agent-guardrail
A runtime gate for autonomous coding agents. It runs as an MCP server in the tool-call path between the agent and your repo, so every run_shell / write_file / git call is checked before it executes. It stops the actions that wreck a repository (force-pushing main, rm -rf the working tree, exfiltrating a secret, wiping CI) and lets normal build and commit work through, without trusting the agent to behave. As a bonus, its git-branch sub-policy is machine-checked by z3, which is a property almost no guardrail has: the policy can check itself for gaps. Everything else is high-precision heuristics, and this README is explicit about which is which.
Coding agents (Copilot Workspace, SWE-agent, OpenHands) now open PRs, run shell, and rewrite git history on their own. Their safety today rests on the model behaving: prompt guardrails and alignment. That is probabilistic and model-dependent. A well-aligned model may refuse a prompt injection; a jailbroken or weaker one will not. agent-guardrail is the deterministic layer that does not depend on the model: it checks every tool call before it runs, so a compromised agent is stopped regardless of why it issued the action.
What is proven vs. what is heuristic
Being precise about this up front, because it is the whole point:
| Threat | How it is enforced | Guarantee |
|---|---|---|
| Force-push / hard-reset / rebase of a protected branch | structured git policy | machine-checked by z3 (see below) |
rm -rf of the repo / home / root |
regex over the command | heuristic, high-precision, bypassable by obfuscation |
| Secret written to disk or exfiltrated over the network | regex (secret shape + sink) | heuristic |
| Emptying a CI workflow file | path + content check | heuristic |
| Everything else a build/test agent does | default allow | not policed (by design) |
"Heuristic" means it catches the direct forms and is intentionally bypassable by a determined obfuscator (rm -r -f, $IFS, base64, aliases). It raises the cost of an accident or a naive injection; it is not a sandbox. For hard isolation, pair it with seccomp/gVisor (see "How it compares").
The demo (measured, reproducible)
The same destructive tool-call sequence a hijacked agent emits, run with and without the gate on a real repo (demo_compare.py):
.git intact |
secret on disk | CI config intact | legit fix still applied | |
|---|---|---|---|---|
| without the gate | destroyed | leaked | wiped | yes |
| with the gate | yes | none | yes | yes |
6 of 6 destructive actions blocked, 2 of 2 legitimate actions allowed, in the real execution path.
A machine-checked core (a credibility detail, not the main defence)
This covers the narrowest surface, protected-branch history, which server-side pre-receive hooks also guard, so it is not where most of the value is. It is here because it is unusual: a hand-written allowlist cannot tell you whether it has a hole, and this policy can. Using z3, it proves over the symbolic class of git actions:
guard_allows(a) implies not mutates_protected_history(a)
with the safety spec written independently of the guard, not copied from it, so the result is not circular. It returns PROVED, or a concrete counterexample. Remove one rule and it finds the exact hole:
full policy : PROVED (no admitted action rewrites protected history)
drop the rebase rule : HOLE op=rebase branch=main
This guarantee covers the structured git tool-call path only. It does not verify the Python implementation, the regex rules, or the shell parser.
How it compares
| Tool | Layer | Catches | Why this is different |
|---|---|---|---|
git server-side hooks (pre-receive) |
git server | bad pushes, once they reach the server | agent-guardrail gates the action before it runs locally, and covers file/shell too, not just pushes |
| seccomp / gVisor | syscall / kernel | syscall-level isolation | strong isolation, but no notion of "protected branch" or "this is a secret"; complementary, not a substitute |
| OPA / policy engines | request / API | structured policy decisions | general policy, no formal self-check of the policy and no coding-agent action model out of the box |
| CodeQL / Copilot Autofix | static analysis | vulnerabilities in code | analyses code at rest; says nothing about what an agent does to the repo at runtime |
| git hooks + a shell allowlist | local | some of the same patterns | cannot prove the policy is gap-free; this is the piece z3 adds |
Short version: this is not a sandbox and not a linter. It is an action-level gate for coding agents, with a formally checked core for the one sub-policy where a proof is tractable. Use it in front of a sandbox, not instead of one.
Validated for false friction (not for attack detection)
A gate that blocks legitimate work gets turned off after two pull requests, so the thing worth measuring is how often it blocks real developer commands. It was run over 2,836 real run: commands from 12 trusted repos (rust-lang/rust, tokio, denoland/deno, ripgrep, cargo, ruff) read-only, nothing executed (realworld_test.py):
| version | false blocks | escalations | allows |
|---|---|---|---|
| v0 (fail-closed on any metacharacter) | 2 (both legit CI) | 1854 (65%) | 35% |
| v0.1 (default-allow, block the threat model) | 0 | 0 | 100% |
It was then re-run on a larger, less hand-picked sample to check for selection bias: 3,790 real commands from 49 of the most-starred repos across 9 languages (react, next.js, tensorflow, ollama, godot, deno, rust, and more), gathered by GitHub-search rank, not chosen by hand (scripts/expanded_realworld.py). Result: 99.9% allow, 0 false blocks, 2 correct escalations (a force-push and a rebase whose branch is a CI variable, so the gate cannot tell if it is protected and asks a human).
That bigger sample earned its keep: it caught four false positives the small one missed (rm -f ../private.key and rm -rf ./bin/build_deps, a specific file and a sub-path, which the rm rule was over-matching as repo destruction). Fixed, and all four are now regression tests. This is why the number is trustworthy: it was tested on code it did not choose, and the failures it found were fixed rather than hidden.
Read this honestly: with a default-allow design, a low false-block rate on legitimate commands is the target, not a surprise. The value of the corpus is the opposite failures it surfaces (v0 was fail-closed and blocked two-thirds of normal CI; the rm rule over-matched real sub-path deletes) and that they get fixed. This corpus does not measure attack detection; it contains no adversarial commands. Attack behaviour is covered by the demo and the tests, not by this number.
Assumptions and limits
- The gate must be out-of-process from the agent. If the agent can edit the guardrail or read the HMAC key, it can bypass or forge. The audit chain is tamper-evident only under the assumption that the key is not accessible to the agent (a wrapper process or separate service, not an in-process import the agent controls). See THREAT_MODEL.md.
- Shell coverage is best-effort. A determined attacker obfuscates around the regexes. Treat shell blocking as defense-in-depth, not a boundary.
- A well-aligned agent will often refuse an injection on its own. In
demo_hijack.pya real Claude agent read the planted note and declined it. The gate's value is being the deterministic backstop for when alignment fails. - Integration is via MCP (see below). The formal guarantee still covers only the git-branch policy wherever the gate runs.
Use it with any MCP agent
The gate runs as an MCP server, the tool-callsurface that Claude Desktop, Cursor, Copilot, and Windsurf all speak. Point an MCPclient at it and every run_shell / write_file / git call the agent makes isgated in the protocol path, before it touches the repo. No trust in the agent.
This holds only if the MCP server is the agent's only route to shell, git, andfiles. An agent that also has an unguarded raw shell, or that can edit the serverfile, bypasses the gate. Run it out-of-process and give the agent no otherexecution path. See THREAT_MODEL.md.
// in your MCP client config (Claude Desktop, Cursor, ...)
"agent-guardrail": {
"command": "python3",
"args": ["/path/to/agent-guardrail/integrations/mcp_server.py"],
"env": { "GUARDRAIL_WORKSPACE": "/path/to/your/repo" }
}
integrations/demo_mcp.py demonstrates this end-to-end: it launches the server andconnects as a real MCP client over stdio (the same transport those apps use), thenissues a mix of legitimate and destructive tool calls. The destructive ones areblocked inside the protocol:
Tools exposed to the agent via MCP: run_shell, write_file, git, audit_log
▶ write_file('calc.py') wrote calc.py (the fix)
▶ git('add calc.py') ok
⛔ git('push origin main --force') BLOCK force-push to protected branch 'main'
⛔ run_shell('rm -rf .git') BLOCK recursive delete of the repo
⛔ write_file('config.py' w/ token) BLOCK writing a secret to disk
⛔ run_shell('curl ... -d ghp_...') BLOCK secret exfiltration over the network
⛔ write_file('.github/workflows/...') BLOCK emptying CI config
▶ run_shell('cargo build --release') allowed
blocked: 5 allowed: 4 .git intact, no secret, CI intact, fix applied, audit chain verifies
Run it
pip install z3-solver "mcp"
python3 tests/test_guardrail.py # 10 tests
python3 demo_compare.py # with and without the gate, on a real repo
python3 integrations/demo_mcp.py # the gate in a real MCP tool-call path
python3 realworld_test.py # the 2,836-command friction check (needs gh)
ANTHROPIC_API_KEY=... python3 demo_hijack.py # a real Claude agent meets a planted injection: it declines, and the gate stands behind it
The interception itself (an attack actually being blocked) is shown by demo_compare.py and integrations/demo_mcp.py. demo_hijack.py shows the complementary case: a well-behaved real agent, where the gate adds no friction and waits as the backstop.
Status
Early, single author, honest about scope. Feedback and holes in the policy are welcome, especially holes. See THREAT_MODEL.md and SECURITY.md.
MIT License.
