Tool Firewall: Mask, Substitute, Downgrade Actions
2026-03-11
Tool Firewall: Mask, Substitute, Downgrade Actions
What We Built
Extended the tool-call firewall from 3 actions (pass|warn|block) to 6 (pass|warn|mask|substitute|downgrade|block). Wired firewall inspection into the agentic-completions path. Added GET /v1/firewall/interceptions endpoint for querying firewall violation events.
Why It Matters
The original firewall was binary: pass or block. Real-world tool governance needs nuance — mask PII in tool arguments without blocking the call, substitute a risky tool with a safe alternative, or hint the router to downgrade model quality for expensive tool calls. These new actions give operators granular control without disrupting agent workflows.
How It Works
- Mask: Compiled regex patterns scan string leaves in tool arguments. Matches are replaced with
[REDACTED:{name}]. The call proceeds with sanitized args. - Substitute: Tool name is swapped and extra arguments merged from config. The original tool name is logged for audit. The call proceeds with the replacement tool.
- Downgrade: When an inspected tool call matches
downgradeOnTools, adowngradeHintis attached to the firewall result and exposed via theX-BR-Tool-Firewall-Downgraderesponse header. Clients can use this signal to opt into cheaper routing on subsequent requests. The downgrade is informational — it does not alter routing for the current request. - Priority:
block > downgrade > substitute > mask > warn > pass. The highest-severity action across all tool calls in a request wins. - Agentic path: The firewall now inspects tool calls in agentic-completions responses (previously only standard completions were inspected).
The Numbers
- 6 firewall actions (up from 3)
- 9-step inspection pipeline
GET /v1/firewall/interceptionswith pagination- SDK methods in TypeScript + Python
- Dashboard filters for all 6 action types + 10 reason categories
Lockstep
| Surface | Status | Files |
|---|---|---|
| API | Done | src/security/tool-call-firewall.ts, src/api/routes/security.ts, src/api/routes/auth.ts, src/api/routes/agentic-completions.ts |
| SDK-TS | Done | packages/sdk-ts/src/resources/security.ts |
| SDK-PY | Done | packages/sdk-py/src/brainstormrouter/resources/security.py |
| MCP | Done | src/mcp/tool-manifest.ts, src/mcp/server.ts, site/.well-known/agents.json — updated br_route_completion description |
| Dashboard | Done | site/dashboard/src/pages/tool-firewall.ts, site/dashboard/src/api.ts |
| Tests | Done | src/security/tool-call-firewall.test.ts |
| Docs | Done | docs/api-reference/firewall.mdx |
| CLI | N/A | No CLI changes needed |
| GTM | N/A | No marketing changes needed |