Questa pagina riguarda i controlli del gateway che limitano il raggio di
esplosione. Il contesto del modello di threat upstream — perché gli agent sono
target di alto valore e come funziona l’injection — è in
Modello di threat. Per il controllo
corrispondente che governa le singole chiamate a tool pericolose, vedi
Chiamate a tool pericolose.
1. Cosa rende un agent eccessivamente capace
Quando ogni agent in un workspace condivide una chiave, o quando una chiave viene emessa una volta e mai riesaminata, la capability deriva verso l’alto:- Modelli non limitati — l’agent può chiamare qualsiasi modello nel workspace, inclusi quelli costosi o altamente capaci di cui non ha mai bisogno.
- Nessun tetto di spesa — un loop incontrollato, un’injection attivata o un attacco di billing può esaurire il saldo del workspace prima che te ne accorga.
- Nessuna scadenza — una chiave emessa durante uno sprint è ancora valida un anno dopo, molto tempo dopo che l’agent per cui è stata creata è stato ritirato.
- Nessun vincolo IP — la credenziale funziona da qualsiasi posto, quindi una chiave trapelata non ha limiti geografici.
- Nessuna allowlist dei tool — l’agent può invocare qualsiasi tool, anche quelli non correlati alla sua funzione.
2. Il pattern del confused deputy
Il confused deputy è una specializzazione dell’eccessiva agenzia. L’agent non viene dirottato; viene convinto. Un payload di prompt injection in una pagina web recuperata, in un documento o nel risultato di un tool dice all’agent di compiere un’azione che è legittimamente autorizzato a eseguire — spostare denaro, eliminare un record, inviare un messaggio — per conto dell’attaccante. L’agent agisce. Era autorizzato a fare esattamente quello. Il controllo di autorizzazione passa. Il danno è fatto. La difesa richiede due cose che lavorano insieme:- Scope ristretto — l’agent non può essere ingannato a fare qualcosa che il suo compito non ha mai inteso, perché non è autorizzato a farlo del tutto.
- Approvazione umana per le azioni irreversibili — anche all’interno dello scope autorizzato, una chiamata ad alto rischio richiede che un essere umano confirmi prima dell’esecuzione.
3. Difesa in profondità: i quattro layer
OrcaRouter applica la minima agenzia attraverso quattro controlli indipendenti che si compongono su una singola chiave API. Nessuno richiede una modifica al codice del tuo agent.Layer 1 — Chiave con scope (identità + limiti rigidi)
Ogni agent dovrebbe avere la propria chiave API. La chiave porta limiti rigidi che il gateway applica indipendentemente da ciò che l’agent richiede:| Campo | Cosa limita |
|---|---|
model_limits | L’esatto set di modelli che questa chiave può chiamare. Una richiesta per qualsiasi altro modello viene rifiutata prima di lasciare il gateway. |
allow_ips | Le richieste da qualsiasi indirizzo non su questa lista vengono rifiutate al layer di autenticazione. Vuoto significa nessuna restrizione IP. |
credit_limit_usd | Tetto di spesa lifetime in USD. 0 significa illimitato. Il gateway lo applica rispetto alla spesa cumulativa sulla chiave. |
expired_time | Timestamp di scadenza assoluto. -1 significa che la chiave non scade mai. Impostalo al ciclo di vita del deployment dell’agent. |
environment | Un’etichetta (prod, staging, dev) per organizzare le chiavi e filtrare i log di audit. |
Layer 2 — Policy del firewall (allowlist dei tool)
Collega una policy del firewall alla chiave tramitefirewall_policy_id. La policy governa ogni chiamata a tool che quella chiave
emette:
- Scrivi regole che consentono i nomi dei tool che l’agent usa legittimamente
(i glob del nome del tool sono supportati — es.
db.query*). - Imposta il
default_verdictdella policy sudenycosì tutto ciò che non è esplicitamente elencato viene bloccato. - Aggiungi predicati sugli argomenti per limitare anche i tool consentiti —
es. consenti
db.querysolo quando l’argomentodatabasecorrisponde a uno schema specifico.
Layer 3 — Approvazione umana per le azioni ad alto rischio (pending_approval)
Per le chiamate a tool irreversibili o di alto valore — un dispatch di pagamento,
l’eliminazione di un record, l’invio di un’email — aggiungi una regola
pending_approval. Il flusso:
- L’agent emette la chiamata a tool. Il firewall la trattiene e restituisce una risposta “held” che porta un id di approvazione. La chiamata non raggiunge il tool.
- Un revisore approva o rifiuta fuori banda — dalla console (Developer+) o tramite un webhook firmato con HMAC verso il tuo sistema di approvazione.
- Il tuo agent fa polling sull’id di approvazione. Una volta approvato, ri-invia
la chiamata originale con un header
X-OrcaRouter-Firewall-Approvalmonouso. Il gateway la lascia passare esattamente una volta.
Layer 4 — Tetto di costo per esecuzione (cap_cost)
Una regola cap_cost nega qualsiasi chiamata a tool una volta che la spesa
accumulata dell’esecuzione dell’agent supera un tetto per regola (in centesimi).
Questo è il circuit-breaker per:
- Loop incontrollati attivati dall’injection.
- Attacchi di billing che guidano la spesa prima che qualsiasi essere umano se ne accorga.
- Ricorsione accidentale in piani multi-step.
cap_cost opera al livello dell’esecuzione, non al livello della lifetime
della chiave — quindi si azzera per ogni invocazione dell’agent, e una singola
esecuzione che si comporta male non può esaurire il tetto credit_limit_usd
della chiave.
4. Una chiave agent ben configurata — esempio
Un agent che riassume i ticket dei clienti usandogpt-4o-mini e interroga
una replica in sola lettura dovrebbe essere configurato così:
model_limits:["openai/gpt-4o-mini"]— non può scalare a un modello più capace o costoso.allow_ips: il CIDR di egress del worker pool — la chiave è inerte ovunque else.credit_limit_usd: un tetto settimanale corrispondente al costo previsto del task, con un po’ di margine — es.5.00.expired_time: la fine dello sprint o del periodo di deployment — la chiave si auto-scade senza pulizia manuale.environment:"prod"— appare nei filtri dei log e nelle viste delle anomalie.guardrail_id: un guardrail con scope alla sensibilità dei dati di questo agent (masking PII, nessun segreto nell’output).firewall_policy_id: una policy che consente solodb.query*eticket.read*, verdetto di defaultdeny.
is_firewall_gateway segna una chiave come token con scope gateway per le
rotte di dispatch MCP e evaluate hook. Crea queste solo per gli agent che
guidano il firewall in modo programmatico — mai per il traffico di inferenza
generale. Una chiave gateway sul percorso di inferenza espone rotte che le
chiavi general-purpose non dovrebbero mai raggiungere. Abilitare
is_firewall_gateway richiede Admin+.5. Ruoli richiesti
| Azione | Ruolo minimo |
|---|---|
| Leggi qualsiasi chiave, policy o evento del firewall | Member |
| Crea o modifica chiavi, policy del firewall, regole | Developer |
| Approva una chiamata a tool trattenuta dalla console | Developer |
Abilita is_firewall_gateway su una chiave | Admin |
6. Relazione con altre minacce
L’eccessiva agenzia è l’abilitatore per quasi ogni altra minaccia per gli agent:- Chiamate a tool pericolose — una chiave con una allowlist dei tool restrittiva non può essere forzata a chiamare un tool che non elenca, anche se l’injection ha successo.
- Prompt injection — i limiti di scope limitano il danno che l’injection può fare; le porte di approvazione bloccano le azioni irreversibili che l’injection cerca di attivare.
- Modello di threat — la mappa completa della superficie d’attacco, che mostra dove si trova l’eccessiva agenzia rispetto agli altri vettori.
Chiavi con scope e policy
Il riferimento completo dei campi della chiave, l’ordine di risoluzione e
il modello del confine del workspace.
Firewall
Scrittura delle policy, verdetti, flusso di approvazione HITL e riferimento
API completo.
