Metadata-Version: 2.4
Name: agentsec-firewall
Version: 0.1.1
Summary: Policy-enforced firewall for AI agent tool calls
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: agentsec-core>=0.1.0
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"

# 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](https://github.com/agentsec) suite -- open-source security primitives for AI agents.

## Install

```bash
pip install agentsec-firewall
```

> **Premium:** Get enterprise security policies, advanced secret detection, and webhook alerting at [zazmatt.gumroad.com/l/kjwwhn](https://zazmatt.gumroad.com/l/kjwwhn)

## Quick Start

```bash
# 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`:

```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

```python
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 |

[Get Premium -- $10](https://zazmatt.gumroad.com/l/kjwwhn)

## Requirements

- Python 3.11+
- [agentsec-core](../agentsec-core/) >= 0.1.0

## License

MIT
