Vai al contenuto principale
Hai una policy che vuoi mettere davanti alla produzione. La paura non è la policy — è attivarla e scoprire che blocca un tool di cui il tuo agent ha davvero bisogno, o maschera un campo da cui la tua app dipende. La soluzione non è più testing in una sandbox; è fare il rollout contro traffico reale in una postura che non può rompere nulla, poi irrigidire solo una volta che hai visto cosa scatta. Questa ricetta è quel rollout: observe → shadow → enforce, con autonomia balanced prima di tight. Resti nella console (o nella REST API) per tutta la strada; l’agent continua a chiamare https://api.orcarouter.ai/v1/... esattamente come prima.
Nuovo al modello? Leggi Modalità di applicazione per cosa fa meccanicamente ciascuna postura, e la baseline Secure Agents per cosa imposta ciascun livello di autonomia. Questa pagina è la sequenza — l’ordine in cui attivi gli interruttori.

​
1. Il rollout di sicurezza AI in tre mosse

L’intero rollout baratta autonomia per sicurezza in tre passi, ciascuno verificato contro il traffico live prima del successivo:

Observe

Consenti tutto, logga tutto. Le chiamate a tool non coperte atterrano in Discovered Tools; le regole flag dei guardrail registrano match senza cambiare il traffico. Apprendi la forma reale del tuo agent.

Shadow

Una policy reale valuta ogni chiamata, ma ogni verdetto applicativo viene declassato a audit e loggato [shadow] would …. Vedi esattamente cosa verrebbe bloccato — con nulla effettivamente bloccato.

Enforce

Shadow disattivata. deny blocca, mask redige, pending_approval mette in attesa. L’autonomia va da ampia (balanced) a stretta (tight), e il tuo agent è governato.
La disciplina è il punto: non applichi mai una regola che non hai prima osservato scattare in shadow contro il tuo stesso traffico.

​
2. Mossa uno — observe (autonomia = permissive)

Parti il più ampio possibile. Applica il livello di autonomia permissive da Firewall → Posture (Developer+) — o POST /api/workspace/firewall/autonomy. Abilita l’observe mode del workspace e non lascia alcuna policy applicativa, così ogni chiamata è consentita e ogni chiamata non coperta è loggata come un gap di copertura. 
# Console: Firewall → Posture → applica "permissive"
# o, tramite la REST API sul tuo token di sessione:
curl https://api.orcarouter.ai/api/workspace/firewall/autonomy \
  -H "Authorization: Bearer <your console access token>" \
  -H "X-Workspace-Id: <workspace>" \
  -H "Content-Type: application/json" \
  -d '{"level": "permissive"}'
