Vai al contenuto principale
Una policy del firewall è un elenco ordinato di regole, e una regola è solo un piccolo sacchetto di campi: a quali chiamate a tool corrisponde, su quale superficie, e cosa farne. Quando hai bisogno di leggere una regola che qualcun altro ha scritto — o ragionare con precisione su una che stai costruendo — vuoi l’elenco dei campi in un unico posto. È questa pagina. Scrivi le regole nell’editor delle regole della console (le scritture richiedono Developer+); l’editor scrive i campi strutturati qui sotto. Questa pagina è la mappa a livello di campo; il motore di matching approfondito vive in Regole del Firewall.

​
1. Lo schema delle regole del firewall in breve

Ogni regola porta gli stessi campi. Solo verdict è sempre obbligatorio — tutto il resto restringe ciò a cui la regola corrisponde o configura il verdetto scelto, e un matcher assente è vacuamente vero.
CampoScopo
priorityOrdine di valutazione — il più basso gira per primo.
verdictL’azione quando la regola corrisponde (obbligatorio).
stageLa superficie a cui dare scope; vuoto = tutte.
tool_name_globGlob sul nome del tool.
args_match_jsonPredicato sugli argomenti JSONPath, come stringa codificata in JSON.
egress_jsonElenco allow-deny per host / CIDR (regole egress), come stringa codificata in JSON.
sanitize_jsonConfig di redazione (quando verdict = sanitize), come stringa codificata in JSON.
cap_cost_centsTetto di costo dell’esecuzione in centesimi USD (quando verdict = cap_cost).
sequence_jsonPredicato di catena multi-step ordinata (regole di sequenza), come stringa codificata in JSON.
label / notesNome umano e motivazione — mostrati negli eventi, ignorati dal motore.
Una regola scatta quando tutti i suoi matcher dichiarati valgono contemporaneamente — lo stage corrisponde (o è vuoto), il glob del tool corrisponde, le clausole sugli argomenti corrispondono (o sono assenti), e lo scope di egress corrisponde (solo regole egress). Il motore percorre le regole in ordine di priorità e vince il primo match; se nulla corrisponde, si applica il default_verdict della policy.

​
2. priority — ordine di valutazione

Un ordinale intero. Il più basso gira per primo; due regole con la stessa priorità risolvono la parità per id della regola (ordine di inserimento). Metti i tuoi carve-out specifici sopra i tuoi catch-all ampi — un allow per un tool fidato a priorità 10 batte un deny * a priorità 100.
Lascia spazi (10, 20, 30) così puoi inserire una nuova regola tra due esistenti più avanti senza rinumerare l’intera policy. Vedi Priorità delle regole per la strategia di ordinamento.

​
3. verdict — l’azione

L’unico campo obbligatorio. Quando una regola corrisponde, il suo verdetto decide cosa succede alla chiamata:
VerdettoEffetto
allowLascia passare la chiamata, loggata.
auditConsenti e registra per revisione — il default_verdict abituale.
denyBlocca la chiamata.
sanitizeRedige le sottostringhe corrispondenti dagli argomenti del tool, poi inoltra.
pending_approvalMette in attesa la chiamata per un revisore umano.
cap_costNega una volta che la spesa accumulata di un’esecuzione dell’agent supera un tetto.
Un deny restituisce HTTP 400 firewall_blocked sulla superficie inbound, o un errore di tool sulla superficie mcp. Una chiamata in attesa restituisce HTTP 400 firewall_approval_pending con un id su cui l’agent fa polling. In shadow mode ogni verdetto applicativo viene declassato a audit e la motivazione è prefissata [shadow] would …. Vedi Verdetti per la tabella completa e le forme di block.

​
4. stage — la superficie di applicazione

Fissa la regola a una delle superfici del firewall. Lascialo vuoto e la regola si applica a tutte le superfici:
I tool che un agent pubblicizza al modello sulla richiesta. Blocca un tool pericoloso prima che il modello possa anche solo sceglierlo.
I tool_calls che il modello emette nella sua risposta.
Un tools/call instradato attraverso il gateway MCP del Firewall.
Un host / IP / CIDR in uscita che un tool raggiunge — la superficie di SSRF ed esfiltrazione di dati.
Alcuni abbinamenti verdetto + stage vengono rifiutati al salvataggio perché il verdetto non può scattare lì: cap_cost è un tetto di costo dell’esecuzione pre-dispatch, inerte su response ed egress; pending_approval mette in attesa solo su inbound, quindi un pin esplicito response/egress viene rifiutato. L’editor nasconde queste combinazioni; l’API le rifiuta. Vedi Stage.

​
5. tool_name_glob — quale tool

Un piccolo glob case-sensitive sul nome del tool — shell.* per un’intera famiglia, *.delete per un verbo attraverso i server, http_fetch per un tool esatto. Vuoto o * corrisponde a ogni tool. Un glob sul nome della skill opzionale (stessa grammatica) mette in AND una seconda condizione sulla skill proprietaria, così puoi fidarti di un tool da una skill integrata e governarlo da una della community. La grammatica completa — prefisso, suffisso, infisso, esatto e i casi limite che fanno inciampare la gente — è il proprio riferimento: Sintassi dei pattern glob.

​
6. args_match_json — con quali argomenti

