koda-sandbox

Capability-aware sandbox layer for Koda. Kernel-enforced FS / network / exec policies, derived from trust mode at compile time.

This crate owns kernel-level sandbox enforcement (Seatbelt on macOS, bwrap on Linux), workspace provisioning, and the egress proxy. It implements the design in #934.

Table of contents

1. Threat model
2. Trust modes
3. Architecture at a glance
4. Per-platform enforcement
5. Defense in depth
6. Escape hatches
7. Configuration philosophy
8. What's enforced today
9. Security boundary tests

Threat model

What we defend against (in scope)

What we explicitly do not defend against (out of scope)

These are accepted risks with documented rationale — not bugs. Changes need an issue + design discussion before tightening, because each one exists to keep legitimate workflows working.

Trust assumptions

• The user is trusted. They invoked koda intentionally. Sandbox protects against LLM-issued actions, not user-issued ones.
• The kernel is trusted. We rely on Seatbelt / bwrap correctness for FS isolation.
• The LLM is not trusted. Treat every tool call as potentially adversarial — the agent might be jailbroken, prompt-injected, or just hallucinating dangerous commands.
• The koda host process is trusted. It runs outside the sandbox and orchestrates worker processes that run inside.
• Worker processes are crash-isolation boundaries. A compromised worker dies; the koda host respawns and continues.

Trust modes

The user's chosen trust mode is the only runtime input that affects sandbox behavior. Every dial in SandboxPolicy is derived from it at compile time via koda_core::sandbox::policy_for_agent. See Configuration philosophy.

Security argument for the depth scaling: more permissive trust mode → less human gating → more paranoid sandbox checking. Auto mode runs without a user in the loop, so the sandbox compensates with the deepest deny-rule traversal.

This invariant is mechanically pinned by the test policy_for_agent_depth_is_strictly_monotone_with_permissiveness in koda-core/src/sandbox.rs.

Architecture at a glance

                 ┌──────────────────────────────────────────────────┐
                 │  koda host process (TRUSTED, runs outside sbox)  │
                 │                                                  │
                 │  • LLM provider calls                            │
                 │  • Tool dispatch                                 │
                 │  • SandboxPolicy construction (policy_for_agent) │
                 │  • SandboxPool slot allocation                   │
                 └────┬───────────────────────┬─────────────────────┘
                      │ spawns                │ spawns
                      │ (Seatbelt/bwrap)      │ (Unix socket IPC)
                      ▼                       ▼
        ┌──────────────────────┐   ┌─────────────────────────────────┐
        │ User command         │   │ koda-fs-worker (crash-isolated) │
        │ (LLM-controlled)     │   │                                 │
        │                      │   │  • Validates Write/Edit ops     │
        │  Kernel-enforced:    │   │    against SandboxPolicy        │
        │  • FS deny rules     │   │  • Receives policy via env var  │
        │  • Network egress    │   │    KODA_FS_WORKER_POLICY (IPC)  │
        │  • Process limits    │   │  • One worker per sandbox slot  │
        └──────────────────────┘   └─────────────────────────────────┘
                      │
                      ▼ outbound traffic
        ┌──────────────────────────────────────┐
        │ Built-in egress proxy (Phase 3)      │
        │  • Domain allow/deny lists           │
        │  • Optional MITM via corporate CA    │
        │  • SOCKS5 fallback for non-HTTP apps │
        └──────────────────────────────────────┘

Dependency direction

koda-cli → koda-core → koda-sandbox
                          │
                          └─ no upward dependency

koda-sandbox knows nothing about Persistence, Provider, or ToolRegistry. Pure infrastructure — testable with assert_eq!(transform(cmd, policy), expected).

Per-platform enforcement

macOS Seatbelt details

• Profile generated dynamically per-policy — see seatbelt::build_profile_string.
• policy_overlay_rules appends user policy after the hardcoded baseline so the baseline (credential paths, koda DB) acts as a floor.
• Optional MITM proxy chaining via build_proxied_profile_string for corporate Zscaler / PKI environments.
• weaker_macos_isolation flag (default false) opts into Apple trustd callbacks for Go-binary TLS verification — costs network sandboxing strength.

Linux bwrap details

• Stage-2 helper (koda-sandbox-stage2) sets up the in-netns TCP↔UDS bridge inside the unshare'd namespace, then execvps the user's command.
• Mount namespace gives true read-only / with carved-out writable roots.
• Network namespace + virtual bridge gives kernel-enforced egress: even binaries that ignore HTTPS_PROXY env vars cannot escape via direct TCP.

