Riferimento API Firewall

L’Agent Firewall è configurato in due modi: attraverso la console (la tua sessione, lo stesso login che usi per la dashboard) e attraverso il gateway (una chiave API dedicata con scope firewall che il tuo agent presenta a runtime). Le due famiglie vivono su prefissi di path diversi, prendono auth diversa e rispondono a domande diverse — “modifica la policy” contro “valuta questa chiamata a tool”. Questa pagina è la mappa rotta per rotta di entrambe. Per cosa significa la policy — verdetti, superfici, regole, risoluzione — parti da Firewall e Regole del firewall. Questa pagina è solo la superficie API.

1. Le due famiglie di rotte

Console — configura

/api/workspace/firewall/*. Autenticata dal tuo session / access token (UserAuth), con scope sul tuo workspace attivo. Crea policy, leggi eventi, registra MCP server, risolvi approvazioni. Ogni azione è role-gated.

Gateway — applica

/api/v1/firewall/*. Autenticata da una chiave con scope firewall-gateway (una chiave con is_firewall_gateway impostato). La superficie machine-to-machine che il tuo agent o client MCP chiama a runtime. Una normale chiave di relay riceve 403 qui.

Le rotte di console non prendono mai una chiave di relay sk-orca-…, e le rotte del gateway non prendono mai un session token. Confonderle è il 401/403 più comune quando si collega il firewall la prima volta. L’unica chiave sk-orca-… che appartiene a una chiamata /v1/firewall/* è una coniata con is_firewall_gateway attivo — vedi Scope, chiavi e policy.

2. Ruoli in sintesi

Le rotte di console risolvono il tuo ruolo di workspace e applicano il gate di conseguenza. Le letture che non portano provenienza di chiamate a tool sono aperte a qualsiasi membro; le scritture e qualsiasi cosa esponga argomenti di chiamate a tool richiedono Developer+.

Ruolo	Cosa può fare
Viewer / member	Leggere impostazioni, policy, preset, discovered tools, simulate, anomalies.
Developer+	Tutto quanto sopra, più ogni scrittura, la superficie `events`/`runs`/`trace` e il dry-run `test`.
Admin+	In aggiunta, impostare il flag `is_firewall_gateway` su una chiave e leggere il plaintext di una chiave gateway.

La divisione è deliberata: un viewer può vedere che una policy esiste e cosa bloccherebbe, ma non gli argomenti grezzi della chiamata a tool dietro un evento. Se stai costruendo dashboard per non-sviluppatori, le rotte read-open sono il set sicuro.

3. Configurare una policy dalla console

Le rotte di console sono il modo in cui crei e ispezioni la policy. Configuri tutto nella UI della dashboard — questi sono gli stessi endpoint che chiama.

Policy e impostazioni

Metodo & path	Ruolo	Scopo
`GET /api/workspace/firewall/settings`	Member	Observe-mode + conteggi.
`PUT /api/workspace/firewall/settings`	Developer+	Aggiorna le impostazioni del firewall del workspace.
`GET /api/workspace/firewall/policies`	Member	Elenca le policy.
`GET /api/workspace/firewall/policies/:id`	Member	Dettaglio di una singola policy.
`POST /api/workspace/firewall/policies`	Developer+	Crea una policy.
`PUT /api/workspace/firewall/policies`	Developer+	Aggiorna una policy.
`DELETE /api/workspace/firewall/policies/:id`	Developer+	Elimina una policy.
`POST /api/workspace/firewall/rules`	Developer+	Aggiunge una regola.
`PUT /api/workspace/firewall/rules`	Developer+	Aggiorna una regola.
`DELETE /api/workspace/firewall/rules/:id`	Developer+	Elimina una regola.

Postura, preset e sandbox

Metodo & path	Ruolo	Scopo
`GET /api/workspace/firewall/presets`	Member	Preset di regole integrati.
`GET /api/workspace/firewall/templates`	Member	Galleria di template per caso d’uso.
`POST /api/workspace/firewall/templates/apply`	Developer+	Applica un template → una policy + le sue regole.
`POST /api/workspace/firewall/autonomy`	Developer+	Applica un livello di autonomia (`tight` / `balanced` / `permissive`).
`POST /api/workspace/firewall/autonomy/undo/:audit_id`	Developer+	Undo a un clic dallo snapshot di audit.
`GET /api/workspace/firewall/simulate`	Member	Cosa un livello bloccherebbe (`?level=`).
`POST /api/workspace/firewall/test`	Developer+	Dry-run di una policy contro una chiamata di esempio.

Osservabilità

Metodo & path	Ruolo	Scopo
`GET /api/workspace/firewall/discovered-tools`	Member	Tool visti, marcati covered / gap.
`GET /api/workspace/firewall/events`	Developer+	Elenca gli eventi del firewall (filtrabili).
`GET /api/workspace/firewall/events/by-request/:request_id`	Developer+	Eventi per una singola richiesta.
`GET /api/workspace/firewall/events/aggregate`	Developer+	Aggregazione per runs / sessions.
`GET /api/workspace/firewall/trace/by-run`	Developer+	Nodi di trace per un’esecuzione (`?run_id=`).
`GET /api/workspace/firewall/anomalies`	Member	Feed delle anomalie.
`POST /api/workspace/firewall/anomalies/snooze`	Developer+	Mette in snooze il feed (≤ 7 giorni).

MCP server

Registra i Model Context Protocol server che i tuoi agent raggiungono, dietro un unico gateway sottoposto ad audit. Le credenziali sono memorizzate cifrate e mascherate in lettura.

Metodo & path	Ruolo	Scopo
`GET /api/workspace/firewall/mcp_servers`	Member	Elenca i server registrati.
`GET /api/workspace/firewall/mcp_servers/:id`	Member	Dettaglio del server.
`POST /api/workspace/firewall/mcp_servers`	Developer+	Registra un server (`409` su un `name` duplicato).
`PUT /api/workspace/firewall/mcp_servers`	Developer+	Aggiorna un server.
`DELETE /api/workspace/firewall/mcp_servers/:id`	Developer+	Rimuove un server.
`POST /api/workspace/firewall/mcp_servers/:id/probe`	Developer+	Raggiungibilità + handshake `tools/list`.

Un server porta un name univoco, un endpoint, un auth_mode (none / bearer / oauth / basic) e uno status di salute (ok / degraded / down). Vedi Firewall MCP per il ciclo di vita completo e la quarantena delle skill.

4. Applicare al gateway

Queste girano su una chiave con scope firewall-gateway, non sulla tua sessione. Sono ciò che il loop del tuo agent o client MCP chiama a runtime.

Metodo & path	Scopo
`POST /api/v1/firewall/evaluate`	Verdetto pre-dispatch per una singola chiamata a tool.
`POST /api/v1/firewall/evaluate_plan`	Controllo pre-esecuzione per un piano multi-step.
`ANY /api/v1/firewall/mcp`	L’endpoint unificato del gateway MCP.
`GET /api/v1/firewall/mcp_servers`	Enumera i server registrati del workspace.
`GET /api/v1/firewall/approvals/:id`	Polling sullo stato di approvazione di una chiamata held.
`POST /api/v1/firewall/approvals/:id/callback`	Callback di approvazione firmato con HMAC.

Un esempio concreto: valutare una chiamata a tool

Prima che il tuo agent dispatchi un tool, chiedi al gateway un verdetto. Passa la chiave con scope firewall-gateway — non la tua chiave di relay sk-orca-…:

curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer <firewall-gateway-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" }
  }'

La risposta porta il verdetto — allow, audit, deny, sanitize o pending_approval. Su deny salti la chiamata e fai emergere la motivazione al modello; su sanitize inoltri gli argomenti ripuliti che il gateway restituisce (sanitize redige solo gli argomenti della chiamata a tool — mai il contenuto che un tool restituisce); su pending_approval entri nel loop di approvazione qui sotto.

Il gateway valuta le chiamate che lo attraversano — l’hook di evaluate, il gateway MCP e il percorso del relay. Un tool che il tuo agent esegue interamente in-process, senza mai toccare OrcaRouter, è fuori dalla sua vista. Instrada le chiamate che contano (tool mediati dal modello, dispatch MCP, egress di rete) attraverso il gateway e sono governate.

5. L’handshake di approvazione (HITL)

Un verdetto pending_approval mette la chiamata in attesa di un umano. L’errore HTTP mentre è held è firewall_approval_pending. Sbloccarlo è un loop a tre passi diviso tra entrambe le famiglie di rotte:

Un revisore risolve l'hold

Dalla console (PATCH /api/workspace/firewall/approvals/:id, Developer+), o il tuo sistema invia un callback firmato con HMAC a POST /api/v1/firewall/approvals/:id/callback. Il callback verifica l’HMAC inline — nessun’altra auth è accettata.

Il tuo agent fa polling sull'approvazione

GET /api/v1/firewall/approvals/:id con la chiave del gateway, finché lo stato non passa ad approvato o rifiutato.

Ri-invia con il token monouso

Una volta approvata, ri-emetti la chiamata originale portando l’header X-OrcaRouter-Firewall-Approval con l’id di approvazione. Il gateway lo riconosce e lascia passare quella sola chiamata. L’header è monouso.

Le decisioni sono first-writer-wins e idempotenti — una seconda risoluzione dello stesso hold è un no-op. Vedi Firewall — Approvazione umana per il flusso end-to-end e Perché è stato bloccato? per leggere un verdetto.

6. Com’è fatto un block

Esito	HTTP	Codice
Chiamata a tool negata (superficie inbound)	`400`	`firewall_blocked`
Negata tramite gateway MCP	errore di tool	`firewall deny: <reason>`
In attesa di approvazione	`400`	`firewall_approval_pending`

firewall_blocked è marcato skip-retry — ri-eseguire la chiamata identica si limiterebbe a bloccarla di nuovo, quindi un client che fa retry si dà tregua invece di martellare. La lista completa dei codici vive in Codici di errore.

7. Riferimenti correlati

API Guardrail

Il pari della content-policy — le rotte /api/guardrail/* per il piano del testo.

Glossario dei verdetti

Ogni verdetto e cosa fa a una chiamata.

Glob e JSONPath

La grammatica di matching dietro tool_name_glob e args_match.

API Compliance

Pack, report firmati, residency ed erasure.

8. FAQ

Perché la mia chiave di relay riceve un 403 su /api/v1/firewall/evaluate?

Le rotte del gateway richiedono una chiave con scope firewall-gateway — una coniata con is_firewall_gateway impostato (un’azione Admin+). Una normale chiave di relay, anche valida, riceve 403. Conia una chiave gateway dedicata per il runtime del tuo agent.

Un viewer può leggere gli eventi del firewall?

No. Le rotte events, events/aggregate e trace sono Developer+ perché i record portano la provenienza degli argomenti delle chiamate a tool. I viewer possono leggere impostazioni, policy, preset, discovered tools, simulate e il feed delle anomalie.

Dove risolvo un'approvazione in attesa — console o gateway?

Entrambi. Un umano la risolve nella console tramite PATCH /api/workspace/firewall/approvals/:id (Developer+), o il tuo sistema invia una decisione firmata con HMAC a POST /api/v1/firewall/approvals/:id/callback. L’agent fa polling su GET /api/v1/firewall/approvals/:id indipendentemente da quale percorso l’ha risolta.

sanitize ripulisce ciò che un tool restituisce?

No. Un verdetto sanitize redige solo gli argomenti della chiamata a tool — mai il contenuto che un tool restituisce. Sulla superficie inbound, dove non ci sono ancora argomenti al momento della chiamata, sanitize escala a un block. Vedi Regole del firewall.

Per come questi controlli si compongono con i guardrails e il resto del gateway, vedi Proteggere gli agent AI e Guardrails vs Firewall.

​1. Le due famiglie di rotte

Console — configura

Gateway — applica

​2. Ruoli in sintesi

​3. Configurare una policy dalla console

​Policy e impostazioni

​Postura, preset e sandbox

​Osservabilità

​MCP server

​4. Applicare al gateway

​Un esempio concreto: valutare una chiamata a tool

​5. L’handshake di approvazione (HITL)

​6. Com’è fatto un block

​7. Riferimenti correlati

API Guardrail

Glossario dei verdetti

Glob e JSONPath

API Compliance

​8. FAQ

1. Le due famiglie di rotte

2. Ruoli in sintesi

3. Configurare una policy dalla console

Policy e impostazioni

Postura, preset e sandbox

Osservabilità

MCP server

4. Applicare al gateway

Un esempio concreto: valutare una chiamata a tool

5. L’handshake di approvazione (HITL)

6. Com’è fatto un block

7. Riferimenti correlati

8. FAQ