Vai al contenuto principale
Quando leggi un evento del firewall o un match di un guardrail, la riga ti dice cosa ha deciso il gateway — deny, sanitize, [EMAIL]. Questa pagina è la tabella di lookup per quelle parole: cosa significa ciascuna, cosa fa alla chiamata e dove andare per la meccanica completa. Tienila aperta mentre crei regole o fai triage del feed degli eventi. Due control plane producono due vocabolari. Il Firewall governa le azioni dei tool ed emette un verdetto. I Guardrails filtrano il testo di prompt e risposta ed emettono un’azione più, su un mask, un tag di mascheramento tipizzato. Non condividono mai una parola — un guardrail non dice mai deny, un firewall non dice mai mask.
Questo è un indice di riferimento, non una guida how-to. Per il caso d’uso dietro ogni controllo vedi Guardrails vs Firewall; per i corpi HTTP vedi Codici di errore di sicurezza.

​
1. Il glossario dei verdetti del firewall

Una regola del firewall (o il default_verdict della policy) risolve ogni chiamata a tool in esattamente uno di questi sei verdetti. Il motore percorre le regole in ordine di priorità, vince il primo match, e ricade sul default se nulla corrisponde.
La chiamata procede verso il tool. Comunque loggata come evento del firewall, quindi compare in Runs e nel feed degli eventi. È ciò che vuoi per i tool che un agent è esplicitamente autorizzato a usare.
Traffico identico ad allow, ma marcato come qualcosa che volevi osservare. È il default_verdict consigliato: osserva tutto, blocca nulla, finché le tue regole non sono messe a punto. Il livello di autonomia balanced fornisce il guardrail PII Shield come solo-flag (audit), così i PII sono registrati senza mettere in attesa la chiamata.
La chiamata non raggiunge mai il tool. Sulla superficie inbound questo restituisce HTTP 400 firewall_blocked; attraverso il gateway MCP torna come un errore di tool (firewall deny: <reason>) così il modello può reagire invece di andare in crash. Marcato skip-retry. Non costa token del modello.
Sostituisce le sottostringhe corrispondenti (segreti, PII) negli argomenti della chiamata a tool con un token [redacted:<preset>], poi inoltra la chiamata con gli argomenti ripuliti. Redige solo gli argomenti — mai il contenuto che un tool restituisce. Sulla superficie inbound, dove non ci sono ancora argomenti al momento della chiamata, sanitize escala a un deny.
La chiamata viene accodata per revisione e l’agent riceve una risposta held che porta un id di approvazione (HTTP 400 firewall_approval_pending). Un revisore la risolve nella console o tramite un callback webhook HMAC; l’agent fa polling sull’id e ri-invia una volta con un header di approvazione monouso. Vedi Approvazione umana.
Creato come una regola con un tetto in centesimi per regola. Si risolve in allow finché l’esecuzione dell’agent è sotto budget e in deny una volta che la spesa accumulata supera il tetto — quindi un evento mostra allow o deny, non la parola letterale cap_cost. Un interruttore di sicurezza per i loop incontrollati.
In shadow mode, deny / sanitize / pending_approval vengono tutti declassati ad audit e la motivazione è prefissata con [shadow] would …. L’evento registra il verdetto che sarebbe scattato, ma il traffico è invariato — questo è l’intero scopo di un rollout sicuro.

​
Verdetto di default

default_verdict accetta solo i tre verdetti non-interattivi:
ValoreSignificato quando nessuna regola corrisponde
allowConsenti silenziosamente le chiamate a tool non coperte.
auditConsenti ma registra — il default.
denyBlocca qualsiasi cosa nessuna regola consenta esplicitamente (postura default-deny).
Il livello di autonomia tight imposta default_verdict: deny; balanced e il default fornito usano audit.

​
2. Azioni dei guardrail

Una regola di guardrail fa scattare una di cinque azioni. Sono l’equivalente sul piano del testo dei verdetti — e una regola di guardrail non produce mai un verdetto del firewall.
AzioneCosa faQuota
blockRifiuta l’intera richiesta con HTTP 400 guardrail_blocked.Nessuna — i block in input scattano prima del metering; i block in output rimborsano.
maskRedige ogni match in un tag tipizzato (vedi §3) e inoltra il testo ripulito.Normale — la chiamata procede.
flagSolo log. Registra un match; non cambia nulla del traffico.Normale.
annotateNon bloccante. Attacca una nota leggibile dall’uomo alla richiesta (iniettata upstream come avviso di sicurezza) senza mascherare o bloccare il testo.Normale.
spotlightNon bloccante. Avvolge il testo (non attendibile) corrispondente in delimitatori e dice al modello di trattare la regione delimitata come dato, mai come istruzioni — la difesa “spotlighting” da prompt-injection.Normale.
Una richiesta di guardrail bloccata è marcata skip-retry — ri-eseguire lo stesso prompt contro un altro canale si limiterebbe a bloccarla di nuovo.
Usa flag per misurare una nuova regola contro il traffico reale prima di passarla a block o mask. Il feed dei match mostra cosa sarebbe stato intercettato con zero impatto sul traffico — la controparte guardrail della shadow mode del firewall.
Una singola regola pii può applicare azioni diverse a entità diverse con entity_actions — maschera email e telefoni, ma blocca su credit_card e ssn, da un’unica regola. Le chiavi devono essere un’entità abilitata sulla regola; i valori devono essere block / mask / flag / annotate.

