Il control stack: chiavi → guardrails → firewall → audit

OrcaRouter applica quattro layer a ogni richiesta in un ordine fisso. Ogni layer è indipendente, con scope a livello di workspace, e si collega a una chiave API senza modifiche al codice. Questa pagina percorre una richiesta attraverso tutti e quattro i layer in sequenza, poi copre l’ordine di risoluzione e il comportamento fail-open/fail-closed. Per un’introduzione più ampia vedi Proteggere gli agent AI con OrcaRouter.

​

1. Layer 1 — Chiave API con scope

La chiave è il primo gate. Prima che qualsiasi contenuto venga ispezionato o che qualsiasi modello venga chiamato, il gateway risolve la chiave chiamante e decide se la richiesta è anche solo consentita. Cosa porta la chiave:

• model_limits — il set di modelli che la chiave può chiamare. Una richiesta per un modello fuori dalla lista viene rifiutata immediatamente.
• allow_ips — allowlist di IP opzionale. Una richiesta da una sorgente non elencata viene rifiutata.
• credit_limit_usd — un tetto di spesa fisso. Una richiesta che spingerebbe la chiave oltre il tetto viene rifiutata.
• expiry — una data di scadenza fissa. Le chiavi scadute vengono rifiutate.
• environment — un tag (production, staging, dev, …) per organizzare e identificare la chiave per ambiente di deployment.
• guardrail_id — la policy del guardrail che si collega a questa chiave (vedi Layer 2 e Layer 4).
• firewall_policy_id — la policy del firewall che si collega a questa chiave (vedi Layer 3).
• is_firewall_gateway — segnala la chiave come token con scope di firewall-gateway; richiesto per le rotte evaluate e gateway MCP.

Una richiesta che fallisce la validazione della chiave non raggiunge mai un modello — e non viene mai misurata. Dove configurare: Console → API Keys, oppure la token API. Richiede Developer+ per creare o modificare; is_firewall_gateway e le letture in chiaro della chiave richiedono Admin. Per il modello completo della chiave vedi Scope, chiavi, policy e workspace.

​

2. Layer 2 — Guardrails in input

Una volta validata la chiave, il gateway esegue le regole di stage input del guardrail collegato rispetto al testo della richiesta — prima di qualsiasi chiamata al modello upstream. Cosa vede: I messaggi del chiamante come inviati. (Un prompt iniettato da un registry di prompt viene aggiunto successivamente, nella fase di routing; le regole di input non lo vedono.) Tipi di regola disponibili: keyword, regex, pii, max_chars, external, llm_judge, grounding. Azioni che una regola può produrre: Un block in questo stage significa che il modello non viene mai chiamato. Costo: zero. Il chiamante vede un errore strutturato che nomina il guardrail e la regola che ha scattato. Dove configurare: Console → Guardrails, oppure la guardrail API. Richiede Developer+ per creare o modificare. Vedi Guardrails per il riferimento completo delle regole.

​

3. Layer 3 — Il modello gira

Se la chiave è valida e i guardrails in input passano, il gateway inoltra la richiesta al modello upstream. Questo è l’unico layer senza applicazione configurabile — è semplicemente il modello che fa il suo lavoro. Il firewall opera sulle azioni che il modello produce (Layer 3 → Layer 4 sotto), non sul modello stesso. Il routing, i fallback e il load balancing avvengono qui in modo trasparente.

​

4. Layer 4 — Agent Firewall (chiamate a tool ed egress)

Dopo che il modello risponde — o inline, man mano che le chiamate a tool vengono emesse — l’Agent Firewall giudica ogni azione che il modello richiede. Quattro superfici di applicazione: Verdetti che una regola (o il default) può produrre: Un deny sulla superficie inbound non costa token del modello — il block scatta prima della chiamata upstream. Un hold pending_approval restituisce HTTP 400 firewall_approval_pending con un id di approvazione su cui il client fa polling. Dove configurare: Console → Firewall, oppure la firewall API. Richiede Developer+ per creare o modificare policy e regole. Vedi Firewall e Regole del firewall per il linguaggio completo delle regole.

​

5. Layer 5 — Guardrails in output

Dopo che il modello risponde (e dopo che qualsiasi ciclo di chiamate a tool si completa), il gateway esegue le regole di stage output del guardrail collegato rispetto al testo della risposta prima che raggiunga il chiamante. Gli stessi tipi di regola e azioni si applicano come nel Layer 2. Un block di output restituisce HTTP 400 guardrail_blocked e rimborsa la quota pre-consumata — il chiamante non paga nulla.

​

6. Layer 6 — Audit

Ogni match, verdetto e decisione di approvazione viene scritto nella traccia di audit, correlato all’esecuzione dell’agent e alla sessione che lo ha causato. Non è un passaggio di applicazione separato — gira in parallelo con i Layer 2–5 — ma è il layer che rende gli altri responsabili. Cosa viene loggato:

• Match dei guardrail: tipo di regola, azione, stage, stringa di dettaglio, e (se Log raw content è abilitato) la sottostringa corrispondente.
• Eventi del firewall: superficie, nome del tool, verdetto, regola corrispondente, codice di motivazione, fattori di rischio, e l’esecuzione/sessione a cui appartiene la chiamata.
• Decisioni di approvazione: chi ha approvato o rifiutato, quando, e se la regola sottostante è cambiata tra hold e decisione.
• Modifiche alle policy: ogni create, update, delete e modifica del livello di autonomia scrive una riga di audit versionata.

Dove consultare: Console → Guardrails → Matches; Console → Firewall → Events, Runs & Sessions, Audit. Il feed Matches del guardrail è aperto a qualsiasi Member del workspace; i feed Events e Runs & Sessions del firewall richiedono Developer+.

​

7. Tabella riassuntiva

​

8. Ordine di risoluzione delle policy

Per qualsiasi richiesta, il guardrail attivo e la policy del firewall vengono risolti indipendentemente:

1. Collegamento della chiave — se la chiave porta un guardrail_id o firewall_policy_id esplicito, quella policy si collega (quando esiste ed è abilitata).
2. Default del workspace — se la chiave non ha collegamento, si applica il guardrail o la policy is_default abilitata del workspace.
3. Nessuno dei due — nessuna applicazione. La richiesta è byte-identica a un workspace che non ha mai abilitato la feature.

I due piani differiscono quando una policy collegata è disabilitata: un collegamento guardrail disabilitato disattiva i guardrail per quella chiave (nessun fallback), mentre un collegamento firewall disabilitato ricade sulla policy del firewall di default del workspace. Al massimo un guardrail e una policy del firewall per workspace possono essere il default. Promuovere un nuovo default declassa il vecchio nella stessa transazione.

​

9. Fail-open e fail-closed

Vedi Modalità di applicazione per l’albero di decisione completo, e Come OrcaRouter ispeziona le richieste per la meccanica del percorso del relay.

​

10. Approfondimenti

Ogni chiamata attraverso OrcaRouter passa tutti e quattro i layer di applicazione nell’ordine — validazione della chiave, filtraggio in input, giudizio del firewall, filtraggio in output — con una traccia di audit completa scritta su tutti.