Le rotte /api/workspace/firewall/* girano sulla tua sessione di console / access token, non su una chiave di relay sk-orca-.... Applicare un livello di autonomia è una scrittura del workspace — Developer+. Solo le chiamate a modello /v1/* usano la chiave di relay.
Ora punta il traffico reale su di esso e lascialo girare. Osserva due feed:
  • Firewall → Discovered Tools (Member) — ogni tool che il tuo agent chiama, marcato covered o gap. Questo è l’input per le tue regole: stai per scrivere policy per traffico che accade davvero, non per ipotesi.
  • Guardrails → Matches (Member) — se hai aggiunto regole con azione flag, ogni match che registrano, senza toccare la richiesta.
Lascialo girare finché Discovered Tools smette di far emergere nuovi tool. Quella lista stabile è la tua specifica per scrivere le regole.

​
3. Mossa due — shadow (una policy reale, zero blocking)

Ora scrivi la policy che vuoi davvero — glob di tool, clausole sugli argomenti, liste egress, un tetto cap_cost — e attiva la shadow_mode prima di collegarla. (Costruisci le regole dalle regole del firewall; il modello di policy completo è nel riferimento Firewall.) 
{
  "name": "prod-rollout",
  "enabled": true,
  "shadow_mode": true,
  "default_verdict": "audit",
  "rules": [
    { "priority": 10, "tool_name_glob": "shell.exec", "verdict": "deny" },
    { "priority": 20, "tool_name_glob": "*",          "verdict": "cap_cost", "cap_cost_cents": 1000 }
  ]
}
Con shadow_mode: true, quel deny e quel cap_cost sono entrambi declassati a audit al momento della valutazione — il motore calcola il verdetto reale, lo logga prefissato [shadow] would …, e lascia passare la chiamata. Collega la policy alle chiavi di cui stai facendo il rollout (imposta firewall_policy_id sulla chiave) o rendila il default del workspace. Poi leggi Firewall → Events / Runs (Developer+) filtrato al prefisso [shadow] e conferma entrambi i lati:
Ogni chiamata shell.exec mostra [shadow] would deny. Ogni esecuzione che supera il tuo cap mostra [shadow] would cap_cost. La policy vede il traffico per cui l’hai costruita.
Nessun tool legittimo compare con un verdetto di avrebbe-bloccato. Questo è il controllo dei falsi positivi — la ragione per cui la shadow esiste. Se un tool di cui hai bisogno è segnalato, correggi la regola e ri-osserva prima di applicare mai.
I guardrail non hanno una shadow a livello di policy. L’equivalente è l’azione per-regola flag: registra un match nel feed Matches e non cambia nulla, così puoi misurare una regola di contenuto prima di passarla a block o mask. Esegui le tue regole di guardrail come flag attraverso questa stessa mossa.

​
4. Mossa tre — enforce (autonomia balanced, poi tight)

Quando il log di shadow sembra giusto, applica in due fasi, non una. Non saltare dritto al default-deny. Prima, balanced. Questa è la prima postura applicativa consigliata: il verdetto di default del firewall è audit, ma le azioni più distruttive (come la shell distruttiva) sono negate, e il guardrail PII Shield gira in solo-audit — segnala le PII senza ancora mascherarle. Ora stai bloccando la cosa peggiore mentre osservi ancora il resto. Disattiva la shadow_mode sulla tua policy nella stessa mossa così i suoi verdetti deny / cap_cost vanno live accanto alla baseline. 
curl https://api.orcarouter.ai/api/workspace/firewall/autonomy \
  -H "Authorization: Bearer <your console access token>" \
  -H "X-Workspace-Id: <workspace>" \
  -H "Content-Type: application/json" \
  -d '{"level": "balanced"}'
Osserva Events per un’ora. I block reali ora appaiono senza il prefisso [shadow]. Una chiamata a tool negata restituisce HTTP 400 firewall_blocked; è skip-retry e non costa token del modello. Poi, tight. Una volta che balanced è silenzioso, vai al default-deny. Il livello tight nega per default, nega la shell distruttiva e l’egress SSRF, e applica PII Shield + Secrets Blocker — le PII sono mascherate sulla richiesta prima che il modello la veda, e i segreti nelle tue richieste sono bloccati. Un prompt bloccato restituisce HTTP 400 guardrail_blocked, non costa alcuna quota, ed è skip-retry.
FaseFirewall (azioni)Guardrails (testo)Cosa stai dimostrando
permissiveObserve; nulla bloccatoSolo flagLa forma del traffico reale
balancedAudit di default; shell distruttiva negataPII segnalateIl caso peggiore è fermato
tightDefault-deny; shell + tool a forma di fetch (SSRF) negatiPII mascherate, segreti bloccatiZero-trust pieno
Avvertenza streaming per le PII. Sotto tight, il PII Shield maschera le PII sulla richiesta prima che il modello la veda — questo è attivo. Il masking sul lato output di una risposta in streaming non è ancora attivo; un block di output è applicato in streaming (lo scanner taglia lo stream). Se dipendi dal redigere l’output del modello, verifica la tua combinazione stage/stream nel tab Test del guardrail prima. Vedi Guardrails.

​
5. La via di fuga — undo a un clic

Ogni modifica di autonomia è un’unica transazione che fa snapshot della tua postura precedente, così puoi tornare dritto indietro da Firewall → Posture (o POST /api/workspace/firewall/autonomy/undo/:audit_id). Puoi anche semplicemente ri-applicare un livello più morbido — riporta tight a balanced, o balanced a permissive — in qualsiasi momento.
L’undo ripristina dallo snapshot di audit dell’applicazione più recente. Se hai fatto modifiche manuali alla policy dopo l’applicazione che stai annullando, quello snapshot non è più l’ultimo inutilizzato e l’undo declina anziché spazzare via silenziosamente quelle modifiche. Quando succede, ri-applica un livello più morbido invece — è sempre disponibile.

​
6. Da dove vengono i verdetti di ogni mossa

Il rollout non blocca mai qualcosa che non hai chiesto, perché ogni postura mappa su un meccanismo esplicito e osservabile:
PosturaMeccanismoEsito
ObserveWorkspace firewall_observe_mode on + guardrail flagAllow + log dei gap / match
Shadowshadow_mode per-policyVerdetto reale calcolato, declassato ad audit, loggato [shadow] would …
Enforceshadow_mode off + autonomia tight/balanceddeny / mask / cap_cost vanno live
I quattro termini — observe mode, il verdetto audit, l’azione flag e shadow_mode — sono interruttori distinti, documentati fianco a fianco in Modalità di applicazione.

​
7. Prossimi passi

Modalità di applicazione

La mappa dei meccanismi dietro observe, shadow ed enforce.

Baseline Secure Agents

Cosa imposta ogni livello di autonomia, e come simularlo prima.

Domare un agent autonomo

Il passo successivo una volta applicato: cap di costo, rilevamento delle anomalie e approvazioni.

Agent Firewall

Policy, regole, verdetti, shadow mode e il gateway MCP per intero.
Un go-live di cui ti puoi fidare è un rollout, non un interruttore. Osserva cosa fa il tuo agent, fai shadow della policy contro il suo traffico reale, poi applica — balanced prima di tight — e ogni regola è verificata sulla produzione prima che la blocchi mai.