sandbroker

A typed-return secret executor. Claude Code causes secrets to be used without ever learning what they are.

Full design, threat model, and hardening guide live in docs/: start with docs/SECURITY.md, docs/THREAT-MODEL.md, and DEPLOY.md. This README is the short version.

The claim

No plaintext secret resolved by sandbroker appears in Claude's context, in the Anthropic API request body, in the local session transcript, or in any prompt cache, because no channel exists through which it could travel.

It does not claim anything about secrets arriving through doors sandbroker doesn't mediate. "100% secure" is not on offer; see the known limits in docs/SECURITY.md.

Why not a redaction hook

A PostToolUse redaction hook is a filter, and filters fail open: unmatched pattern, unexpected encoding, or an unanticipated error string, and the raw value proceeds to the wire. sandbroker is not a filter. The response schema has no field a secret can occupy.

How it holds

Four structural properties, all asserted in tests/test_guarantee.py (30 tests):

1. The child cannot talk to us. Targets spawn with stdout/stderr bound to /dev/null at the fd level, so no output on any path reaches the caller.
2. Secrets never enter argv. Rejected at registry load, because /proc/PID/cmdline exposes argv to the same uid.
3. There is no shell. Argv vectors only, so arguments can never become code.
4. Egress is allowlisted. Response keys outside {ok, error, verb} are dropped and unknown error tokens collapsed.

Install

Two commands on Linux/WSL2 or macOS. First make sure pipx is installed (sudo apt install pipx on Debian/Ubuntu/WSL2, brew install pipx on macOS; a PEP 668 "externally-managed" Python blocks pip install pipx):

pipx install sandbroker        # puts sandbroker, sandbrokerd, and the bin/ helpers on PATH
sandbroker setup               # guided wizard: base + daemon, secret store, approver, Claude Code

sandbroker setup runs unprivileged (user mode) by default; add --hardened for the dedicated-uid /opt/sandbroker system install. See docs/integration-notes/setup-wizard.md.

Quick start from a checkout (Linux/WSL, systemd)

python3 tests/test_guarantee.py                 # expect OK
sudo ./install.sh                               # creates sandbroker uid + claude-broker
install -m 0755 bin/sandbroker ~/.local/bin/sandbroker
install -m 0755 hooks/deny_secret_reads.py ~/.claude/hooks/

# new login session for group membership, then:
sudo ./canary/canary_provision.sh
sandbroker canary.probe --ref file://canary      # expect {"ok": true}
sudo ./canary/canary_sweep.sh                   # expect clean

Then register the PreToolUse hook in your Claude Code settings.json (see docs/ for the snippet).

Ref schemes

op:// refs name an alias from the root-owned vault registry, not a real vault; akv:// and the canary bypass the registry entirely. Which backend to choose, how to wire each one up, and why none of it is editable from the web console: docs/vaults.md.

Layout

sandbroker/sandbrokerd.py   the daemon: exec core, registry validator, egress filter
sandbroker/verbs.json    capability grants; installed root:root 0444
bin/sandbroker          the only interface Claude uses
hooks/                 PreToolUse deny for doors sandbroker doesn't mediate
canary/                provision + sweep: the leak test that must keep passing
tests/                 the guarantee, as executable assertions
install.sh             every sudo step (Linux/systemd)

Verification note

A sweep only means something when Claude runs the probe. Running it yourself proves nothing, because the canary was never near the model's context. Have Claude exercise the verbs and attempt extraction, then sweep.