Skip to main content

Agent firewall

agent-firewall checks the tool calls in model traffic and allows or blocks each one. For example, an agent may call search and read_* tools but never a deletion tool. It can also limit how many actions one request contains, stop on suspicious commands, and escalate large payments for approval.

The gateway tracks action rates, session actions, daily transaction totals, and consecutive tool errors across requests. Local counters reset on restart or eviction. A configured distributed backend shares counters across gateway instances. Set an explicit value for each threshold you need to enforce; omitted thresholds can report would_block observations without blocking.

Configuration​

The control has a simple shape and an expanded shape. Use one of them in a block. Lint rejects a block that mixes them.

Start with the simple shape. Save it as policy-config.yaml in a test directory, and use the config-first workflow to apply it.

policy-config.yaml
pack:
  name: agent-firewall-simple
  version: 1.0.0
  enabled: true
policies:
  chain:
    - agent-firewall
policy:
  agent-firewall:
    allowed_tools:
      - read_*
      - search
    blocked_tools:
      - rm_rf
    max_actions_per_session: 50

search and read_document are allowed. rm_rf is blocked, and write_document is rejected because no rule allows it.

Fields​

FieldTypeDefaultDescription
allowed_toolsstring[]["*"]Simple shape. Tool name patterns that are allowed. * matches any sequence, including an empty one.
blocked_toolsstring[][]Simple shape. Tool name patterns that are blocked. A block wins over an allow.
max_actions_per_sessioninteger500 reporting thresholdBoth shapes. Counts tool actions across a session when x-session-id is present; otherwise checks assistant messages in the request. Set it explicitly to enforce.
tools.roles.<role>.allowedstring[][]Expanded shape. Allowed tool patterns for a verified role
tools.roles.<role>.deniedstring[][]Expanded shape. Denied tool patterns for a verified role
rate_limits.defaultinteger60 reporting thresholdExpanded shape. Default per-tool minute limit and maximum actions in one evaluation. Set explicitly to enforce.
rate_limits.<tool>integerExpanded shape. Explicit per-minute limit for this tool
transaction_limits.max_single_transactionnumber10000 reporting thresholdLargest permitted amount for one transaction
transaction_limits.max_daily_totalnumber50000 reporting thresholdMaximum total for the identity during the UTC day
transaction_limits.require_approval_abovenumber5000 reporting thresholdEscalates an amount strictly greater than this value
kill_switches.halt_on_suspicious_patternbooleantrue reporting defaultBlocks matching suspicious text when explicitly enabled
kill_switches.halt_on_pii_in_actionbooleantrue reporting defaultBlocks PII in tool arguments when explicitly enabled
kill_switches.max_errors_before_haltinteger5 reporting thresholdHalts after this many consecutive recorded tool errors when explicitly set
monitoring.alert_on_denied_actionbooleantrueAdds denied-action alerts to decision details
monitoring.alert_on_rate_limitbooleantrueAdds rate-limit alerts to decision details
monitoring.alert_threshold_percentinteger80Usage-alert threshold, clamped to 1 through 100

An omitted enforcement threshold uses the reporting default and can add would_block details. It does not enforce that default. Explicit zero disables an amount or count threshold where that threshold uses zero as its off value. Monitoring details are decision evidence; they do not promise an email notification.

Phase and verdicts​

ItemValue
Phasetool, in the input and output stages
Request familiesChat Completions, Responses, Messages
Verdictsallow, block, escalate
Reason codesagent_firewall.<check>, listed below
  • agent_firewall.allowed
  • agent_firewall.malformed_tool_call
  • agent_firewall.kill_switch
  • agent_firewall.rate_limit_exceeded
  • agent_firewall.session_limit_exceeded
  • agent_firewall.error_threshold_halt
  • agent_firewall.transaction_value_exceeded
  • agent_firewall.daily_total_exceeded
  • agent_firewall.approval_required
  • agent_firewall.pii_in_tool_args
  • agent_firewall.authoritative_role_required
  • agent_firewall.role_denied_tool
  • agent_firewall.role_tool_not_allowed
  • agent_firewall.blocked_tool.<tool>
  • agent_firewall.tool_not_allowed

A block returns HTTP 400 with error code content_policy_violation. An escalation returns HTTP 200 with content: null, finish_reason: content_filter, and a verdictan.escalation object with the escalation ID and status queued.

Try it without a provider​

The control reads tool calls, so give each test case a raw request with an assistant tool call. Add this to the simple configuration:

