Vai al contenuto principale
Quando un agent è dirottato — prompt injection, un risultato di tool avvelenato, un loop incontrollato — ciò che può effettivamente fare è limitato da esattamente una cosa: cosa la sua chiave API era autorizzata a fare. Una chiave senza limiti e senza policy trasforma un singolo agent compromesso in un incidente a livello di workspace. Questa pagina è il giro di hardening che esegui su ogni chiave prima che venga rilasciata, e di nuovo su una cadenza dopo. È deliberatamente breve: una checklist, un esempio svolto, poi link alla profondità per ciascun campo. Per il modello mentale dietro di essa, parti da Scope e chiavi; per il riferimento campo per campo, vedi la panoramica delle chiavi.

​
1. La checklist di minima agenzia

Fai passare ogni chiave — nuova o esistente — attraverso questi sei gate nell’editor delle chiavi (/console/token). Impostarne uno qualsiasi richiede il ruolo Developer o superiore; i due piani di policy (§5–6) sono scritti separatamente e collegati qui.
Imposta model_limits all’elenco esatto di cui questo agent ha bisogno (e abilita model_limits_enabled). Una chiamata a qualsiasi modello fuori dall’elenco viene rifiutata prima di lasciare il gateway, così un agent dirottato non può escalare a un modello più costoso o più capace. Verifica: l’elenco è il più corto che il lavoro consenta — idealmente un solo modello? Profondità: Limiti sui modelli.
Imposta allow_ips agli indirizzi sorgente o al CIDR da cui l’agent chiama effettivamente. Una chiave trapelata presentata da qualunque altro luogo viene rifiutata al livello di autenticazione. Vuoto significa che tutti gli IP sono consentiti. Verifica: per un agent a host fisso o schedulato, l’elenco è non vuoto e con scope su quell’egress? Profondità: IP allow-list.
Imposta credit_limit_usd a un tetto che l’agent non dovrebbe mai superare nel corso della sua vita. Il gateway lo applica rispetto alla spesa della chiave. 0 significa illimitata — un loop incontrollato può prosciugare l’intero saldo. Verifica: il cap è un budget reale, non 0? Profondità: Quota, cap e scadenza.
Imposta expired_time a una scadenza assoluta — la fine dello sprint, del deployment o dell’esecuzione di CI. -1 significa non scade mai. Una chiave a vita breve non può attardarsi come superficie d’attacco dimenticata. Verifica: una chiave effimera o di contractor ha una scadenza reale, non -1? Profondità: Chiavi a scadenza.
Collega un guardrail tramite guardrail_id così che il testo della richiesta (e, dove supportato, della risposta) sia filtrato per PII, segreti e intento di injection prima che raggiunga il modello. Verifica: una chiave che gestisce prompt sensibili ha un guardrail collegato, o eredita un default del workspace? Vedi §5.
Collega una policy del firewall tramite firewall_policy_id così che ogni chiamata a tool, dispatch MCP ed egress che questa chiave emette sia valutato rispetto a un’allow-list di ciò di cui l’agent ha legittimamente bisogno. Verifica: un agent che chiama tool ha una policy del firewall collegata, o eredita il default del workspace? Vedi §6.
I campi qui sopra sono le uniche leve configurabili dal cliente su una chiave — impostale tutte nella console; nulla qui richiede una modifica al codice dell’agent. Rileggere una chiave la mostra mascherata; il plaintext è mostrato una volta alla creazione. Vedi Mascheramento delle chiavi.

​
2. Cosa / quanto spesso / dove

Tre domande trasformano la checklist da incombenza una-tantum a postura.

Cosa

I sei gate qui sopra, in ordine: model_limits → allow_ips → credit_limit_usd → expired_time → guardrail_id → firewall_policy_id.

Quanto spesso

Su ogni chiave alla creazione, e su una revisione ricorrente — quando lo scope di un agent cambia, quando ruoti una chiave, e su una cadenza fissa per le chiavi a vita lunga.

Dove

Nell’editor delle chiavi della console (/console/token), come Developer+. Le due policy sono scritte nelle loro console, poi collegate sulla chiave.

​
3. Una chiave a minima agenzia concreta

