8.2 Sandbox & Security - Claude Code Deep Dive

1

🏗️ Sandbox Architecture

macOS

Apple Seatbelt (sandbox-exec). Zero install, only ripgrep needed.

Linux/WSL2

bubblewrap (bwrap) + seccomp + socat.

WSL1/Windows

Not supported. /sandbox command hidden.

💡 Thin Adapter

Claude Code translates its settings/permission system into SandboxRuntimeConfig. All actual process isolation delegated to @anthropic-ai/sandbox-runtime.

2

🛠️ Three Sandbox Modes

Disabled

All commands run unsandboxed. Permission prompt for each new pattern.

Regular (sandboxed)

OS isolation. Still asks permission for commands outside pre-approved list.

Auto-Allow (sandboxed)

Commands auto-approved without prompt. Maximum productivity.

💡 Two Booleans

Derived from sandbox.enabled and sandbox.autoAllowBashIfSandboxed. Written to localSettings.

3

🌐 Network Control

Allowed domains from sandbox.network.allowedDomains and WebFetch permission rules. Denied domains from permissions.deny patterns.

💡 Enterprise Lockdown

allowManagedDomainsOnly: true means only policySettings domains used. User-level allow rules in localSettings ignored entirely.

4

📁 Filesystem Control

Always writable: CWD and Claude temp dir. Always denied: all settings.json files, .claude/skills (skill injection prevention), bare git repo sentinels (core.fsmonitor escape vector).

💡 Bare Git Repo Escape

Git treats any dir with HEAD + objects/ + refs/ as bare repo. Sandboxed command could plant these, then git loads attacker-controlled core.fsmonitor hook. Defended by deny-write + post-command scrub.

5

🔒 Secure Storage

macOS Keychain

Credentials hex-encoded via security -i (stdin). 30s TTL cache with stale-while-error.

Startup Prefetch

Two security subprocesses fired in parallel at top of main.tsx, saving ~65ms.

Plaintext Fallback

~/.config/claude/.credentials.json with chmod 0o600. Warning on every write.

Fallback Combinator

Deletes stale primary after successful fallback write to prevent login loops.

6

🚨 Violation Reporting & Live Refresh

Violations stored in SandboxViolationStore. Two UI surfaces: stderr annotation and SandboxDoctorSection with suggestions. Sandbox config refreshes live via settingsChangeDetector - no restart needed.

💡 Startup Warning

If sandbox.enabled: true but dependencies missing, visible warning at startup. Silent failure would be a security footgun.

🗺️ Diagrama de Arquitetura

flowchart TD CC["Claude Code\n(sandbox-adapter.ts)"] --> |"convertToSandboxRuntimeConfig()"| CFG["SandboxRuntimeConfig\n{ network, filesystem, ripgrep ... }"]
CFG --> BSM["BaseSandboxManager\n(@anthropic-ai/sandbox-runtime)"]
BSM -->|macOS| SB["seatbelt\n(sandbox-exec)"]
BSM -->|Linux/WSL2| BW["bubblewrap (bwrap)\n+ seccomp filter\n+ socat proxy"]
SB --> PROC["sandboxed\nprocess"]
BW --> PROC

📋 Resumo do Modulo

✅ Sandbox adapter is thin bridge to @anthropic-ai/sandbox-runtime with two platform backends.

✅ Three modes: disabled, regular (ask), auto-allow (sandbox provides safety).

✅ Settings files and .claude/skills always denied write access to prevent sandbox escape.

✅ Bare git repo sentinels scrubbed after each command to block core.fsmonitor escape vector.

✅ macOS keychain: hex-encoded, stdin-based, 30s TTL cache with stale-while-error.

✅ Fallback combinator deletes stale primary entry after successful plaintext write.