The Document Nobody Wants to Write

Years ago I pushed an iptables rule that did exactly what I told it to do, which is how I ended up locked out of the box I was trying to protect, on a Saturday, with nobody else awake. The rule was correct. I was wrong. The machine had no way to tell the difference.

That gap between a rule that enforces cleanly and a rule that means what you intended is old news in infrastructure. I've spent twenty-five years inside it: iptables, IAM, RBAC, Terraform, more nginx configs than I want to admit to. What's new is that agent security policy widens the gap considerably, and almost all the energy in agent security is going somewhere else.

Everyone wants to talk about the sandbox. Isolation boundaries, process jails, network proxies. Enforcement is an engineering problem and engineers like engineering problems, because you can build one, test it, and watch it hold. But the runtime does what the policy document tells it to do. When the document is wrong, the runtime enforces the wrong thing with total fidelity and a clean exit code.

Take a rule from OpenShell's policy quickstart. /usr/bin/curl gets access to api.github.com on port 443, with access: read-only. That expands to GET, HEAD, and OPTIONS. A POST to open an issue gets blocked. Precise, enforceable, easy to review in a pull request.

It can also be wrong in a way the sandbox will never catch. read-only is a claim about HTTP verbs. It is not a claim about what the endpoint does when it receives them, and there are plenty of APIs where a GET changes state on the far side. The author wrote a syntactically perfect rule describing the mechanism, and the mechanism was never the thing being constrained. The runtime doesn't know what your application does. The policy has to carry that knowledge, and nothing in the syntax forces the author to think about it.

Credentials make it stranger. OpenShell keeps network reachability separate from credential authorization, so an agent can be allowed to reach an endpoint and still come back with a 403 credential_endpoint_mismatch because the credential binding doesn't cover that destination. Separating those concerns is good hygiene and I'd do the same thing. But the agent doesn't experience two systems. It experiences one permission surface with a hole in it, and the hole produces behavior indistinguishable from a bug. Whoever picks that up at 2 AM has to hold both documents in their head and work out which one is lying.

Config files talk to machines. Runbooks talk to humans. Agent policy has to satisfy three readers simultaneously. The enforcement engine wants binary precision on every request. The agent needs enough room to actually finish the job, and that margin is tighter than it sounds: researchers watched agents fabricate form data, inventing a phone number and a billing address nobody had given them, because the form looked incomplete and the agent treated visual completeness as the objective. The policy said in plain language not to invent values. They did it anyway, because finishing conflicted with complying. And OpenShell's repo has an open issue proposing a second, agent-readable manifest, on the grounds that the enforcement policy is opaque to the agent trying to plan its work. The people building the runtime already know one document can't serve every reader. Nobody has fixed it.

The third reader, the person reconstructing an incident six weeks later, is the one authors drop first. You can record every request and every denial, miss nothing in the telemetry, and still be unable to answer whether a particular action was authorized, because the boundary was never written down clearly enough for the question to have an answer. Ambiguity in the policy becomes ambiguity in the audit. More telemetry doesn't help. I've watched teams try.

Build the sandbox. You need it. But we have decades of collective practice writing configuration and almost none writing documents that must be machine-enforceable, operationally generous, and legible in hindsight all at once. I don't think anyone is good at it yet, me included. That's where the real tradeoffs get decided, and a better runtime won't decide them for you.