Regole
Il linguaggio di matching — glob di tool, clausole sugli argomenti, elenchi
egress, sanitizer e sequenze.
MCP server
Registra e governa i Model Context Protocol server dietro un unico gateway
sottoposto ad audit.
Skill
Scansiona e assegna un punteggio di rischio alle capability che i tuoi agent
installano prima che possano girare.
1. Cos’è il Firewall
Un agent AI non si limita a generare testo — agisce. Chiamashell.exec,
interroga db.query, recupera un URL, carica una skill della community o instrada
una chiamata a tool attraverso un MCP server di terze parti. Ognuna di queste è
un’azione con conseguenze reali, e i guardrail a livello di prompt non riescono a
vederle.
Il Firewall è una policy nominata, con scope a livello di workspace che il
gateway valuta su ogni chiamata a tool. Crei una policy una volta, le colleghi una
chiave API (o ne imposti una come default del workspace), e da quel momento ogni
chiamata a tool emessa da quella chiave viene controllata rispetto alla policy —
prima che raggiunga il tool.
Ogni policy è un elenco ordinato di regole. Una regola decide una cosa — a
quali chiamate a tool si applica (un glob sul nome del tool, opzionalmente con
scope su una skill e su una superficie di applicazione) e cosa farne (un
verdetto: allow, audit, deny, sanitize, mettere in attesa di approvazione o
limitare il costo). Il motore percorre le regole in ordine di priorità, vince il
primo match, e ricade sul verdetto di default della policy se nulla
corrisponde.
Modificare una policy ha effetto su ogni chiave ad essa collegata alla
chiamata successiva. Nessun redeploy. Nessuna modifica al codice dell’agent. La
policy è applicata nel gateway — il tuo agent continua a emettere chiamate a tool
esattamente come prima.
La detection avviene nel gateway, al primo uso. Il Firewall si trova sul
percorso del relay LLM, non all’interno del package manager o del filesystem del
tuo agent. 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 — non al
momento dell’installazione. È deliberato: è l’unico punto di strozzatura che vede
ogni provider, ogni agent e ogni chiamata a tool indipendentemente da come la
capability è arrivata lì.
2. Le quattro superfici di applicazione
Ogni chiamata a tool è valutata rispetto a esattamente una superficie — il punto del ciclo di vita della richiesta in cui il firewall la vede:| Superficie | Cosa vede |
|---|---|
inbound | I tool che un agent pubblicizza al modello sulla richiesta (definizioni dei tool). Ti permette di bloccare 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 del Firewall o valutato tramite l’hook dell’SDK. |
egress | Una destinazione di rete in uscita (host / IP / CIDR) segnalata da un tool — la superficie di SSRF ed esfiltrazione di dati. |
3. Concetti fondamentali
| Concetto | Definizione |
|---|---|
| Policy | Un insieme di regole nominato, con scope a livello di workspace. Ha enabled, is_default, un default_verdict e un flag shadow_mode. |
| Regola | Un controllo all’interno di una policy: una priorità, un match su tool/skill, una superficie opzionale, un predicato opzionale sugli argomenti e un verdetto. Vedi Regole. |
| Verdetto | L’azione che una regola (o il default) produce — vedi §4. |
| Verdetto di default | Applicato quando nessuna regola corrisponde. Uno tra allow, audit (default) o deny. |
| Shadow mode | La policy valuta e logga ma non blocca mai — ogni verdetto applicativo viene declassato a audit e la motivazione è prefissata con [shadow] would …. Il tuo interruttore per un rollout sicuro. |
| Observe mode | Un’impostazione a livello di workspace. Quando una richiesta si risolve in nessuna policy e l’observe mode è attivo, la chiamata viene consentita ma loggata come un gap di copertura — è ciò che popola la vista dei Discovered-tools. |
Scoping e risoluzione
Le policy si risolvono esattamente come i Guardrails e le chiavi API — condivise a livello di workspace quando hai un workspace attivo. Per ogni chiamata a tool il gateway risolve la policy in quest’ordine:- Collegamento della chiave — se la chiave chiamante ha un
firewall_policy_id, quella policy si applica (quando esiste ed è abilitata). - Default del workspace — altrimenti si applica la policy
is_defaultabilitata del workspace. - Nessuno dei due — nessuna applicazione. Con l’observe mode attivo, la chiamata viene consentita e loggata come un gap; con esso disattivato, la chiamata viene consentita silenziosamente (byte-identica a un workspace che non ha mai abilitato la feature).
Fail-open sull’ignoto, fail-closed sull’ambiguo. Se la risoluzione della
policy incontra un errore transitorio, il gateway degrada a observe/allow anziché
mettere giù il traffico. Ma dove non applicare vanificherebbe la regola — un
report egress senza destinazione utilizzabile, un approval store irraggiungibile,
una skill la cui ownership non può essere risolta — il motore fa fail closed
(deny o hold). La disponibilità è preservata; la sicurezza non viene saltata
silenziosamente nei casi che contano.
4. Verdetti
Una regola (o il verdetto di default) produce uno tra:| Verdetto | Cosa fa |
|---|---|
allow | Lascia passare la chiamata. Loggata. |
audit | Consente, ma la registra per revisione. Il default_verdict predefinito — osserva tutto, blocca nulla, finché non sei pronto. |
deny | Blocca la chiamata. L’agent vede un errore di tool (o HTTP 400 sulla superficie inbound). |
sanitize | Redige le sottostringhe corrispondenti dagli argomenti del tool (segreti, PII) e inoltra la chiamata ripulita. Vedi sanitizer. Sulla superficie inbound — dove non ci sono ancora argomenti al momento della chiamata — sanitize escala a un block. |
pending_approval | Mette in attesa la chiamata per un umano. L’agent riceve una risposta “held”; un revisore approva o rifiuta fuori banda; l’agent ri-invia con un token di approvazione monouso. Vedi §7. |
cap_cost | Nega una volta che la spesa accumulata dell’esecuzione dell’agent supera un tetto in centesimi per regola. Un interruttore di sicurezza per i loop incontrollati. |
deny / sanitize / pending_approval vengono tutti declassati a
audit così puoi misurare l’impatto di una policy prima che modifichi il
traffico.
5. Come viene valutata una chiamata a tool
- Una chiamata a tool raggiunge il gateway (pubblicizzata inbound, emessa in una response, dispatchata attraverso il gateway MCP o segnalata come egress).
- Il motore risolve la policy attiva (§3).
- Percorre le regole della policy in ordine di priorità (priorità più bassa per prima; parità risolta per id della regola). Una regola corrisponde quando la sua superficie, il suo glob sul nome del tool, il suo glob opzionale sul nome della skill, le sue clausole opzionali sugli argomenti e il suo scope opzionale di egress tutti corrispondono.
- Vince il primo match → si applica il verdetto della regola. Se nessuna
regola corrisponde → il
default_verdictdella policy. - Se la chiamata è di proprietà di una skill
governata, la modalità di applicazione della skill viene applicata in aggiunta —
una skill in modalità
blockforza un deny; una skill in modalitàquarantineescala qualsiasi cosa al di sotto di deny apending_approval. - La decisione viene loggata come un evento del firewall (a meno che non sia un dry run), correlata all’esecuzione e alla sessione dell’agent.
6. Com’è fatto un block
Una chiamata negata sulla superficie inbound restituisce HTTP 400 con un corpo di errore in forma OpenAI, codice di errorefirewall_blocked e un messaggio
che nomina il tool e la motivazione — es. tool "shell.exec" blocked by firewall: destructive shell command. L’errore porta metadata strutturati (codice di
motivazione, fattori di rischio, punteggio) ed è marcato skip-retry
(rieseguire la stessa chiamata si limiterebbe a bloccarla di nuovo).
Una chiamata dispatchata attraverso il gateway MCP viene bloccata come un
errore di tool (firewall deny: <reason>) anziché un fallimento di trasporto,
così il modello vede il rifiuto e può reagire — scegliere un altro tool, chiedere
all’utente o fermarsi — invece di andare in crash.
Una chiamata held (pending_approval) restituisce HTTP 400 con codice
firewall_approval_pending e un id di approvazione su cui il client fa polling.
7. Approvazione umana (HITL)
Un verdettopending_approval trasforma una chiamata a tool in una revisione fuori
banda:
- Il motore accoda un record di approvazione e restituisce una risposta “held” che ne porta l’id; la chiamata non raggiunge il tool.
- Un revisore la risolve — dalla console (Developer+), o tramite un webhook callback firmato con HMAC verso il tuo sistema di approvazione.
- Il tuo agent (o l’SDK MCP) fa polling sull’id di approvazione; una volta
approvata ri-invia la chiamata originale con un header monouso
X-OrcaRouter-Firewall-Approval, e il gateway la lascia passare quella sola volta.
rule_changed così i revisori sanno
che il contesto è cambiato.
8. Livelli di autonomia — un unico interruttore per tutta la tua postura
Mettere a punto le policy regola per regola è il percorso preciso; i livelli di autonomia sono quello rapido. Un singolo controllo sostituisce atomicamente la postura del Firewall e dei Guardrails del tuo workspace in un’unica transazione, con undo a un clic:| Livello | Postura |
|---|---|
tight | Blocca shell distruttiva, segreti negli argomenti ed egress SSRF (default deny); guardrails PII Shield + Secrets Blocker attivi; observe mode disattivato. |
balanced | Audit della shell distruttiva, flag delle PII; observe mode disattivato. La postura di partenza consigliata. |
permissive | Nessuna policy applicativa, nessun guardrail; observe mode attivo così vedi comunque tutto. |
9. Rilevamento delle anomalie
Oltre alle regole statiche, il Firewall apprende la forma normale dell’uso dei tool di ciascun workspace e segnala le deviazioni su un feed leggibile dal viewer:- Picchi di rate / costo — l’attività per tool viene valutata rispetto a una
baseline ora-della-settimana appresa (una media mobile a 14 giorni), così
“100 chiamate
db.queryalle 3 di domenica notte” salta all’occhio anche se ogni chiamata è individualmente consentita. retry_loop— un agent che martella lo stesso tool che fallisce.novel_path— una transizione da tool a tool che questo workspace non ha mai fatto prima.
10. Osservabilità
Il Firewall lascia una traccia su cui puoi agire, tutta con scope a livello di workspace:| Superficie | Cosa ti dà |
|---|---|
| Events | Ogni valutazione, filtrabile per verdetto, superficie, tool, esecuzione e sessione. Il record grezzo dietro tutto il resto. |
| Runs & sessions | Eventi aggregati per esecuzione dell’agent o conversazione — ripartizione dei verdetti, tool e modelli distinti, primo/ultimo visto. La vista “cosa ha effettivamente fatto questo agent”. |
| Discovered tools | Ogni tool che il workspace ha visto, marcato covered (si applica una regola) o gap (nessuna lo fa). Guida la creazione delle policy dal traffico reale. |
| Simulate | Anteprima di cosa un livello di autonomia cambierebbe prima di applicarlo. |
| Test | Esegue un dry-run di una policy contro una chiamata a tool di esempio e mostra il verdetto, la regola corrispondente e la motivazione — nulla viene persistito, nulla viene dispatchato. |
| Audit | Ogni modifica a policy, regola e impostazioni scrive una riga di audit (workspace + centrale) dopo il commit della modifica. Segreti e blob delle regole non vengono mai loggati. |
11. Relazione con il resto del gateway
| Superficie | Come si compone con il Firewall? |
|---|---|
| Guardrails | Piani complementari. I Guardrails filtrano il testo di prompt/risposta; il Firewall governa le azioni dei tool. Entrambi possono applicarsi a una stessa richiesta. I livelli di autonomia impostano entrambi in una volta. |
| Routing | Indipendente. Il routing sceglie il modello/canale; il firewall giudica le chiamate a tool a prescindere da quale modello le ha servite. |
| Chiavi API | Una chiave si collega a una policy tramite firewall_policy_id; il binding vive sulla chiave nel gateway. Nessun collegamento fa fallback al default del workspace. |
| Gateway MCP | Il firewall è il gateway MCP — ogni server che registri dispatcha il suo tools/call attraverso il motore. |
| Skill | La modalità di applicazione di una skill governata si sovrappone al verdetto della regola, così una skill in quarantine viene messa in attesa anche se nessuna regola nomina i suoi tool. |
12. Collegare un agent al gateway del Firewall
Ci sono due modi in cui una chiamata a tool raggiunge il motore:- Gateway MCP — punta il tuo client MCP (Claude Desktop, Cursor, un framework
per agent) su
https://api.orcarouter.ai/api/v1/firewall/mcp. Il gateway espone i tool di ogni server registrato raggiungibile, con namespace<server>.<tool>, e valuta ognitools/callinline. Vedi MCP server. - Hook di evaluate — chiama
POST /api/v1/firewall/evaluatedal tuo loop di agent prima di dispatchare una chiamata a tool, e agisci sul verdetto.
403 su queste rotte.
13. Riferimento API
Tutte le rotte di console hanno scope a livello di workspace tramite il contesto del workspace e applicano RBAC in modo coerente: le letture e le sandbox di test/simulate sono aperte a ogni membro; le scritture richiedono Developer+.Policy e impostazioni
| Metodo & path | Ruolo | Scopo |
|---|---|---|
GET /api/workspace/firewall/settings | Member | Legge le impostazioni del firewall del workspace (observe mode, default). |
PUT /api/workspace/firewall/settings | Developer+ | Aggiorna le impostazioni. |
GET /api/workspace/firewall/policies | Member | Elenca le policy (con conteggi di regole + chiavi collegate). |
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 (409 se ci sono ancora chiavi collegate). |
Postura, preset e sandbox
| Metodo & path | Ruolo | Scopo |
|---|---|---|
GET /api/workspace/firewall/presets | Member | Preset di regole integrati. |
POST /api/workspace/firewall/autonomy | Developer+ | Applica un livello di autonomia. |
POST /api/workspace/firewall/autonomy/undo/:audit_id | Developer+ | Annulla una modifica di autonomia. |
GET /api/workspace/firewall/simulate | Member | Anteprima di un livello di autonomia (?level=). |
POST /api/workspace/firewall/test | Developer+ | Esegue un dry-run di una policy contro una chiamata a tool 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 (?window=). |
POST /api/workspace/firewall/anomalies/snooze | Developer+ | Mette in snooze il feed delle anomalie. |
Gateway (machine-to-machine)
Queste girano su un token con scope firewall-gateway, non sulla sessione di console:| 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/approvals/:id | Polling sullo stato di approvazione di una chiamata held. |
POST /api/v1/firewall/approvals/:id/callback | Callback di approvazione firmato con HMAC. |
14. FAQ
Cosa succede se nessuna policy si risolve su una chiamata a tool?
Cosa succede se nessuna policy si risolve su una chiamata a tool?
Con l’observe mode disattivato, il comportamento è byte-identico a un
workspace che non ha mai abilitato la feature — nulla viene bloccato o loggato.
Con l’observe mode attivo, la chiamata viene consentita ma registrata come
un gap di copertura così compare in Discovered tools.
Come faccio il rollout di una policy in sicurezza?
Come faccio il rollout di una policy in sicurezza?
Attiva la shadow mode. La policy valuta e logga esattamente come farebbe in
produzione, ma ogni verdetto applicativo viene declassato a
audit e la
motivazione è prefissata con [shadow] would …. Osserva le viste events e
runs, conferma che scatti su ciò che ti aspetti e su nulla che non vuoi, poi
disattiva la shadow mode per iniziare ad applicare.Una chiamata a tool bloccata costa quota?
Una chiamata a tool bloccata costa quota?
Un block inbound scatta prima della chiamata al modello upstream, quindi non
costa token del modello. I verdetti audit / allow non cambiano la fatturazione.
Una regola
cap_cost è essa stessa un controllo di fatturazione — nega una
volta che la spesa dell’esecuzione supera il tuo tetto in centesimi.Firewall o Guardrails — quale uso?
Firewall o Guardrails — quale uso?
Entrambi, per layer diversi. I Guardrails filtrano il testo nei prompt e
nelle risposte (PII, segreti, jailbreak). Il Firewall governa le azioni che
un agent compie (quali tool, quali MCP server, quali host). Una richiesta può
attraversare entrambi. Il livello di autonomia
tight li configura insieme.L'applicazione è garantita per ogni tool che un agent esegue?
L'applicazione è garantita per ogni tool che un agent esegue?
Il Firewall applica sulle chiamate a tool che attraversano il gateway — il
percorso del relay, il gateway MCP e l’hook di evaluate. Un tool che il tuo
agent esegue interamente all’interno del proprio processo, senza mai toccare il
gateway, è al di fuori della vista del firewall. L’obiettivo di design è rendere
il gateway l’unico percorso sottoposto ad audit per le chiamate che contano
(tool mediati dal modello, dispatch MCP, egress di rete); instradale attraverso
di esso e sono governate.
Vedi anche
Vuoi approfondire la sicurezza degli agent? Le guide Proteggi i tuoi agenti (Zero Trust) inseriscono questa feature in un workflow zero-trust.Proteggi i tuoi agenti (Zero Trust)
Il playbook del firewall per agent zero-trust — allow-list dei tool, controlli sugli argomenti e controllo dell’egress.
Baseline Secure Agents
Un unico switch che imposta insieme la postura del tuo Firewall e dei Guardrails.