Agent Capability Firewall

Use this when an AI agent can propose tool calls, API actions, file operations, email sends, browser actions, database writes, or code execution.

The Agent Capability Firewall sits between the model and the tool layer. The model may propose an action, but Firefish decides whether that action is allowed, blocked, requires approval, or can run only as a dry run.

What it protects

• External sends and exports.
• Destructive or irreversible actions.
• Code execution and shell-like tools.
• Writes to files, databases, tickets, or records.
• Tool calls carrying sensitive data.
• Calls to untrusted, private, localhost, link-local, metadata, or credential-bearing destinations.

Local-first defaults

• AGENT_FIREWALL_ENABLED=true by default.
• Localhost, private IP, link-local, and metadata destinations are blocked by default.
• Code execution is blocked by default.
• External send, export, and write actions require approval unless policy explicitly allows them.
• Raw tool arguments are not stored by default. Firefish stores redacted previews, hashes, reason codes, and audit-safe metadata.

Evaluate a proposed action

curl -X POST http://localhost:8000/v1/agent/firewall/evaluate \
  -H "X-API-Key: change-me-local-dev-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_goal": "Send the support summary to the approved review mailbox.",
    "proposed_tool_call": {
      "tool_name": "send_mock_email",
      "arguments": {
        "to": "review@example.test",
        "subject": "Synthetic support summary"
      }
    },
    "allowed_tools": ["send_mock_email"],
    "trusted_domains": ["example.test"],
    "sensitive_data_present": false,
    "reversible": true
  }'

The response includes a decision, risk score, risk level, reason codes, approval requirement, and audit metadata. It does not execute the tool.

Python SDK

from firefish import FirefishClient

client = FirefishClient(base_url="http://localhost:8000", api_key="change-me-local-dev-key")

result = client.evaluate_agent_action(
    user_goal="Read the synthetic ticket.",
    proposed_tool_call={
        "tool_name": "read_synthetic_document",
        "arguments": {"document_id": "doc_demo_001"},
    },
    allowed_tools=["read_synthetic_document"],
)

print(result["decision"], result["reason_codes"])

Operating guidance

Use allowlists for tools and trusted destinations. Treat REQUIRE_APPROVAL as a product feature, not friction: it is the clean handoff point between autonomous agent behavior and human-controlled side effects.

Firefish does not replace application authorization. Your app should still verify user identity, tenant boundaries, object permissions, and business rules before a tool runs.