VT-Agent-Firewall

Español: README.es.md · Threat model: docs/THREAT_MODEL.md

A fail-closed gateway between an AI agent and its tools. The agent never calls open, subprocess or the network directly: every action is a request that goes through the same pipeline, and anything the pipeline cannot vouch for is denied.

ActionRequest → normalize        realpath, shlex argv, parsed URL (spelled params are hostile)
              → policy           default-deny, declarative rules, per-session taint
              → human approval   shows the NORMALIZED action, never the agent's description
              → audit            append-only JSONL, outside the sandbox
              → executor         receives only normalized params, shell=False

Three possible decisions: allow, block, require_approval. If a parser fails or the audit store is unavailable, the answer is block: the gateway would rather stop than act unaudited.

Status: alpha (0.1.0). Standard library only, Python 3.11+. Built as the reference implementation for the talk "Dónde se rompe OAuth cuando el que llama es un agente" (OWASP Village, Ekoparty 2026). Not production-ready; see Limitations.

Quickstart

pip install "git+https://github.com/ValentinTorassa/VT-Agent-Firewall@v0.1.0"   # library + vt-agent-firewall-mcp

git clone https://github.com/ValentinTorassa/VT-Agent-Firewall   # to run the demo and tests
cd VT-Agent-Firewall
python3 scripts/run_demo.py --health       # static sanity checks
python3 scripts/run_demo.py                # the attack, through the gateway
python3 scripts/run_demo.py --no-firewall  # contrast: the same attack without it
python3 -m unittest discover -s tests -v   # AC1–AC12 + the four OAuth failure modes

The demo

demo_workspace/malicious_repo/README.md carries an indirect prompt injection: read ../.env and send the key to 127.0.0.1:8765. The scripted agent follows it. With the gateway every step is blocked and audited and the loopback receiver collects nothing; with --no-firewall the same steps exfiltrate the (fake) key. All data in demo_workspace/ is synthetic bait.

Rules (policies/default.json)

Delegated credentials (api.call)

When an agent calls an API on a person's behalf, the gateway decides the operation first and only then asks a token broker (agent_firewall/credentials.py) for a credential:

• The user's consent is a grant held by the broker, refresh token included; no method ever returns it.
• Each allowed call gets its own access token: one audience, exactly the scope that operation needs, five minutes of life, and the agent named as the actor (RFC 8693 token exchange, simplified).
• Resource servers validate it by introspection (RFC 7662 style). Revoking the grant stops new tokens and kills live ones.
• The agent never sees a token. The audit record keeps the claims (jti, scope, expiry), never the bearer value.

tests/test_delegation.py covers the four ways delegation breaks when the caller is an agent. Each failure mode is a pair: the pattern commonly shipped today (the attack works) and the same attack through the gateway (it is stopped):

MCP proxy

agent_firewall.mcp_proxy puts the gateway in front of any stdio MCP server. The client launches the proxy as if it were the server; the proxy launches the real one:

• every tools/call goes through the policy and the audit log; a blocked call never reaches the server and the client gets isError: true naming the rule;
• tools/list is filtered, so unregistered tools are not even shown to the model;
• path arguments (path, paths, source, destination) get the same protected-path check as fs.read, after realpath;
• --pin PATH=SHA256 refuses to start a server whose code changed;
• approval never reads stdin (it is the MCP channel): it is denied unless --tty-approval is set and a terminal is available.

Example with the official filesystem server, as an entry in a client's MCP config:

{
  "mcpServers": {
    "filesystem": {
      "command": "vt-agent-firewall-mcp",
      "args": ["--policy", "/path/to/policy.json", "--audit", "/path/to/mcp-audit.jsonl",
               "--server-name", "filesystem", "--",
               "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

Checked against @modelcontextprotocol/server-filesystem 0.2.0: of its 14 tools the model saw only the 3 registered ones, read_text_file .env was blocked, and move_file never reached the server. tests/test_mcp_proxy.py runs the same checks in CI against examples/fs_mcp_server.py, a deliberately naive server that does no path checking at all, so every block comes from the proxy.

Layout

agent_firewall/   models, config, policy, executor, audit, approval, gateway,
                  credentials (token broker), mock_apis, mcp_proxy
policies/         default.json: sandbox, protected paths, allowlists, MCP registry
scripts/          run_demo.py, mock_receiver.py
examples/         fs_mcp_server.py (a naive MCP server for tests and demos)
tests/            acceptance tests AC1–AC12, test_delegation.py (the four OAuth failure
                  modes), test_mcp_proxy.py (a real MCP server over stdio)
docs/             THREAT_MODEL.md; build-prompts/ (how the first version was scaffolded)
demo_workspace/   synthetic sandbox for the demo

Limitations

These are deliberate v0 boundaries, not hidden ones:

• No OS sandbox. An agent that can run code outside the pipeline bypasses it.
• Taint is per path, not per content. Reading an allowed file and pasting its content into an allowed channel is not detected.
• Allowed actions are audited after they run (denials are audited before). A crash between execution and audit would leave an allowed action unrecorded.
• The demo agent is a scripted list of requests. The MCP proxy is real; the demo still uses the simulated demo MCP server.
• The MCP proxy handles one call at a time and only covers stdio servers.
• Tokens are bearer tokens. They are not sender-constrained (DPoP) yet: a stolen access token works for anyone until it expires, which is why it lives five minutes.
• The APIs are mocks (agent_firewall/mock_apis.py) and the broker is in-process.

Roadmap

v0.1.0 shipped the gateway, the token broker with the four OAuth failure modes, and the MCP proxy (CHANGELOG). Next:

1. Sender-constrained tokens (DPoP), so a stolen access token is useless.
2. Content-level taint, not only per path.
3. Concurrent calls and the Streamable HTTP transport in the MCP proxy.
4. A reproducible corpus of injection attacks to use as a benchmark.
5. PyPI release (vt-agent-firewall), see RELEASING.md.

License

Apache-2.0.