agentsec-firewall 0.1.1__tar.gz

agentsec_firewall-0.1.1/PKG-INFO

@@ -0,0 +1,171 @@
+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

agentsec_firewall-0.1.1/README.md

@@ -0,0 +1,156 @@
+# 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

agentsec_firewall-0.1.1/agentfirewall/__init__.py

@@ -0,0 +1,5 @@
+"""agentfirewall: Policy-enforced firewall for AI agent tool calls."""
+
+__version__ = "0.1.0"
+
+from .interceptor import Interceptor, PolicyViolationError

agentsec_firewall-0.1.1/agentfirewall/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python3 -m agentfirewall."""
+
+from .cli import main
+
+main()

agentsec_firewall-0.1.1/agentfirewall/cli.py

@@ -0,0 +1,236 @@
+"""Click-based CLI for agentfirewall."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+import click
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_POLICY_DIR = ".agentfirewall"
+DEFAULT_POLICY_PATH = f"{DEFAULT_POLICY_DIR}/policy.yaml"
+DEFAULT_LOG_PATH = f"{DEFAULT_POLICY_DIR}/audit.jsonl"
+
+DEFAULT_POLICY_YAML = """\
+version: "1.0"
+name: "default-agent-policy"
+description: "Default security policy -- blocks dangerous operations, logs everything"
+default_action: log
+rules:
+  - name: allow-read-operations
+    tools: ["Read", "Glob", "Grep"]
+    action: allow
+    reason: "Read operations are safe"
+  - name: block-dangerous-bash
+    tools: ["Bash"]
+    resources: ["rm -rf *", "sudo *", "chmod 777 *", "curl * | sh", "wget * | sh"]
+    action: deny
+    reason: "Dangerous shell commands blocked"
+  - name: alert-mcp-tools
+    tools: ["mcp__*"]
+    action: alert
+    reason: "MCP tool calls flagged for review"
+  - name: log-all-writes
+    tools: ["Write", "Edit"]
+    action: log
+    reason: "File modifications logged"
+"""
+
+HOOK_PRETOOL = {
+    "type": "command",
+    "event": "PreToolUse",
+    "command": "python3 -c 'from agentfirewall.hooks import pretool_hook; pretool_hook()'",
+}
+HOOK_POSTTOOL = {
+    "type": "command",
+    "event": "PostToolUse",
+    "command": "python3 -c 'from agentfirewall.hooks import posttool_hook; posttool_hook()'",
+}
+
+SETTINGS_PATH = ".claude/settings.local.json"
+
+
+@click.group()
+@click.version_option(package_name="agentfirewall")
+def main() -> None:
+    """agentfirewall -- Policy-enforced firewall for AI agent tool calls."""
+
+
+@main.command()
+def init() -> None:
+    """Initialize .agentfirewall/ with default policy and audit log."""
+    policy_dir = Path(DEFAULT_POLICY_DIR)
+    policy_dir.mkdir(parents=True, exist_ok=True)
+
+    policy_file = Path(DEFAULT_POLICY_PATH)
+    if policy_file.exists():
+        click.echo(f"Policy already exists: {policy_file}")
+    else:
+        policy_file.write_text(DEFAULT_POLICY_YAML, encoding="utf-8")
+        click.echo(f"Created default policy: {policy_file}")
+
+    log_file = Path(DEFAULT_LOG_PATH)
+    if not log_file.exists():
+        log_file.touch()
+        click.echo(f"Created audit log: {log_file}")
+
+    click.echo("Initialization complete. Run `agentfirewall install` to add hooks.")
+
+
+@main.command()
+@click.option("--policy", default=DEFAULT_POLICY_PATH, help="Path to policy YAML file.")
+def validate(policy: str) -> None:
+    """Validate a policy YAML file."""
+    from agentsec_core.policy import load_policy
+
+    try:
+        loaded = load_policy(policy)
+    except FileNotFoundError:
+        click.echo(f"Error: Policy file not found: {policy}", err=True)
+        raise SystemExit(1)
+    except ValueError as exc:
+        click.echo(f"Error: Invalid policy: {exc}", err=True)
+        raise SystemExit(1)
+
+    click.echo(f"Policy: {loaded.name} (v{loaded.version})")
+    click.echo(f"Description: {loaded.description}")
+    click.echo(f"Default action: {loaded.default_action.value}")
+    click.echo(f"Rules: {len(loaded.rules)}")
+    for rule in loaded.rules:
+        tools = ", ".join(rule.tools) if rule.tools else "*"
+        click.echo(f"  - {rule.name}: {rule.action.value} [{tools}]")
+    click.echo("Policy is valid.")
+
+
+@main.command()
+@click.option("--tail", "tail_n", default=20, type=int, help="Number of recent events.")
+@click.option("--tool", "tool_name", default=None, help="Filter by tool name.")
+@click.option("--action", "action_filter", default=None, help="Filter by action (allow/deny/log/alert).")
+def audit(tail_n: int, tool_name: str | None, action_filter: str | None) -> None:
+    """Query the audit log."""
+    from agentsec_core.logger import AuditLogger
+    from agentsec_core.schemas import PolicyAction
+
+    log_path = Path(DEFAULT_LOG_PATH)
+    if not log_path.exists():
+        click.echo("No audit log found. Run `agentfirewall init` first.", err=True)
+        raise SystemExit(1)
+
+    audit_logger = AuditLogger(log_path)
+
+    action_enum = None
+    if action_filter:
+        try:
+            action_enum = PolicyAction(action_filter.lower())
+        except ValueError:
+            click.echo(f"Error: Invalid action '{action_filter}'. Use: allow/deny/log/alert", err=True)
+            raise SystemExit(1)
+
+    events = audit_logger.query(tool_name=tool_name, action=action_enum)
+    recent = events[-tail_n:]
+
+    if not recent:
+        click.echo("No matching events found.")
+        return
+
+    click.echo(f"Showing {len(recent)} of {len(events)} events:")
+    for event in recent:
+        ts = event.timestamp.strftime("%Y-%m-%d %H:%M:%S") if event.timestamp else "N/A"
+        violations = f" [{len(event.violations)} violations]" if event.violations else ""
+        click.echo(f"  {ts} | {event.action_taken.value:5s} | {event.tool_name}{violations}")
+
+
+@main.command()
+@click.argument("path", default=".")
+def scan(path: str) -> None:
+    """Run security scanner on project files."""
+    from agentsec_core.scanner import scan_file
+
+    target = Path(path)
+    if not target.exists():
+        click.echo(f"Error: Path not found: {path}", err=True)
+        raise SystemExit(1)
+
+    files = [target] if target.is_file() else sorted(target.rglob("*"))
+    total_violations = 0
+
+    for filepath in files:
+        if not filepath.is_file():
+            continue
+        violations = scan_file(str(filepath))
+        for v in violations:
+            total_violations += 1
+            click.echo(f"  [{v.severity}] {v.source}:{v.line_number} - {v.message}")
+
+    if total_violations == 0:
+        click.echo("No security issues found.")
+    else:
+        click.echo(f"\nFound {total_violations} issue(s).")
+        raise SystemExit(1)
+
+
+@main.command()
+def install() -> None:
+    """Install agentfirewall hooks into Claude Code settings."""
+    settings_path = Path(SETTINGS_PATH)
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if settings_path.exists():
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    else:
+        settings = {}
+
+    hooks = settings.get("hooks", [])
+
+    # Check for existing agentfirewall hooks
+    existing_commands = {h.get("command", "") for h in hooks}
+    added = 0
+
+    if HOOK_PRETOOL["command"] not in existing_commands:
+        hooks.append(HOOK_PRETOOL)
+        added += 1
+
+    if HOOK_POSTTOOL["command"] not in existing_commands:
+        hooks.append(HOOK_POSTTOOL)
+        added += 1
+
+    settings["hooks"] = hooks
+    settings_path.write_text(
+        json.dumps(settings, indent=2) + "\n", encoding="utf-8"
+    )
+
+    if added > 0:
+        click.echo(f"Installed {added} hook(s) into {settings_path}")
+    else:
+        click.echo("Hooks already installed.")
+
+
+@main.command()
+def uninstall() -> None:
+    """Remove agentfirewall hooks from Claude Code settings."""
+    settings_path = Path(SETTINGS_PATH)
+
+    if not settings_path.exists():
+        click.echo("No settings file found. Nothing to uninstall.")
+        return
+
+    settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    hooks = settings.get("hooks", [])
+
+    firewall_commands = {HOOK_PRETOOL["command"], HOOK_POSTTOOL["command"]}
+    original_count = len(hooks)
+    hooks = [h for h in hooks if h.get("command", "") not in firewall_commands]
+
+    removed = original_count - len(hooks)
+    settings["hooks"] = hooks
+    settings_path.write_text(
+        json.dumps(settings, indent=2) + "\n", encoding="utf-8"
+    )
+
+    if removed > 0:
+        click.echo(f"Removed {removed} hook(s) from {settings_path}")
+    else:
+        click.echo("No agentfirewall hooks found to remove.")

