Vai al contenuto principale
Un agent AI non si limita a generare testo — agisce. Chiama shell.exec, interroga un database, recupera un URL, dispatcha un tool attraverso un MCP server. Ognuna di queste è un’azione con conseguenze reali che i guardrails a livello di prompt non riescono a vedere. L’agent firewall è il piano a livello di azione che le governa: una policy nominata, con scope a livello di workspace, che il gateway valuta su ogni chiamata a tool, prima che raggiunga il tool. Questa pagina è l’hub della sezione Firewall — il modello di policy, i verdetti, le superfici e come una policy si collega a una chiave. Ogni pagina spoke approfondisce, e il riferimento completo del motore vive in Firewall e Regole del Firewall.

​
1. Cosa fa l’agent firewall

Crei una policy una volta nella console del tuo workspace, le colleghi una chiave API (o ne imposti una come default del workspace), e da quel momento ogni chiamata a tool che quella chiave emette viene controllata rispetto alla policy nel gateway. Nessun redeploy, nessuna modifica al codice dell’agent — il tuo agent continua a emettere chiamate a tool esattamente come prima, e modificare la policy ha effetto sulla chiamata successiva per ogni chiave ad essa collegata. Una policy è un elenco ordinato di regole. Ogni regola decide a quali chiamate a tool si applica e cosa farne. Il motore percorre le regole in ordine di priorità, vince il primo match, e ricade sul verdetto di default della policy se nulla corrisponde.
La detection avviene nel gateway, al primo uso — non al momento dell’installazione. Un tool, un MCP server o una skill che un agent auto-installa viene intercettato la prima volta che la sua chiamata attraversa il gateway. È l’unico punto di strozzatura che vede ogni provider, ogni agent e ogni chiamata a tool indipendentemente da come la capability è arrivata lì.

​
2. Un esempio concreto

Supponiamo che tu voglia bloccare i comandi shell distruttivi ma lasciar passare tutto il resto sotto audit. Nella console crei una policy con default_verdict = audit e una regola: 
{
  "label": "block rm -rf",
  "tool_name_glob": "*.exec",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf|drop table\"}]}",
  "verdict": "deny"
}
args_match_json è una stringa codificata in JSON (il gateway la valida rispetto allo schema delle clausole al salvataggio): path è un JSONPath dentro gli argomenti della chiamata, op è uno tra eq, contains, regex, in, cidr_match, gt, lt. Collega una chiave alla policy (imposta firewall_policy_id sulla chiave). Ora, quando un agent emette shell.exec con command: "rm -rf /", il gateway restituisce HTTP 400 con codice di errore firewall_blocked e una motivazione che nomina il tool — e la chiamata non raggiunge mai la shell. Ogni altra chiamata a tool viene consentita e registrata per revisione.
Fai il rollout di una nuova policy sotto shadow mode prima: valuta e logga esattamente come farebbe in produzione, ma ogni verdetto applicativo viene declassato a audit e la motivazione è prefissata [shadow] would …. Osserva il feed degli eventi, poi disattiva la shadow per applicare.

​
3. Policy, regole e risoluzione

Una policy ha scope a livello di workspace ed è nominata, con enabled, is_default, un default_verdict (allow / audit / deny, default audit) e un flag shadow_mode. Una regola è un controllo al suo interno — vedi Crea una policy e Schema delle regole. Per ogni chiamata a tool il gateway risolve la policy attiva in quest’ordine:
  1. Collegamento della chiave — il firewall_policy_id della chiave chiamante, quando quella policy esiste ed è abilitata.
  2. Default del workspace — altrimenti la policy is_default abilitata.
Una policy del firewall collegata e disabilitata ricade sul default del workspace — questo differisce dai guardrails, dove un collegamento disabilitato si risolve in nessuno. L’interruttore di spegnimento sul firewall di una chiave significa “usa il default”, non “nessuna applicazione”. Vedi Gestisci le policy.
Quando nessuna policy si risolve, il comportamento dipende dall’impostazione firewall_observe_mode del workspace: con l’observe mode attivo, la chiamata viene consentita ma loggata come un gap di copertura (compare in Discovered Tools); con esso disattivato, la chiamata viene consentita silenziosamente.

​
4. Verdetti

Una regola — o il default — produce uno tra:
VerdettoCosa fa
allowLascia passare, loggato.
auditConsente + registra per revisione. Il default abituale.
denyBlocca. HTTP 400 firewall_blocked su inbound; errore di tool su MCP.
sanitizeRedige le sottostringhe corrispondenti dagli argomenti del tool e inoltra.
pending_approvalMette in attesa per un umano; HTTP 400 firewall_approval_pending.
cap_costNega una volta che la spesa dell’esecuzione supera un tetto per regola.
Un verdetto sanitize redige solo gli argomenti della chiamata — 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 Verdetti e Sanitizza le risposte.

​
5. Le quattro superfici di applicazione

Ogni chiamata a tool è valutata rispetto a esattamente una superficie — fissa una regola a una sola con il campo stage, o lascialo vuoto per applicarla a tutte.

inbound