Il glob risponde a quale tool; args_match_json risponde a con quali argomenti — la differenza tra “blocca shell.exec” e “blocca shell.exec solo quando il comando è rm -rf.” Il suo valore è una stringa codificata in JSON che porta un insieme di clausole JSONPath, tutte in AND. Decodificato, l’oggetto delle clausole appare così: 
{
  "clauses": [
    { "path": "$.command",    "op": "regex",      "value": "rm -rf|drop table" },
    { "path": "$.connection", "op": "in",         "value": ["prod", "replica"] },
    { "path": "$.ip",         "op": "cidr_match", "value": "10.0.0.0/8" }
  ]
}
In un corpo di richiesta il campo porta quell’oggetto come una stringa con escape, es. "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf\"}]}". Gli operatori sono eq, contains, regex, in, cidr_match, gt e lt. Un args_match_json assente è vacuamente vero — la regola corrisponde sul glob da solo. Il linguaggio completo dei predicati, la sintassi del path e il comportamento fail-closed di una clausola rotta sono in Valida gli argomenti e nel ricettario degli argomenti.

​
7. egress_json — quali destinazioni

Usato sulla superficie egress: una stringa codificata in JSON che contiene un elenco di allow-e-deny per host / CIDR confrontato con una destinazione in uscita che un tool raggiunge. Decodificato, l’oggetto appare così: 
{
  "deny":  ["169.254.169.254", "10.0.0.0/8"],
  "allow": ["api.openai.com"]
}
Le voci fanno match come un CIDR, un IP letterale o un hostname case-insensitive. La polarità segue il verdetto — con un verdetto applicativo l’elenco deny definisce ciò che viene bloccato e allow ne ricava eccezioni.
Il template del firewall Baseline include una regola di deny egress con una denylist SSRF / cloud-metadata già pronta (l’IP metadata 169.254.169.254, i range RFC-1918, loopback, link-local e metadata.google.internal), così non devi scriverli a mano. Aggiungi le tue destinazioni sopra per tutto il resto che vuoi governare. Vedi Controllo dell’egress per la ricetta completa e Esfiltrazione di dati per perché conta.

​
8. sanitize_json — redige gli argomenti

Usato quando verdict = sanitize: una stringa codificata in JSON che nomina quali preset / regex custom redigono le sottostringhe corrispondenti dagli argomenti del tool prima che la chiamata ripulita venga inoltrata — utile per rimuovere un segreto o un valore PII che un agent ha lasciato in un argomento senza bloccare l’intera azione. Decodificato, l’oggetto appare così: 
{ "presets": ["email", "ssn_us"], "custom": ["foo-\\d+"] }
Sanitize redige solo gli argomenti — mai il contenuto che un tool restituisce. Una regola sanitize deve nominare almeno un preset o pattern custom (un sanitizer vuoto viene rifiutato). Sulla superficie inbound non ci sono argomenti al momento della chiamata da redigere, quindi un verdetto sanitize lì escala a un deny.
Vedi Sanitizza le risposte per la libreria di preset e le forme di redazione.

​
9. cap_cost_cents — un tetto di spesa

Usato quando verdict = cap_cost: un tetto di costo dell’esecuzione per regola, un intero in centesimi USD. Quando la regola corrisponde, la chiamata viene negata una volta che la spesa accumulata dell’esecuzione dell’agent supera il tetto — un interruttore di sicurezza per un loop incontrollato, che si risolve in allow o deny negli eventi. Il tetto deve essere esplicito e non negativo, e la regola non può essere fissata a response o egress (dove il verdetto è inerte). Comportamento completo in Tetto di costo.

​
10. Una regola completa

Mettendo i campi insieme — nega shell.exec, ma solo quando il comando appare distruttivo, con scope sulle chiamate a tool emesse dal modello: 
{
  "priority": 10,
  "label": "block destructive shell",
  "stage": "response",
  "tool_name_glob": "shell.exec",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf|mkfs|:\\\\(\\\\)\\\\{\"}]}",
  "verdict": "deny",
  "notes": "fork bombs and recursive deletes only — plain shell.exec audits"
}
Lo stage corrisponde alla superficie response, il glob sceglie shell.exec, la singola clausola restringe a un comando distruttivo, e il verdetto nega. Qualsiasi shell.exec il cui comando non corrisponde alla regex ricade sulla regola successiva o sul default della policy. Collega una chiave alla policy (firewall_policy_id sulla chiave) ed è live sulla chiamata successiva — nessun redeploy.
Conferma che una regola scatti esattamente su ciò che ti aspetti prima di farci affidamento: Testa le regole esegue un dry-run di una policy contro una chiamata a tool di esempio e restituisce il verdetto, la regola corrispondente e la motivazione senza dispatchare nulla.

​
11. Come si combinano i campi

Un verdict. Tutto il resto è opzionale: uno stage vuoto corrisponde a tutte le superfici, un tool_name_glob vuoto (o *) corrisponde a ogni tool, e un args_match_json assente corrisponde a qualsiasi argomento. Un nudo { "verdict": "audit" } è un catch-all valido.
Sono in AND. Una regola scatta solo quando il suo stage, glob del tool, glob della skill, clausole sugli argomenti e scope di egress tutti valgono. Per esprimere un OR, scrivi regole separate.
sanitize_json è letto solo per il verdetto sanitize; cap_cost_cents solo per cap_cost; egress_json solo sulla superficie egress. La console valida questi abbinamenti al salvataggio, così una regola che mostra un comportamento ma non può mai applicarlo non può essere persistita.
Vince la priority più bassa (parità risolta per id della regola) — vince il primo match, e la valutazione si ferma lì. Vedi Priorità delle regole.

​
Correlati

Crea una policy

Crea la tua prima policy e collega una chiave.

Sintassi glob

La grammatica completa dei glob sul nome del tool.

Verdetti

Ogni verdetto e com’è fatto un block.

Valida gli argomenti

Le clausole sugli argomenti JSONPath in profondità.

Gestisci le policy

Modifica, versiona e fai revert delle policy.

Regole del Firewall

Il riferimento completo del motore di matching.
Nuovo al piano delle azioni? Parti dalla Panoramica del Firewall, o vedi come si abbina al filtraggio del testo in Guardrails vs Firewall.