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.
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: 50search and read_document are allowed. rm_rf is blocked, and write_document is rejected because no rule allows it.
Use this shape for rules by role. Do not combine it with the simple shape.
pack:
name: agent-firewall-expanded
version: 1.0.0
enabled: true
policies:
chain:
- agent-firewall
policy:
agent-firewall:
tools:
roles:
analyst:
allowed:
- read_database
- export_csv
denied:
- delete_database
rate_limits:
export_csv: 1
transaction_limits:
max_single_transaction: 5000.0
max_daily_total: 20000.0
require_approval_above: 1000.0
kill_switches:
halt_on_suspicious_pattern: true
halt_on_pii_in_action: trueFields
| Field | Type | Default | Description |
|---|---|---|---|
allowed_tools | string[] | ["*"] | Simple shape. Tool name patterns that are allowed. * matches any sequence, including an empty one. |
blocked_tools | string[] | [] | Simple shape. Tool name patterns that are blocked. A block wins over an allow. |
max_actions_per_session | integer | 500 reporting threshold | Both 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>.allowed | string[] | [] | Expanded shape. Allowed tool patterns for a verified role |
tools.roles.<role>.denied | string[] | [] | Expanded shape. Denied tool patterns for a verified role |
rate_limits.default | integer | 60 reporting threshold | Expanded shape. Default per-tool minute limit and maximum actions in one evaluation. Set explicitly to enforce. |
rate_limits.<tool> | integer | Expanded shape. Explicit per-minute limit for this tool | |
transaction_limits.max_single_transaction | number | 10000 reporting threshold | Largest permitted amount for one transaction |
transaction_limits.max_daily_total | number | 50000 reporting threshold | Maximum total for the identity during the UTC day |
transaction_limits.require_approval_above | number | 5000 reporting threshold | Escalates an amount strictly greater than this value |
kill_switches.halt_on_suspicious_pattern | boolean | true reporting default | Blocks matching suspicious text when explicitly enabled |
kill_switches.halt_on_pii_in_action | boolean | true reporting default | Blocks PII in tool arguments when explicitly enabled |
kill_switches.max_errors_before_halt | integer | 5 reporting threshold | Halts after this many consecutive recorded tool errors when explicitly set |
monitoring.alert_on_denied_action | boolean | true | Adds denied-action alerts to decision details |
monitoring.alert_on_rate_limit | boolean | true | Adds rate-limit alerts to decision details |
monitoring.alert_threshold_percent | integer | 80 | Usage-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
| Item | Value |
|---|---|
| Phase | tool, in the input and output stages |
| Request families | Chat Completions, Responses, Messages |
| Verdicts | allow, block, escalate |
| Reason codes | agent_firewall.<check>, listed below |
agent_firewall.allowedagent_firewall.malformed_tool_callagent_firewall.kill_switchagent_firewall.rate_limit_exceededagent_firewall.session_limit_exceededagent_firewall.error_threshold_haltagent_firewall.transaction_value_exceededagent_firewall.daily_total_exceededagent_firewall.approval_requiredagent_firewall.pii_in_tool_argsagent_firewall.authoritative_role_requiredagent_firewall.role_denied_toolagent_firewall.role_tool_not_allowedagent_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:
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
- The control reads tool calls from the request or response:
messages[].tool_callsof assistant messages,choices[].message.tool_calls, Responses APIoutputandinputitems, and Anthropiccontentblocks. A tool call that it cannot parse blocks withagent_firewall.malformed_tool_call. - It also finds tool names in assistant text with patterns such as
"name": "<tool>",function_call: <tool>,tool: <tool>, andcalling <tool>. - With
tools.roles, it keeps the roles of the verified identity that appear in the table. - With
halt_on_suspicious_pattern, tool text that containsrm -rf,sudo,drop table,exfiltrate, ordisable securityblocks withagent_firewall.kill_switch. - Too many actions in total, or too many calls of one tool, blocks with
agent_firewall.rate_limit_exceeded. - More session actions than an explicit
max_actions_per_sessionblocks withagent_firewall.session_limit_exceeded. Without a session ID, the check uses assistant messages in the current request. Consecutive recorded tool errors can halt withagent_firewall.error_threshold_halt. - 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_exceededoragent_firewall.daily_total_exceeded. Strictly above an explicitrequire_approval_above, it escalates withagent_firewall.approval_required. - With
halt_on_pii_in_action, a PII match in a tool argument blocks withagent_firewall.pii_in_tool_args. - With
tools.rolesand tool actions present, an identity without a listed role is blocked withagent_firewall.authoritative_role_required. - Each tool action is checked in this order: role
denied, roleallowed,blocked_tools,allowed_tools. The reason codes areagent_firewall.role_denied_tool,agent_firewall.role_tool_not_allowed,agent_firewall.blocked_tool.<tool>, andagent_firewall.tool_not_allowed. - 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 asamount,total, andprice. They do not convert currencies. Use one monetary unit for a governed workflow. - In the simple shape, an empty
allowed_toolslist 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-Roleheader does not select a role. - The suspicious pattern check matches five fixed substrings.
sudomatches only when a space follows it. - The PII check on tool arguments uses the base detector, without
healthcare_modeorpci_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
- RBAC: allow tools by verified role, with data sensitivity limits.
- Tool security: check request payloads for unsafe tool definitions.
- Resolve an escalation: approve the payments that
require_approval_aboveescalates. - Govern agent tool calls and MCP tools: a short guide to this task, with the decisions and limits in one place.