Auto mode is fail-closed

When the user picks Auto, koda refuses to start if the kernel sandbox isn't available on the platform (Codex's failIfUnavailable pattern). Rationale: Auto means "no human in the loop" — running without kernel enforcement under those conditions would be reckless.

Defense in depth

The sandbox is not a single fence — it's four concentric ones, each correcting for failure modes the others can't see.

A bypass needs to defeat all four layers, not any one. This is by design — each layer's threat model is documented in its module-level rustdoc.

Escape hatches

These are intentional bypass mechanisms. They exist for specific documented use cases. Each one has a security cost; using one is a deliberate acknowledgement that the user accepts that cost.

--no-sandbox flag

Disables kernel sandbox entirely. Used for:

• Debugging the sandbox itself when developing koda-sandbox.
• Platform-unsupported environments (CI containers without bwrap).
• Reproducing customer-reported bugs where the user can't run with sandbox.

Cost: No FS / network / exec enforcement. Only the trust-mode approval gate stands between the LLM and your filesystem. Plan mode still rejects mutations, but Safe and Auto allow whatever the LLM asks for.

fs.allow_git_config = true

Permits writes to git config. Off by default because git config core.fsmonitor can register a hook that runs arbitrary code on the next git status → RCE.

Cost: Trades sandbox containment for git config ergonomics. Only opt in for workflows that genuinely need to modify git config (rare).

net.weaker_macos_isolation = true

macOS-only. Permits Apple trustd mach lookups so Go binaries can verify TLS.

Cost: Widens the network sandbox surface. Opt in if Go binaries don't work otherwise.

MITM CA bundle (mitm.ca_bundle)

Configures the egress proxy to terminate TLS using a corporate CA (Zscaler, internal PKI). Used for environments where the corporate proxy is mandatory and inspects HTTPS.

Cost: All HTTPS traffic from sandboxed processes is decrypted and re-encrypted by koda. The proxy still applies domain allow/deny rules — MITM is enforcement, not an escape — but it materially expands what koda's process can see.

failIfUnavailable = false (implicit, for Plan/Safe modes)

Plan and Safe modes start without a kernel sandbox if the platform doesn't support one. Auto mode requires kernel enforcement.

Cost: Plan/Safe rely entirely on app-layer path defense + the approval gate when no kernel sandbox is available. Trust mode is the safety net.

Configuration philosophy

Koda is config-free at runtime.

Every behavioral dial in SandboxPolicy is derived at compile time from the trust mode (Plan / Safe / Auto) via koda_core::sandbox::policy_for_agent. There is no JSON config file, no CLI override, no env-var dial that the user can twiddle.

Why. Config knobs are foot-guns:

• They turn into compatibility liabilities the moment they ship.
• They force users to make security decisions they're not equipped to make.
• They drift from documented defaults, breaking the threat model silently.

If a behavioral change is justified, it goes into policy_for_agent (a compile-time table keyed off trust mode), not into a config file.

One legitimate exception: IPC

SandboxPolicy keeps its serde::Deserialize impl because the crash-isolated koda-fs-worker process needs to receive the policy across the process boundary (via KODA_FS_WORKER_POLICY env var as JSON). This is IPC, not config — the host built the policy in-memory via policy_for_agent; the JSON is just the wire format.

To prevent this IPC channel from morphing into a config loader by accretion, the test sandbox_policy_deserialize_only_used_in_fs_worker_binary walks the workspace and fails the build if any file other than the worker binary deserializes a SandboxPolicy. A future contributor adding a config loader gets a red CI build with a teaching moment baked in.

What's enforced today

Honest accounting of which fields actually do something vs. are declared-but-not-yet-enforced. This list is meant to drift downward over time as enforcement code lands.

Declared-only fields are intentionally inert; setting them today has no runtime effect. They're included in SandboxPolicy so the type contract stays stable while enforcement lands incrementally.

Security boundary tests

Each load-bearing claim in this README is pinned by a test. If you change the corresponding behavior, expect to update the test by name — that's the point.

Adding a new defended threat? Add a test next to the relevant module and update this table. Removing a defended threat? Update the threat model table first, then remove the test.

Phase status

This crate is the kernel-enforcement implementation of issue #934. Phase 5 (current) wraps sub-agent policy composition + the per-trust derivation. PR-6 (next) wires declared-only resource limits to actual rlimit / SBPL enforcement.

For the full design rationale, threat-model evolution, and per-phase acceptance criteria, see the issue.