Architecture

Three-Layer Defense

BlastShield provides defense in depth through three complementary layers, each handling what the layer above cannot.

┌─────────────────────────────────────────────────┐
│                  AI Agent                        │
│  (Claude Code, Codex, Cursor, Gemini, etc.)     │
└──────────────────┬──────────────────────────────┘
                   │
    ┌──────────────┼──────────────────┐
    │              ▼                   │
    │  Layer 2: blastshield-guard      │
    │  (command-argument filter)       │
    │  • Intercepts destructive        │
    │    subcommands via PATH wrappers │
    │  • Requires Touch ID / password  │
    │  • Passes safe commands through  │
    └──────────────┬──────────────────┘
                   │
    ┌──────────────┼──────────────────┐
    │              ▼                   │
    │  Layer 1: blastshield            │
    │  (sandbox-exec profiles)         │
    │  • Kernel-enforced file policy   │
    │  • Blocks credential reads       │
    │  • Blocks state file writes      │
    │  • Protects backend configs      │
    └──────────────┬──────────────────┘
                   │
    ┌──────────────┼──────────────────┐
    │              ▼                   │
    │  Layer 0: agent's built-in       │
    │  sandbox (Claude /sandbox,       │
    │  Codex approval policies)        │
    │  • Tool-level gating             │
    │  • Network filtering             │
    └──────────────┬──────────────────┘
                   │
                   ▼
              macOS Kernel

Layer 0: Agent’s Built-in Sandbox

The agent itself may provide a sandbox (e.g. Claude’s /sandbox, Codex’s approval policies). These operate at the tool level — they gate the agent’s own tools and network access.

Limitation: These only gate their own tools. An agent that shells out via Bash or Python bypasses all of it. A determined agent can simply run a subprocess that the agent sandbox never sees.

Layer 1: blastshield — Kernel-Level Sandbox

This is the hard boundary. BlastShield uses macOS sandbox-exec (Apple Seatbelt) to enforce filesystem and process restrictions at the kernel level. The kernel doesn’t care what the agent thinks it’s allowed to do.

How It Works

1. Profile Assembly — BlastShield combines multiple SBPL (Seatbelt Profile Language) profiles into a single policy
2. Deny-by-default — The assembled profile starts with (deny default), then adds only necessary allow rules
3. Profile intersection — Every deny rule from every loaded profile is enforced; profiles compose by intersection
4. Kernel enforcement — sandbox-exec -f <profile> -- <command> runs the agent process inside the sandbox

What It Blocks

• Credential file reads — The agent process physically cannot read ~/.aws/credentials, ~/.azure/, GCP service account keys, etc.
• State file writes — Cannot modify Terraform state, Helm chart locks, or backend configurations
• Protected path access — Each profile defines its own set of protected paths

What It Cannot Block

sandbox-exec operates at the file/process level. It cannot filter by command arguments. It cannot distinguish terraform destroy from terraform plan — both execute the same terraform binary. That’s where Layer 2 comes in.

Layer 2: blastshield-guard — Command-Argument Filter

This layer handles what sandbox-exec cannot see: which subcommands the agent invokes.

How It Works

1. PATH wrappers — blastshield automatically creates temporary wrapper scripts for each guarded CLI found on PATH
2. Intercept — When the agent runs terraform destroy, the wrapper (found first on PATH) intercepts it
3. Block — Destructive subcommands are blocked inside the agent sandbox
4. Pass-through — Non-destructive commands execute immediately without interruption

Guarded Commands

CLI	Destructive Pattern
terraform	destroy
gcloud	delete
aws	delete*
az	delete
kubectl	delete
gh	delete

Important Note

Layer 2 is a speed bump, not a hard boundary. A determined agent that specifies the full path to a CLI (e.g. /usr/local/bin/terraform destroy or ./bin/terraform destroy) bypasses PATH wrappers. Runtime wrappers cover Hermit and repo-local shims when they are invoked by command name. Layer 1 (sandbox) is the hard boundary — it blocks credential access regardless of how the CLI is invoked.

Why Both Layers?

Scenario	Layer 1 (sandbox)	Layer 2 (guard)
Agent reads ~/.aws/credentials directly	✅ Blocked	❌ Not visible
Agent runs terraform destroy	❌ Same binary as terraform plan	✅ Intercepted
Agent uses full path /usr/local/bin/terraform destroy	❌ Same binary	❌ Bypassed
Agent runs aws s3 rb with already-loaded credentials	❌ Creds already in env	✅ Intercepted
Agent exfiltrates secrets via network	⚠️ Only if -c used	❌ Not visible

The layers are complementary — neither is sufficient alone. Use both for defense in depth.