agentsec-firewall 0.1.0

Policy-enforced firewall for AI agent tool calls

agentfirewall

Policy-enforced firewall for AI agent tool calls. Intercepts, evaluates, and audits every tool invocation against a YAML security policy.

Install

pip install agentfirewall

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 call
• deny -- block the tool call (exit code 2)
• log -- permit but log to audit trail
• alert -- 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

Requirements

• Python 3.11+
• agentsec-core >= 0.1.0

License

MIT