Un agent schedulato che riassume i ticket di supporto con un unico modello economico, da un solo host, non ha quasi bisogno di agenzia. Una chiave pienamente sottoposta a hardening:
CampoValorePerché
model_limitsun modello di summarizationnon può escalare a un modello di frontiera
allow_ipsil CIDR di egress dello scheduleruna chiave trapelata è inutile altrove
credit_limit_usdun tetto settimanaleun loop incontrollato non può prosciugare il saldo
expired_timefine del deploymentsi auto-scade, non può attardarsi
guardrail_idun guardrail che maschera le PIIil testo della richiesta viene filtrato
firewall_policy_idmette in allow-list solo i suoi toolnessuna chiamata a tool a sorpresa
Se questo agent viene dirottato, può comunque chiamare solo un modello, solo da un range di IP, solo fino al suo cap, e solo i tool che la sua policy del firewall permette. Il resto del workspace resta intatto — e la traccia di audit del firewall mostra esattamente cosa era autorizzato a fare.
Una chiave senza model_limits, senza allow_ips, con credit_limit_usd: 0, expired_time: -1 e senza collegamento a policy ha agenzia massima. Se trapela, chi la possiede ottiene il tuo intero workspace. Tratta quella combinazione come una scoperta, non un default — vedi illimitate vs limitate.

​
4. La chiamata di relay /v1 vs la console

La checklist è configurata nella console con la tua sessione (un utente Developer+). Il tuo agent non tocca mai quelle rotte di config — presenta la sua chiave di relay con scope (sk-orca-…) sulle chiamate di inferenza /v1/*, e i limiti e le policy collegate qui sopra sono applicati su ciascuna. 
# La chiamata a runtime dell'agent — la chiave di relay, con scope dalla checklist sopra.
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Summarize this ticket..."}]
  }'
Se i model_limits della chiave non includono openai/gpt-4o-mini, questa chiamata viene rifiutata prima di lasciare il gateway. Se l’IP del chiamante non è in allow_ips, viene rifiutata al livello di autenticazione. Il codice dell’agent resta lo stesso; la chiave decide il raggio d’esplosione.

​
5. Gate 5 — il guardrail collegato

guardrail_id collega alla chiave una policy sui contenuti ordinata e con scope a livello di workspace. La risoluzione è il guardrail esplicito della chiave (se esiste ed è abilitato), altrimenti il default del workspace, altrimenti nessuno.
I guardrail sono un interruttore di spegnimento rigido quando disabilitati: un guardrail_id disabilitato o eliminato significa che la chiave non ottiene alcun guardrail — non fa fallback al default del workspace. È l’opposto del piano del firewall (§6), quindi verifica che il guardrail collegato sia abilitato, non solo collegato.
Le regole di un guardrail girano prima del modello (fase di input) e, dove supportato, sulla risposta (fase di output), con azioni block, mask o flag. Il preset PII Shield, ad esempio, maschera le PII nella richiesta prima che raggiunga mai il modello. Scrivi e collega i guardrail come Developer+ — vedi Guardrails e Collegare le policy.

​
6. Gate 6 — la policy del firewall collegata + lo scope gateway

firewall_policy_id collega una policy sulle chiamate a tool con scope a livello di workspace. Governa le azioni che un agent compie — tool pubblicizzati, tool_calls emessi dal modello, dispatch MCP ed egress in uscita — rispetto a un elenco ordinato di regole i cui verdetti sono allow, audit, deny, sanitize, pending_approval o cap_cost.
Il piano del firewall si risolve diversamente dai guardrail: una policy del firewall collegata e disabilitata fa fallback al default del workspace, non disattiva l’applicazione. Quindi collegare una policy e disabilitarla riporta la chiave al default del workspace — non resta mai silenziosamente senza protezione.
Il modo più rapido per impostare entrambi i piani in una volta è un livello di autonomia — un singolo interruttore che configura atomicamente la postura del firewall e dei guardrail del tuo workspace (tight / balanced / permissive), con undo a un clic. Vedi Firewall §8.
is_firewall_gateway è un tipo di chiave separato — coniato solo per le rotte del Firewall MCP e dell’evaluate-hook (/api/v1/firewall/*), mai per l’inferenza. Una chiave normale riceve 403 su quelle rotte, e una chiave gateway sul percorso di inferenza è over-scoped. Abilitare il flag, e leggere il plaintext di una chiave gateway, richiede Admin+. Una chiave, uno scopo.

​
7. Dopo la checklist

Baseline secure-agents

La postura di partenza consigliata — un interruttore di autonomia, poi metti a punto dal traffico reale.

Collegare le policy

Come guardrail_id e firewall_policy_id si collegano e si risolvono.

Agenzia eccessiva

La minaccia che questa checklist è costruita per contenere.

Chiave trapelata

Cosa fare nell’istante in cui una chiave con scope è esposta.
Più ristretta è ciascuna chiave, più piccolo è il raggio d’esplosione se un singolo agent viene compromesso — e più chiaro è il registro di cosa ciascun agent era autorizzato a fare. Esegui la checklist di minima agenzia su ogni chiave, e continua a eseguirla.