Skip to main content

agent-firewall

Fail-closed MCP tool-call firewall for AI agents.
Give your agent's MCP tools a local firewall — deny by default, allowlist only, every verdict hash-chained.

pip install frt-agent-firewall       # zero deps, Python 3.9+

GitCode GitHub tests license python

agent-firewall is a zero-dependency Python library that sits between an MCP client and its server and inspects every tools/call message on the wire. It is part of the Verifiable-agent family — same design language as agent-call-audit, agent-memory-ledger, agent-audit-gateway, agent-route-grid.

⚠️ Research prototype — AI-assisted development. This is an open-source research/experimental prototype produced with AI assistance. It is provided AS IS, without warranty of any kind, and is not a commercial or production-grade product. Use at your own risk.

Verifiable-agent family

Repo Role
agent-firewall MCP tool-call firewall (this repo)
agent-call-audit audit engine
agent-memory-ledger verifiable memory layer
agent-audit-gateway HTTP gateway
agent-route-grid audited multi-agent routing

Why

MCP servers hand your agent arbitrary tool access. A single shell.exec or db.query call with user-controlled arguments is enough to lose a machine or a database. The ecosystem's answer has been security gateways in Go — but if you are already on Python and want provable, auditable enforcement (not just a wall), this is the lightweight, dependency-free option.

What you get:

  • Deny by default — empty policy denies every tool call (fail-closed).
  • Blocklist beats allowlist — blocked_tools and argument-level red lines always win.
  • Argument-level red lines — regex against a JSON path inside arguments (e.g. reject path=/etc/*, reject SQL injection probes).
  • Tamper-evident trail — every verdict appends to a JSONL hash chain; verify_trail() detects any tampering.
  • Privacy by default — raw tool arguments are never persisted, only a sha256 of the canonical payload.
  • Rules are data — policy is a JSON file, not hard-coded.
  • Fail-closed on fault — malformed requests and internal errors resolve to deny, never allow.

Install

pip install frt-agent-firewall

Zero runtime dependencies (Python 3.9+).

Quick start

from agent_firewall import McpFirewall, ToolPolicy

policy = ToolPolicy(
    allowed_tools=["files.read", "files.write", "search.query"],
    blocked_tools=["shell.exec", "network.namespace"],
)

fw = McpFirewall(policy=policy, trail_path="./firewall_trail.jsonl")

# In your MCP server request handler, inspect before dispatch:
def handle(request):  # request is a JSON-RPC 2.0 dict
    result, response = fw.inspect(request)
    if result.decision == "deny":
        return response          # a JSON-RPC error — do NOT run the tool
    return dispatch(request)     # result.decision == "allow" → forward original

Proof of life

from agent_firewall.demo import run_demo
for row in run_demo():
    print(row)
{'request_id': 1, 'method': 'tools/list',      'decision': 'allow', 'reason_code': 'PASSTHROUGH'}
{'request_id': 2, 'method': 'tools/call', 'tool': 'files.read',    'decision': 'allow', 'reason_code': 'ALLOWED'}
{'request_id': 3, 'method': 'tools/call', 'tool': 'shell.exec',    'decision': 'deny',  'reason_code': 'ERR_TOOL_BLOCKED'}
{'request_id': 4, 'method': 'tools/call', 'tool': 'db.drop',       'decision': 'deny',  'reason_code': 'ERR_TOOL_NOT_ALLOWED'}
{'request_id': 5, 'method': 'tools/call', 'tool': 'files.write',   'decision': 'deny',  'reason_code': 'ERR_RED_LINE'}
{'request_id': 6, 'method': 'tools/call', 'tool': 'search.query',  'decision': 'deny',  'reason_code': 'ERR_RED_LINE'}

Invariants

# Invariant Enforced by
1 Empty policy denies everything ToolPolicy.allows default
2 Blocklist > red lines > allowlist McpFirewall._inspect order
3 Any unexpected fault → deny inspect() try/except
4 Raw arguments never persisted payload_hash only
5 Trail is a hash chain _append → verify_trail
6 Malformed tools/call never forwarded parse_tool_call None → deny

Architecture

MCP client ──tools/call──> [ agent-firewall ] ──allow──> MCP server
                              │      │
                              │      └──deny──> JSON-RPC error to client
                              └── hash-chain trail (JSONL)

agent-firewall reuses the audit_guard engine (vendored from agent-call-audit under MIT) for its hash-chain trail; adjudication itself is a small, focused policy layer that never re-implements the core guard.

Roadmap ideas

  • HTTP/SSE proxy wrapper (POST /mcp), for network-deployed MCP servers.
  • Policy reload on file change (hot reload).
  • tools/list filtering: hide blocked tools from the client entirely.

License

MIT. Note the vendored audit_guard module is MIT from agent-call-audit (see LICENSE).

中文版

Metadata

Release files for frt-agent-firewall 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for frt-agent-firewall 0.1.0
File Size Uploaded Provenance Actions
frt_agent_firewall-0.1.0.tar.gz 23.1 kB With provenance Details for frt_agent_firewall-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for frt-agent-firewall 0.1.0
File Interpreter ABI Platform Actions
frt_agent_firewall-0.1.0-py3-none-any.whl Python 3 none any Details for frt_agent_firewall-0.1.0-py3-none-any.whl

Total release size: 48.7 kB

Release files / frt_agent_firewall-0.1.0.tar.gz

Download URL frt_agent_firewall-0.1.0.tar.gz
Size 23.1 kB
Tags Source
SHA-256 checksum
How to use checksums
b7b69f311321635df79b5e046acf3054c4ee43310843676e611c2481ce406104
BLAKE2b-256 checksum
How to use checksums
3bd491a3152dac12003bb7298fa51f7970c208b295b6625d3ee79d46fa28a4f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / frt_agent_firewall-0.1.0-py3-none-any.whl

Download URL frt_agent_firewall-0.1.0-py3-none-any.whl
Size 25.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5f57713430c6d7ebd953e56aacd03e9da7d5c4557a01a21ce8b59cd02b156ef0
BLAKE2b-256 checksum
How to use checksums
defff302e986ecae7d41632ff6f6a2debc054fb2f9370894dfd214461a7c232c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for frt-agent-firewall 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for frt_agent_firewall-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page