5. Permission & Security Model

Confidence: 100% (Tier 1 - Official) Sources:

• code.claude.com/docs/en/hooks
• code.claude.com/docs/en/sandboxing

Claude Code has a layered security model:

┌─────────────────────────────────────────────────────────────┐
│                    PERMISSION LAYERS                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Layer 1: INTERACTIVE PROMPTS                               │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Claude wants to run: rm -rf node_modules               │ │
│  │ [Allow once] [Allow always] [Deny] [Edit command]      │ │
│  └────────────────────────────────────────────────────────┘ │
│                          │                                  │
│                          ▼                                  │
│  Layer 2: ALLOW/DENY RULES (settings.json)                  │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ {                                                      │ │
│  │   "permissions": {                                     │ │
│  │     "allow": ["Bash(npm *)", "Read"],              │ │
│  │     "deny": ["Bash(rm -rf *)"]                         │ │
│  │   }                                                    │ │
│  │ }                                                      │ │
│  └────────────────────────────────────────────────────────┘ │
│                          │                                  │
│                          ▼                                  │
│  Layer 3: HOOKS (Pre/Post execution)                        │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ PreToolUse: Validate before execution                  │ │
│  │ PostToolUse: Audit after execution                     │ │
│  │ PermissionRequest: Override permission prompts         │ │
│  └────────────────────────────────────────────────────────┘ │
│                          │                                  │
│                          ▼                                  │
│  Layer 4: SANDBOX MODE (Optional isolation)                 │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Filesystem isolation + Network restrictions            │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Dangerous Pattern Detection

Confidence: 80% (Tier 2 - Observed but not exhaustive)

Claude Code appears to flag certain patterns for extra scrutiny:

Pattern	Risk	Behavior
rm -rf	Destructive deletion	Always prompts
sudo	Privilege escalation	Always prompts
curl | sh	Remote code execution	Always prompts
chmod 777	Insecure permissions	Always prompts
git push --force	History destruction	Always prompts
DROP TABLE	Data destruction	Always prompts

This is not a complete blocklist. Patterns are likely detected through model training rather than explicit rules.

Native Sandbox (v2.1.0+)

Confidence: 100% (Tier 1 - Official) Source: code.claude.com/docs/en/sandboxing

Claude Code includes built-in native sandboxing using OS-level primitives for process-level isolation:

┌──────────────────────────────────────────────────────┐
│               Native Sandbox Architecture            │
├──────────────────────────────────────────────────────┤
│                                                      │
│  Bash Command Request                                │
│       │                                              │
│       ▼                                              │
│  Sandbox Wrapper (Seatbelt/bubblewrap)               │
│       │                                              │
│       ├─ Filesystem: read all, write CWD only        │
│       ├─ Network: SOCKS5 proxy + domain filtering    │
│       ├─ Process: isolated environment               │
│       │                                              │
│       ▼                                              │
│  OS Kernel Enforcement                               │
│       │                                              │
│       ├─ Allowed: operations within boundaries       │
│       ├─ Blocked: violations at system call level    │
│       └─ Notify: user receives alert on violation    │
│                                                      │
└──────────────────────────────────────────────────────┘

OS Primitives:

Platform	Mechanism	Notes
macOS	Seatbelt (TrustedBSD MAC)	Built-in, kernel-level system call filtering
Linux/WSL2	bubblewrap (namespaces + seccomp)	Requires: sudo apt-get install bubblewrap socat
WSL1	❌ Not supported	bubblewrap needs kernel features unavailable
Windows	⏳ Planned	Not yet available

Isolation Model:

1. Filesystem:

   • Read: Entire computer (except denied paths)
   • Write: Current working directory only (configurable)
   • Blocked: Modifications outside CWD, credentials directories (~/.ssh, ~/.aws)

2. Network:

   • Proxy: All connections routed through SOCKS5 proxy
   • Domain filtering: Allowlist/denylist mode
   • Default blocked: Private CIDRs, localhost ranges

3. Process:

   • Shared kernel: Vulnerable to kernel exploits (unlike Docker microVM)
   • Child processes: Inherit same sandbox restrictions
   • Escape hatch: dangerouslyDisableSandbox parameter for incompatible tools

Sandbox Modes:

• Auto-allow mode: Bash commands auto-approved if sandboxed (recommended for daily dev)
• Regular permissions mode: All commands require explicit approval (high-security)

Security Trade-offs:

Aspect	Native Sandbox	Docker Sandboxes (microVM)
Kernel isolation	❌ Shared kernel	✅ Separate kernel per VM
Setup	0 deps (macOS), 2 pkgs (Linux)	Docker Desktop 4.58+
Overhead	Minimal (~1-3% CPU)	Moderate (~5-10% CPU)
Use case	Daily dev, trusted code	Untrusted code, max security

Security Limitations:

⚠️ Domain fronting: CDNs (Cloudflare, Akamai) can bypass domain filtering ⚠️ Unix sockets: Misconfigured allowUnixSockets grants privilege escalation ⚠️ Filesystem: Overly broad write permissions enable attacks on $PATH directories

When to use:

• ✅ Native Sandbox: Daily development, trusted team, lightweight setup
• ✅ Docker Sandboxes: Untrusted code, kernel exploit protection, Docker-in-Docker needed

Deep dive: See Native Sandboxing Guide for complete technical reference, configuration examples, and troubleshooting.

Hooks System

Hooks allow programmatic control over Claude's actions:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "/path/to/validate-command.sh"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [{
          "type": "command",
          "command": "/path/to/audit-log.sh"
        }]
      }
    ]
  }
}

Hook capabilities:

Capability	Supported	How
Block execution	Yes	Exit code 2
Modify parameters	Yes	Return modified JSON
Log actions	Yes	Write to file in hook
Async processing	Yes	Set async: true in hook config (v2.1.0+)

Hook JSON payload (passed via stdin):

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm install lodash"
  }
}

Common fields sent to all events: session_id, transcript_path, cwd, permission_mode, hook_event_name. Event-specific fields (e.g., tool_name/tool_input for PreToolUse) are added on top.

→ Cross-reference: See Section 7 - Hooks in the main guide for complete examples.