​
3. Il glossario dei tag di mascheramento

Su un’azione mask, ogni entità corrispondente viene sostituita inline con un tag tipizzato — [<NOME_ENTITÀ_MAIUSCOLO>] — così il modello (fase di input) o il chiamante (fase di output) vede la forma del dato senza il valore. Il mascheramento gira su entrambe le fasi, incluse le risposte in streaming: uno scanner di stream token-aware maschera i match che attraversano i confini dei chunk prima che raggiungano il client.
EntitàTag
email[EMAIL]
phone[PHONE]
credit_card[CREDIT_CARD]
ssn[SSN]
ip[IP]
iban[IBAN]
mac_address[MAC_ADDRESS]
jwt[JWT]
aws_access_key[AWS_ACCESS_KEY]
api_key_openai[API_KEY_OPENAI]
bitcoin_address[BITCOIN_ADDRESS]
Tre identificatori regionali si aggiungono al set di base:
EntitàTagRegione
jp_mynumber[JP_MYNUMBER]Giappone
kr_rrn[KR_RRN]Corea del Sud
cn_resident_id[CN_RESIDENT_ID]Cina
Le entità personalizzate seguono la stessa convenzione. Un’entità personalizzata chiamata employee_id maschera a [EMPLOYEE_ID] a meno che tu non imposti una sostituzione mask_with esplicita. Fino a 25 entità personalizzate per regola, ciascuna una regex RE2 con un checksum luhn opzionale. Vedi Rilevamento PII.

​
4. Un esempio svolto

Una singola chiamata al tool db.query, letta dall’alto in basso, tocca entrambi i vocabolari: 
firewall verdict : sanitize        # secret stripped from the SQL argument
guardrail action : mask            # an email in the prompt redacted
masking tag      : [EMAIL]         # what the model actually receives
Il sanitize del firewall ha ripulito gli argomenti del tool; il mask del guardrail ha ripulito il testo del prompt; il tag [EMAIL] è ciò che il modello vede al posto dell’indirizzo. Stessa richiesta, tre layer diversi, tre parole da questo glossario.

​
5. Parole di postura che vedrai accanto ai verdetti

Queste non sono verdetti o azioni, ma decidono se un verdetto viene applicato del tutto — quindi compaiono nelle stesse viste di eventi e impostazioni.
ParolaPianoSignificato
Shadow modeFirewallFlag per-policy. Declassa ogni verdetto applicativo ad audit, prefissa la motivazione [shadow] would ….
Observe modeFirewallImpostazione del workspace. Quando nessuna policy si risolve, consente la chiamata ma la logga come un gap di copertura (Discovered tools).
EnforceFirewallShadow off + una policy collegata: i verdetti hanno effetto.
Fail-openGuardrailsDefault per le regole avanzate (llm_judge, grounding, external) — un timeout viene osservato, la richiesta continua. Passa a fail-closed per regola.
Log raw contentGuardrailsDisattivato di default. Quando è off, un match registra che una regola è scattata ma non la sottostringa corrispondente.
Per la distinzione deny-vs-audit-vs-shadow in profondità, vedi Modalità di applicazione.

​
6. Dove ogni parola è definita

SuperficieVocabolarioPagina di riferimento
Policy del firewallallow audit deny sanitize pending_approval cap_costFirewall
Matching delle regole del firewalltool_name_glob, args_match, egress, sequenceRegole del firewall
Regola del guardrailblock mask flag annotate spotlightGuardrails
PII del guardrailnomi delle entità + tag di mascheramentoGuardrails
MCP e skillrisk band delle skill, modalità quarantine / blockFirewall MCP, Firewall skills
Corpi di errore HTTPguardrail_blocked, firewall_blocked, firewall_approval_pendingCodici di errore
Ogni termine qui compare anche nel più ampio glossario dei concetti, che aggiunge termini di identità, scope e threat. Questa pagina è la fetta stretta e focalizzata sulle decisioni — solo verdetti, azioni e tag di mascheramento.

​
7. Letture correlate

Perché è stato bloccato?

Risali da una singola chiamata negata alla regola e al verdetto esatti che l’hanno fermata.

Modalità di applicazione

Come audit, shadow, observe ed enforce si relazionano — e come fare rollout in sicurezza.

Guardrails vs Firewall

Quale piano possiede quale decisione, e perché una richiesta può attraversare entrambi.

Chiamate a tool pericolose

La minaccia per cui esistono i verdetti deny e sanitize.