Add to policy-config.yaml
testing:
  suites:
    - name: agent-firewall
      cases:
        - name: allows-search
          input:
            request:
              model: test-model
              messages:
                - role: user
                  content: "Find the report."
                - role: assistant
                  tool_calls:
                    - id: call_1
                      type: function
                      function: {name: search, arguments: "{\"q\":\"report\"}"}
          expected: {verdict: allow, reason_code: ok}
        - name: blocks-rm-rf
          input:
            request:
              model: test-model
              messages:
                - role: user
                  content: "Clean up."
                - role: assistant
                  tool_calls:
                    - id: call_1
                      type: function
                      function: {name: rm_rf, arguments: "{}"}
          expected: {verdict: block, reason_code: agent_firewall.blocked_tool.rm_rf}
        - name: blocks-unlisted-tool
          input:
            request:
              model: test-model
              messages:
                - role: user
                  content: "Save it."
                - role: assistant
                  tool_calls:
                    - id: call_1
                      type: function
                      function: {name: write_document, arguments: "{}"}
          expected: {verdict: block, reason_code: agent_firewall.tool_not_allowed}

Run verdictan policy test --json. All three cases pass. Then send a real tool call through a test gateway before you connect a tool executor.

How it works​

  1. The control reads tool calls from the request or response: messages[].tool_calls of assistant messages, choices[].message.tool_calls, Responses API output and input items, and Anthropic content blocks. A tool call that it cannot parse blocks with agent_firewall.malformed_tool_call.
  2. It also finds tool names in assistant text with patterns such as "name": "<tool>", function_call: <tool>, tool: <tool>, and calling <tool>.
  3. With tools.roles, it keeps the roles of the verified identity that appear in the table.
  4. With halt_on_suspicious_pattern, tool text that contains rm -rf, sudo , drop table, exfiltrate, or disable security blocks with agent_firewall.kill_switch.
  5. Too many actions in total, or too many calls of one tool, blocks with agent_firewall.rate_limit_exceeded.
  6. More session actions than an explicit max_actions_per_session blocks with agent_firewall.session_limit_exceeded. Without a session ID, the check uses assistant messages in the current request. Consecutive recorded tool errors can halt with agent_firewall.error_threshold_halt.
  7. The control reads currency amounts from tool text and numeric amount fields from structured arguments. Over an explicit limit, it blocks with agent_firewall.transaction_value_exceeded or agent_firewall.daily_total_exceeded. Strictly above an explicit require_approval_above, it escalates with agent_firewall.approval_required.
  8. With halt_on_pii_in_action, a PII match in a tool argument blocks with agent_firewall.pii_in_tool_args.
  9. With tools.roles and tool actions present, an identity without a listed role is blocked with agent_firewall.authoritative_role_required.
  10. Each tool action is checked in this order: role denied, role allowed, blocked_tools, allowed_tools. The reason codes are agent_firewall.role_denied_tool, agent_firewall.role_tool_not_allowed, agent_firewall.blocked_tool.<tool>, and agent_firewall.tool_not_allowed.
  11. Otherwise, the request is allowed with agent_firewall.allowed.

The allow details contain action_count, session_action_count, role, authoritative_roles, authoritative_permissions, actions, and structured_action_count.

Limits and failure behavior​

  • Per-minute action counters are scoped to the verified identity, or an anonymous identity when none is available. Session counters also use x-session-id. Use stable, trusted session IDs. Output calls are checked before delivery and are counted when replayed as input in a later request.
  • Local counters are bounded and reset on restart or eviction. Distributed counters use Redis or Valkey; session and daily records have a 48-hour expiry. Daily totals use UTC dates. Backend failure follows the distributed-state failure mode.
  • Isolated policy tests do not prove cross-request accumulation. Check live session behavior when you deploy these limits.
  • Transaction checks recognize supported currency symbols and codes, including $, €, £, ¥, USD, EUR, and numeric tool-argument fields such as amount, total, and price. They do not convert currencies. Use one monetary unit for a governed workflow.
  • In the simple shape, an empty allowed_tools list allows nothing. Leave the field out to keep the ["*"] default.
  • With tools.roles, identity roles that the table does not list are ignored. If none is listed, every tool action is blocked. If several are listed, every one of them must allow the tool.
  • Role rules use only the verified identity. An X-User-Role header does not select a role.
  • The suspicious pattern check matches five fixed substrings. sudo matches only when a space follows it.
  • The PII check on tool arguments uses the base detector, without healthcare_mode or pci_mode.
  • With stream: true, the gateway holds the streamed tool calls until the stream ends, checks them, and then sends the stream or a final error.
  • Suspicious-pattern checks can block text without a structured tool call. To restrict access by identity, use RBAC.

Next steps​