agentsec_firewall-0.1.1/agentfirewall/hooks.py

@@ -0,0 +1,106 @@
+"""Claude Code hook integration for agentfirewall.
+
+PreToolUse hook: reads tool call from stdin, checks policy, exits 2 to block.
+PostToolUse hook: reads tool result from stdin, logs to audit trail.
+
+Install via: agentfirewall install
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from pathlib import Path
+
+from agentsec_core.schemas import AuditEvent, PolicyAction
+
+logger = logging.getLogger(__name__)
+
+# Default paths (created by `agentfirewall init`)
+DEFAULT_POLICY_PATH = ".agentfirewall/policy.yaml"
+DEFAULT_LOG_PATH = ".agentfirewall/audit.jsonl"
+
+
+def _read_hook_input() -> dict:
+    """Read JSON hook input from stdin. Returns empty dict on failure."""
+    try:
+        raw = sys.stdin.read()
+        return json.loads(raw) if raw.strip() else {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _parse_json_field(data: dict, field: str) -> dict:
+    """Parse a possibly-stringified JSON field."""
+    value = data.get(field, "{}")
+    if isinstance(value, dict):
+        return value
+    try:
+        return json.loads(value)
+    except (json.JSONDecodeError, TypeError):
+        return {}
+
+
+def pretool_hook() -> None:
+    """PreToolUse hook entry point.
+
+    Reads stdin JSON with tool_name and tool_input.
+    Checks against policy. Exits 2 to block, 0 to allow.
+    Outputs JSON reason on block.
+    """
+    if not Path(DEFAULT_POLICY_PATH).exists():
+        sys.exit(0)  # No policy = allow all
+
+    from .interceptor import Interceptor
+
+    hook_data = _read_hook_input()
+    tool_name = hook_data.get("tool_name", "")
+    tool_input = _parse_json_field(hook_data, "tool_input")
+
+    try:
+        interceptor = Interceptor(
+            policy_path=DEFAULT_POLICY_PATH,
+            log_path=DEFAULT_LOG_PATH,
+        )
+        decision = interceptor.check(tool_name, tool_input)
+    except Exception as exc:
+        # Fail-open: don't break Claude Code if firewall crashes
+        sys.stderr.write(f"agentfirewall: error checking policy: {exc}\n")
+        sys.exit(0)
+
+    if decision.action == PolicyAction.DENY:
+        reason = decision.reason or "Blocked by agentfirewall policy"
+        output = json.dumps({"decision": "block", "reason": reason})
+        print(output)  # noqa: T201 — CLI output
+        sys.exit(2)
+
+    sys.exit(0)
+
+
+def posttool_hook() -> None:
+    """PostToolUse hook entry point.
+
+    Reads stdin JSON with tool result. Logs to audit trail.
+    Always exits 0 (never blocks post-execution).
+    """
+    if not Path(DEFAULT_LOG_PATH).parent.exists():
+        sys.exit(0)
+
+    from agentsec_core.logger import AuditLogger
+
+    hook_data = _read_hook_input()
+    tool_name = hook_data.get("tool_name", "")
+
+    try:
+        audit_logger = AuditLogger(DEFAULT_LOG_PATH)
+        event = AuditEvent(
+            event_type="tool_execution",
+            tool_name=tool_name,
+            action_taken=PolicyAction.LOG,
+        )
+        audit_logger.log(event)
+    except Exception as exc:
+        sys.stderr.write(f"agentfirewall: error logging: {exc}\n")
+
+    sys.exit(0)