Firewall

Guardrails screen the text that flows through a model. The Firewall governs the actions an agent takes — the tools it calls, the MCP servers it reaches, the skills it loads, and the hosts it talks to. It is the action-layer peer of Guardrails: same workspace scoping, same attach-once model, same “policy lives in the gateway, not your app” promise. This page is the conceptual overview and operations reference. Three companion pages cover the moving parts in depth:

​

1. What is the Firewall

An AI agent doesn’t just generate text — it acts. It calls shell.exec, queries db.query, fetches a URL, loads a community skill, or routes a tool call through a third-party MCP server. Each of those is an action with real-world consequences, and prompt-level guardrails can’t see them. The Firewall is a workspace-scoped, named policy that the gateway evaluates on every tool call. You author a policy once, attach an API key to it (or set one as the workspace default), and from then on every tool call that key issues is checked against the policy — before it reaches the tool. Each policy is an ordered list of rules. A rule decides one thing — which tool calls it applies to (a tool-name glob, optionally scoped to a skill and to an enforcement surface) and what to do about them (a verdict: allow, audit, deny, sanitize, hold for approval, or cap cost). The engine walks the rules in priority order, first match wins, and falls back to the policy’s default verdict if nothing matches. Editing a policy takes effect on every key attached to it on the next call. No redeploy. No agent-code change. The policy is enforced at the gateway — your agent keeps issuing tool calls exactly as before.

​

2. The four enforcement surfaces

Every tool call is evaluated against exactly one surface — the point in the request lifecycle where the firewall sees it: A rule with no stage applies to all surfaces; pin a rule to one surface when a verdict only makes sense there (e.g. an egress allowlist).

​

3. Core concepts

​

Scoping and resolution

Policies resolve exactly like Guardrails and API keys — workspace-shared when you have an active workspace. For any tool call the gateway resolves the policy in this order:

1. Key attachment — if the calling key has a firewall_policy_id, that policy applies (when it exists and is enabled).
2. Workspace default — otherwise the workspace’s enabled is_default policy applies.
3. Neither — no enforcement. With observe mode on, the call is allowed and logged as a gap; with it off, the call is allowed silently (byte-identical to a workspace that never enabled the feature).

At most one policy per workspace can be the default; promoting a new default demotes the old one in the same transaction.

​

4. Verdicts

A rule (or the default verdict) produces one of: In shadow mode, deny / sanitize / pending_approval are all downgraded to audit so you can measure a policy’s impact before it changes traffic.

​

5. How a tool call is evaluated

1. A tool call reaches the gateway (advertised inbound, emitted in a response, dispatched through the MCP gateway, or reported as egress).
2. The engine resolves the active policy (§3).
3. It walks the policy’s rules in priority order (lower priority first; ties broken by rule id). A rule matches when its surface, its tool-name glob, its optional skill-name glob, its optional argument clauses, and its optional egress scope all match.
4. First match wins → the rule’s verdict applies. If no rule matches → the policy’s default_verdict.
5. If the call is owned by a governed skill, the skill’s enforcement mode is applied on top — a skill in block mode forces a deny; a skill in quarantine mode escalates anything short of deny to pending_approval.
6. The decision is logged as a firewall event (unless it’s a dry run), correlated to the agent run and session.

​

6. What a block looks like

A denied call on the inbound surface returns HTTP 400 with an OpenAI-shaped error body, error code firewall_blocked, and a message naming the tool and the reason — e.g. tool "shell.exec" blocked by firewall: destructive shell command. The error carries structured metadata (reason code, risk factors, score) and is marked skip-retry (re-running the same call would just block again). A call dispatched through the MCP gateway is blocked as a tool error (firewall deny: <reason>) rather than a transport failure, so the model sees the rejection and can react — pick another tool, ask the user, or stop — instead of crashing. A held call (pending_approval) returns HTTP 400 with code firewall_approval_pending and an approval id the client polls on.

​

7. Human approval (HITL)

A pending_approval verdict turns a tool call into an out-of-band review:

1. The engine enqueues an approval record and returns a “held” response carrying its id; the call does not reach the tool.
2. A reviewer resolves it — from the console (Developer+), or via an HMAC-signed webhook callback to your own approval system.
3. Your agent (or the MCP SDK) polls the approval id; once approved it re-submits the original call with a single-use X-OrcaRouter-Firewall-Approval header, and the gateway lets it through that one time.

Decisions are first-writer-wins and idempotent. If the underlying rule was edited after the hold, the enrichment notes rule_changed so reviewers know the context shifted.

​

8. Autonomy levels: one switch for your whole posture

Tuning policies rule-by-rule is the precise path; autonomy levels are the fast one. A single control atomically replaces your workspace’s Firewall and Guardrails posture in one transaction, with one-click undo: Undo restores the exact prior state from the audit snapshot.

​

9. Anomaly detection

Beyond static rules, the Firewall learns each workspace’s normal tool-use shape and flags deviations on a viewer-readable feed:

• Rate / cost spikes — per-tool activity is scored against a learned hour-of-week baseline (a 14-day rolling average), so “100 db.query calls at 3am Sunday” stands out even if each call is individually allowed.
• retry_loop — an agent hammering the same failing tool.
• novel_path — a tool-to-tool transition this workspace has never made before.

The feed reports tool names, redacted token ids, and counts only. You can snooze an anomaly for up to 7 days while you investigate.

​

10. Observability

The Firewall leaves a trail you can act on, all workspace-scoped:

​

11. Relationship to the rest of the gateway

​

12. Connecting an agent to the Firewall gateway

There are two ways a tool call reaches the engine:

• MCP gateway — point your MCP client (Claude Desktop, Cursor, an agent framework) at https://api.orcarouter.ai/api/v1/firewall/mcp. The gateway exposes every reachable registered server’s tools, namespaced <server>.<tool>, and evaluates each tools/call inline. See MCP servers.
• Evaluate hook — call POST /api/v1/firewall/evaluate from your own agent loop before dispatching a tool call, and act on the verdict.

Both require a firewall-gateway-scoped token — a dedicated API key minted for this purpose. A regular key gets 403 on these routes.

​

13. API reference

All console routes are workspace-scoped via the workspace context and enforce RBAC consistently: reads and the test/simulate sandboxes are open to every member; writes require Developer+.

​

Policies & settings

​

Posture, presets & sandboxes

​

Observability

Rules, MCP servers, and skills each have their own endpoints — see Rules, MCP servers, and Skills.

​

Gateway (machine-to-machine)

These run on a firewall-gateway-scoped token, not the console session:

​

14. FAQ

​

See also

Going deeper on agent security? The Secure Your Agents (Zero Trust) guides put this feature in a zero-trust workflow.