# CrabTrap

CrabTrap is Brex's open-source approach to running AI agents in production without losing the plot on what they're allowed to do. It runs as an HTTP proxy between the agent and every upstream service: agent traffic flows through CrabTrap, which evaluates each request against a policy and either allows or blocks it in real time. Two judgment layers — static rules (fast path) and an LLM-as-a-judge evaluation (everything else).

## What it does

The agent is configured to route its HTTP traffic through CrabTrap as an MITM proxy. CrabTrap requires a CA cert install during setup (via `./scripts/generate-certs.sh`) so it can intercept TLS. For each intercepted request:

1. **Static rules** match first — URL patterns, method, destination hostname, header values. Deterministic allow/deny.
2. **LLM judge** evaluates anything that doesn't hit a static rule. The policy is written in plain English — e.g.: *"The agent is a code assistant that uses GitHub for issues, post messages, and read repository data. It should never delete repositories, send emails to external addresses, or send messages on Slack."*
3. The decision plus reasoning is logged and either the request proceeds or gets blocked.

## Why this design

The alternative approaches have known gaps:

- **Sandbox-based controls** ([[hazmat]], [[bubblewrap-dev-env]]) block filesystem, process, and sometimes network egress at the OS layer. But HTTPS on port 443 is essentially unblockable without breaking API calls, so an agent inside a sandbox can still exfiltrate data to any server that speaks TLS — [[hazmat]] explicitly acknowledges this gap.
- **Prompt-level controls** (system prompt says "don't delete repos") are trivially bypassable by a sufficiently adversarial context and depend on the agent's reasoning staying aligned.
- **Per-tool allow-lists** work when the agent uses MCP-style structured tools but break down the moment the agent shells out to curl.

CrabTrap's move is to intercept at the HTTP layer where the actual action happens — the moment the agent is about to hit the GitHub delete-repo endpoint, you can inspect the URL, method, and body and decide. That's independent of how the agent was configured or what reasoning it did to get there.

The LLM-judge step is the expensive-but-flexible piece: natural-language policy means the operator doesn't have to enumerate every allowed URL pattern, but each request incurs a judgment call. The static-rules-first pipeline keeps throughput reasonable by short-circuiting deterministic cases.

## Tradeoffs

- **Requires CA cert install.** The proxy has to decrypt TLS, which means the trust root is now whatever CrabTrap's key hygiene is. Lose the CA private key and anything the agent trusted is compromised.
- **LLM judge adds latency.** Every non-static-rule request waits for a policy evaluation. On hot paths this bites.
- **Policy has to be curated.** "The agent should never delete repos" is a reasonable policy; "the agent should make good decisions" is not. The quality of the policy determines the quality of the decisions.
- **Agent can still exfiltrate through allowed endpoints.** If GitHub issue creation is allowed, the agent can post stolen secrets in an issue title. CrabTrap stops the obvious moves, not the clever ones.

## Where this fits

In the [[sandboxing-ai-agents]] taxonomy, CrabTrap is the *network-layer, policy-driven* quadrant — distinct from filesystem sandboxes like [[hazmat]] and [[bubblewrap-dev-env]], distinct from syscall-level tools like [[syscall-binary-rewriting]], distinct from context-management tools like [[ctx]]. It pairs well with any of those: defense-in-depth rather than replacement.

The LLM-judge pattern itself is reusable — it's a general technique for policy enforcement when the policy is easier to write in English than as code. The same pattern shows up in content moderation stacks and in tool-use filters for agents.

## Repo

https://github.com/brexhq/CrabTrap — Brex-originated, open-source. Setup via `make setup` after cloning, which runs cert generation and UI build. Demo site at [brex.com/crabtrap](https://www.brex.com/crabtrap) with an interactive policy editor and request-decision visualiser.

## Related

- [[hazmat]], [[bubblewrap-dev-env]] — filesystem-level sandboxing; complementary, not substitute
- [[sandboxing-ai-agents]] — the broader concept covering layers of control
- [[charlie-daemons]] — different angle on production agents: autonomous background processes that need similar constraints
- [[supply-chain-security]] — same spirit of "define what's allowed, block everything else"