I tool che un agent pubblicizza al modello sulla richiesta. Blocca un tool pericoloso prima ancora che il modello possa sceglierlo.

response

I tool_calls che il modello emette nella sua risposta.

mcp

Un tools/call dispatchato attraverso il gateway MCP. Vedi MCP server.

egress

Un host / IP / CIDR in uscita che un tool raggiunge — la superficie di SSRF ed esfiltrazione di dati.

​
6. Matching

Le regole esprimono quali chiamate a tool intercettano con un vocabolario piccolo e deterministico, sicuro sul percorso caldo:
Un glob case-sensitive sul nome del tool (shell.*, *.delete), opzionalmente in AND con un glob sulla skill proprietaria. Vedi Sintassi glob e Allow-listing dei tool.
Predicati JSONPath sugli argomenti della chiamata con gli operatori eq, contains, regex, in, cidr_match, gt, lt — la differenza tra “blocca shell.exec” e “bloccalo solo quando il comando è rm -rf.” Le clausole fanno fail closed (la regola, non la richiesta). Vedi Valida gli argomenti.
Elenchi di allow e deny per host / IP / CIDR sulla superficie egress. Puoi scrivere la tua regola di deny per i range cloud-metadata o RFC-1918. Vedi Controllo dell’egress.
Una regola sequence corrisponde a una catena ordinata di chiamate in una finestra (applicata reattivamente); una regola cap_cost nega una volta che la spesa accumulata di un’esecuzione dell’agent supera un tetto in centesimi. Vedi Regole di sequenza e Tetto di costo.

​
7. Approvazione umana, autonomia e anomalie

  • Human-in-the-loop. Un verdetto pending_approval mette in attesa la chiamata e restituisce il suo id di approvazione. Un revisore la risolve nella console (Developer+) o tramite un webhook callback firmato con HMAC; l’agent fa polling e ri-invia con un header monouso X-OrcaRouter-Firewall-Approval. Vedi Approvazioni e Webhook di approvazione.
  • Livelli di autonomia. Un singolo interruttore imposta tutta la tua postura: tight (default-deny + deny della shell distruttiva + deny dei tool a forma di fetch (http_fetch/web_search/fetch_url/request, il vettore SSRF) + PII Shield + Secrets Blocker applicati), balanced (audit di default, deny della shell distruttiva, PII Shield solo in audit), o permissive (solo observe). Ognuno scrive righe di policy e di guardrail reali e modificabili, con undo a un clic dallo snapshot di audit.
  • Rilevamento delle anomalie. Oltre alle regole statiche, il firewall valuta l’uso dei tool rispetto a una baseline ora-della-settimana appresa (14 giorni) e segnala picchi di rate/costo, retry_loop e novel_path su un feed leggibile dai Member che puoi mettere in snooze per un massimo di 7 giorni.

​
8. Dove si colloca il firewall

Il firewall è il pari a livello di azione di due piani adiacenti:
PianoGovernaQuando ricorrervi
GuardrailsTesto di prompt e rispostaPII, segreti, jailbreak, intento di injection
Agent firewallAzioni dei toolQuali tool, chiamate MCP, host e costo
ComplianceEvidenze e frameworkProntezza SOC 2 / HIPAA / EU AI Act
Sia il piano dei contenuti sia quello delle azioni possono applicarsi a una singola richiesta, e un livello di autonomia li configura insieme. Vedi Guardrails vs. Firewall e il control stack.

​
9. Collegamento e connessione

Una policy si lega a una chiave tramite firewall_policy_id (configurato nella console; il binding vive sulla chiave nel gateway). Due modi in cui una chiamata a tool raggiunge il motore, entrambi che richiedono una chiave con scope firewall-gateway (is_firewall_gateway = true) — una normale chiave di relay riceve 403 su queste rotte:
  • Gateway MCP — punta il tuo client MCP sull’endpoint unificato ANY /api/v1/firewall/mcp; ogni tools/call viene valutato inline. Vedi MCP server.
  • Hook di evaluate — chiama POST /api/v1/firewall/evaluate (o /evaluate_plan per un piano multi-step) dal tuo loop di agent prima di dispatchare, e agisci sul verdetto.
Tutta la configurazione di console gira sotto la tua sessione tramite /api/workspace/firewall/*. Le letture di policy, impostazioni, discovered tools, il simulatore di autonomia in sola lettura e il feed delle anomalie sono aperti a ogni membro del workspace; la sandbox di dry-run Test, il log Events / Runs e tutte le scritture richiedono Developer+. Vedi Chiavi del gateway e Testa le regole.

​
10. Minacce affrontate da questo piano

Chiamate a tool pericolose

Nega shell distruttiva, drop di DB e verbi rischiosi per glob + args.

Esfiltrazione di dati

Elenchi egress e regole di sequenza read-then-export.

MCP tool poisoning

Valutazione per chiamata sulla superficie mcp prima del dispatch.

Agenzia eccessiva

Approvazioni, tetti di costo e postura default-deny.

​
Passi successivi

Crea una policy

Crea la tua prima policy e regola.

Verdetti

Cosa fa ogni verdetto sul filo.

Log degli eventi

Leggi cosa ha deciso il firewall e perché.