sandbox-exec: The Missing Handbook — Index

---

Part I: Foundations

• Chapter 1: sandbox-exec and the macOS Sandbox
  • 1. What Is sandbox-exec?
    • The interface in one sentence
    • Origins: the Seatbelt codename
    • Where sandbox-exec fits in macOS security architecture
  • 2. How It Works Under the Hood
    • The enforcement path: MAC hooks
    • Userland compilation: TinyScheme and libsandbox
    • The binary profile format: policy as a directed acyclic graph
    • The sandboxd daemon
  • 3. Writing Your First Profile
    • SBPL fundamentals
    • Core operations
    • Filters
    • Meta-filters
    • A minimal default-deny profile
    • A profile with controlled writes and outbound HTTPS
    • Authoring workflow
    • Common pitfalls
    • Reading the denial logs
  • Summary

---

Part II: The macOS Security Landscape

• Executive Summary
• Architecture and Terminology
  • The Terminology Trap
• Enforcement Flow and Code-Signing Mechanics
  • When Sandbox Restrictions Take Effect
  • The Low-Level Path: sandbox_init and sandbox-exec
  • The App Sandbox Path: Entitlements Drive Policy Generation
  • Enforcement Flow: App Sandbox at Launch
  • Enforcement Flow: Conceptual Diagram
• Entitlements vs SBPL: What They Can and Cannot Replace
  • How Entitlements Relate to SBPL
  • Mapping Table: Common Entitlements to Likely SBPL Features
  • What Entitlements Cannot Express
  • Temporary Exception Entitlements
• XPC and Privilege Separation Patterns
• sandbox-exec: Deprecated — But Not Gone
  • What Deprecation Means in Apple's Own Words
  • Timeline
  • Why Apple Deprecated sandbox-exec
  • Why It Remains Widely Used
• Risks, Mitigations, and Practical Recommendations
  • Risk Landscape
  • Mitigation Patterns
  • Use-Case Comparison
  • Actionable Checklist
• What Is Known, What Is Inferred, What Is Undocumented

---

Part III: sandbox-exec in the Real World

• 3.1 Who Actually Uses sandbox-exec
• 3.2 What "Deprecated" Actually Means Here
• 3.3 How Real Projects Structure Their Profiles
  • The two baseline models
  • Rule evaluation: last match wins
  • Parameterization
  • Regex, subpath, and literal filters
• 3.4 Filesystem Controls
• 3.5 Network Controls
• 3.6 Process Controls
• 3.7 System Service Access (Mach)
• 3.8 Real Project Implementations
  • OpenAI Codex
  • Anthropic sandbox-runtime
  • Bazel Darwin sandbox runner
  • claudebox
• 3.9 Invocation Patterns
  • Profile via -p (inline string)
  • Profile via -f (file on disk)
  • Hardcoded path
• 3.10 Profiles for Common Scenarios
  • Read-only with no network
  • Workspace-write with no network
  • Exec allowlist
• 3.11 Verifying That Your Profile Works
  • Capability probe
  • Behavioral unit tests
  • Log monitoring for denials
  • PolicyWitness
• 3.12 Common Pitfalls
• 3.13 sandbox-exec in the AI Agent Stack
• 3.14 How Browsers Use SBPL
• 3.15 Security Properties and Limits
• 3.16 Alternatives and Migration Planning
• 3.17 Decision Checklist

---

Part IV: Limits and Alternatives for macOS and Linux Isolation

• The Central Thesis
• 4.1 What sandbox-exec Cannot Do
  • Threat model
  • Seatbelt is a reference monitor, not a virtual machine
  • It does not virtualize the machine or the kernel
  • It cannot reliably capability-ize filename-based authority
  • Mach services are a privileged attack surface
  • Attack patterns
    • Allowed Mach service → sandbox escape
    • TOCTOU on a mountpoint or symlink
    • CVE-class sandbox restriction bypasses
  • Policy design mitigations
  • Minimal SBPL profile pattern
• 4.2 macOS vs Linux Isolation
  • What Linux namespaces actually provide
  • overlayfs
  • seccomp as syscall filtering
  • Docker on macOS is not Linux namespaces on macOS
  • Comparative isolation properties
  • Sharp edges
  • Docker hardening
  • bubblewrap baseline pattern
• 4.3 Alternatives and Workarounds
  • Throwaway user identities
  • WebAssembly and WASI capability sandboxes
  • VM-based isolation
• 4.4 Defense-in-Depth by Construction
  • Selection logic
  • Design principles
  • Alternatives comparison
• 4.5 The Deprecation Question, Revisited
• 4.6 Summary