agentfirewall
Policy-enforced firewall for AI agent tool calls. Intercepts, evaluates, and audits every tool invocation against a YAML security policy.
Part of the AgentSec suite -- open-source security primitives for AI agents.
Install
pip install agentsec-firewall
Premium: Get enterprise security policies, advanced secret detection, and webhook alerting at zazmatt.gumroad.com/l/kjwwhn
Quick Start
# 1. Initialize policy and audit log
agentfirewall init
# 2. Install hooks into Claude Code
agentfirewall install
# 3. Done -- every tool call is now checked against .agentfirewall/policy.yaml
How It Works
Tool Call (e.g. Bash "rm -rf /")
|
v
+-----------+
| PreToolUse | <-- Claude Code hook reads stdin JSON
| Hook |
+-----+-----+
|
v
+-----------+
| Interceptor| <-- Evaluates against policy.yaml
| .check() | Scans params for secrets
+-----+-----+
|
+----+----+
| |
ALLOW DENY ---------> exit 2 (blocks tool call)
| + JSON reason to stdout
v
Tool Executes
|
v
+-----------+
| PostToolUse| <-- Logs execution to audit.jsonl
| Hook |
+-----------+
Policy Reference
Policies are YAML files at .agentfirewall/policy.yaml:
version: "1.0"
name: "my-policy"
description: "Custom security policy"
default_action: log # allow | deny | log | alert
rules:
- name: allow-read-operations
tools: ["Read", "Glob", "Grep"] # fnmatch patterns
action: allow
reason: "Read operations are safe"
- name: block-dangerous-bash
tools: ["Bash"]
resources: ["rm -rf *", "sudo *"] # resource patterns
action: deny
reason: "Dangerous shell commands blocked"
- name: alert-mcp-tools
tools: ["mcp__*"] # wildcards supported
action: alert
reason: "MCP tool calls flagged for review"
- name: log-all-writes
tools: ["Write", "Edit"]
action: log
reason: "File modifications logged"
Actions:
allow-- permit the tool calldeny-- block the tool call (exit code 2)log-- permit but log to audit trailalert-- permit, log, and fire webhook alert
CLI Reference
| Command | Description |
|---|---|
agentfirewall init |
Create .agentfirewall/ with default policy and audit log |
agentfirewall install |
Add PreToolUse/PostToolUse hooks to .claude/settings.local.json |
agentfirewall uninstall |
Remove agentfirewall hooks from settings |
agentfirewall validate |
Validate policy YAML and print rule summary |
agentfirewall audit |
Query audit log (supports --tail, --tool, --action filters) |
agentfirewall scan [PATH] |
Run security scanner on project files |
Python API
from agentfirewall import Interceptor, PolicyViolationError
from agentsec_core.schemas import PolicyAction
# From a policy file
interceptor = Interceptor(policy_path=".agentfirewall/policy.yaml")
# Check a tool call (returns PolicyDecision, never raises)
decision = interceptor.check("Bash", {"command": "rm -rf /"})
if decision.action == PolicyAction.DENY:
print(f"Blocked: {decision.reason}")
# Check and raise on deny
try:
interceptor.check_or_raise("Bash", {"command": "rm -rf /"})
except PolicyViolationError as e:
print(f"Violation: {e.decision.reason}")
# Decorator pattern
@interceptor.wrap("data_export")
def export_data(**kwargs):
... # Only runs if policy allows
Free vs Premium
| Feature | Free (OSS) | Premium |
|---|---|---|
| YAML policy enforcement | Yes | Yes |
| PreToolUse / PostToolUse hooks | Yes | Yes |
| Audit log (JSONL) | Yes | Yes |
| Secret scanning (23 patterns) | Yes | Yes |
| Enterprise policy templates | -- | Yes |
| Webhook alerts (Slack, Discord) | -- | Yes |
| PII/GDPR filtering rules | -- | Yes |
| Priority support | -- | Yes |
Requirements
- Python 3.11+
- agentsec-core >= 0.1.0
License
MIT
Metadata
Release files for agentsec-firewall 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentsec_firewall-0.1.1.tar.gz | 11.8 kB | Without provenance | Details for agentsec_firewall-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentsec_firewall-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agentsec_firewall-0.1.1-py3-none-any.whl |
Total release size: 20.9 kB
Release files / agentsec_firewall-0.1.1.tar.gz
| Download URL | agentsec_firewall-0.1.1.tar.gz |
|---|---|
| Size | 11.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4cfd2dfa9fb76a398535329835950399504ad68dea4b47f1f95a96592aa54108
|
|
BLAKE2b-256 checksum How to use checksums |
6a4c6065a467f502150dcd4e813de05063968ccc2f460583abccd09bf0f8448b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Release files / agentsec_firewall-0.1.1-py3-none-any.whl
| Download URL | agentsec_firewall-0.1.1-py3-none-any.whl |
|---|---|
| Size | 9.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
08abe075569be317271c30742aefb4152233f3e48f25d89eed138ef7730daf27
|
|
BLAKE2b-256 checksum How to use checksums |
c0eb612f845bf10c822ab90963133a777ce39626ff3f87425d0b774b67f71755
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Security for agentsec-firewall 0.1.1
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.