Vai al contenuto principale
Una regola del firewall corrisponde a una chiamata a tool su due assi: quale tool (un tool_name_glob) e quali argomenti (clausole args_match sui campi JSONPath). Questa pagina è la grammatica precisa per entrambi — cosa corrisponde un pattern, cosa non corrisponde e come ogni operatore coercizza i tipi — così una regola che crei nella console si comporta esattamente come la leggi qui. Il caso d’uso di punta: trasformare uno smussato “blocca shell.exec” in un chirurgico “blocca shell.exec solo quando il comando assomiglia a rm -rf”. Il glob sceglie la famiglia di tool; gli operatori sugli argomenti scelgono la chiamata pericolosa al suo interno.
Questo è il riferimento di sintassi. Per dove vivono queste clausole su una regola, l’ordinamento delle regole e i verdetti, vedi il riferimento approfondito Regole del firewall. Per i campi della regola in sé, vedi la panoramica Firewall.

​
1. Dove si applica questa sintassi

Entrambe le forme sono create su una regola del firewall, nella console sotto /console/firewall (le scritture richiedono Developer+). Non chiami mai il matcher direttamente — il gateway lo valuta su ogni chiamata a tool contro la policy risolta. Una regola corrisponde quando la sua superficie, il suo tool_name_glob, il suo glob opzionale sulla skill e le sue clausole args_match tutti corrispondono; vince il primo match.
Una regola con nessuna clausola args_match corrisponde sul glob del nome del tool da solo. Aggiungi clausole sugli argomenti solo quando il nome del tool non è abbastanza specifico.

​
2. Grammatica dei glob sul nome del tool

Il tool_name_glob è una grammatica deliberatamente piccola e prevedibile — non una regex completa. I pattern sono confrontati in modo case-sensitive (i nomi dei tool MCP sono convenzionalmente in minuscolo-con-punti, quindi un case-fold ti sorprenderebbe quando copi un nome dalla tab Discovered tools).
Un pattern vuoto o un nudo * corrisponde a tutti i tool. Usalo su una regola catch-all, o affidati invece al default_verdict della policy.
shell.* corrisponde a shell.exec, shell.read, shell.write. Non corrisponde al nudo shell (il punto è richiesto — un glob di prefisso copre solo i figli con namespace).
*.exec corrisponde al shell.exec con namespace e al nudo exec senza namespace (le function call native dei provider e gli MCP server senza namespace espongono i tool sotto il verbo nudo, quindi una regola di suffisso copre entrambe le forme). Il suffisso resta ancorato a un punto o all’inizio della stringa, quindi *.exec non corrisponde a shell.execute.
*.shell.* corrisponde a qualsiasi forma <server>.shell.<verb> — local.shell.exec, byo.shell.run. Richiede almeno un carattere su ciascun lato dell’infisso, quindi *.shell.* non corrisponde al nudo shell o a .shell. da solo. Solo la forma simmetrica *.X.* è trattata come infisso; un pattern misto come foo.*.bar ricade sul match esatto.
Qualsiasi pattern che non sia una delle quattro forme wildcard qui sopra (incluso un nome di tool letterale, o un combo malformato come foo.*.bar) è confrontato come una stringa esatta, case-sensitive.
Non c’è il wildcard a singolo carattere ?, non ci sono classi di caratteri e non c’è un * a metà token (es. sh*l.exec). Un pattern che non sia una delle quattro forme supportate è confrontato letteralmente — sh*l.exec corrisponde solo a un tool chiamato letteralmente sh*l.exec. Crea con le forme qui sopra, non con la memoria muscolare della regex.

​
3. Clausole JSONPath sugli argomenti

args_match è un insieme di clausole, ciascuna una tripla {path, op, value}. Il path è un JSONPath nell’oggetto argomenti della chiamata a tool; op è uno di sette operatori; value è ciò con cui confrontare. Tutte le clausole in una regola sono in AND tra loro — ogni clausola deve corrispondere perché la regola scatti. 
{
  "clauses": [
    {"path": "$.command", "op": "regex", "value": "rm -rf|drop table"},
    {"path": "$.connection", "op": "in", "value": ["prod", "replica"]}
  ]
}

​
Sottoinsieme JSONPath supportato

FormaCorrisponde
$.fooUna chiave di primo livello.
$.foo.barUna chiave annidata.
$.foo[0]Un elemento di array per indice.
$.arr[1].kIndice poi chiave (combinazioni delle precedenti).
Questo è l’intero sottoinsieme. Non ci sono wildcard ($.*), filtri ($.foo[?(...)]), slice ($.foo[0:2]) o discesa ricorsiva ($..foo).
Fail-closed sul path. Se il path di una clausola si risolve in nulla — la chiave manca, gli argomenti non sono JSON valido, o il valore è del tipo sbagliato per l’operatore — quella clausola valuta a false, la regola non scatta, e la valutazione ricade sulla regola successiva o sul default della policy. Un argomento malformato non auto-nega mai e non fa mai crashare il motore.

​
4. Operatori sugli argomenti

Sette operatori, un set chiuso. Il validatore della console e il motore live condividono esattamente lo stesso vocabolario, quindi una clausola che si salva è una clausola che gira.
OperatoreConfrontaRegole di tipo
eqUguaglianza esatta.Tipizzato: string↔string, bool↔bool, o number↔number. Tipi misti non corrispondono mai.
containsContenimento di sottostringa.Entrambi i lati devono essere stringhe; qualsiasi altra cosa è un non-match. Un valore vuoto corrisponde a qualsiasi stringa.
regexUn pattern RE2 (tempo lineare, no backreference) contro una stringa.Valore e arg risolto devono essere entrambi stringhe. Un pattern non valido disabilita la clausola (non corrisponde mai).
inAppartenenza — il valore è uguale a qualsiasi elemento di una lista.Il valore deve essere un array JSON; ogni elemento confronta con semantica eq.
cidr_matchIl valore risolto è un IP dentro la rete data.Il valore è una stringa CIDR (IPv4 o IPv6, es. 10.0.0.0/8, fd00::/8); l’arg deve parsare come IP.
gtMaggiore-di, numerico.Entrambi i lati devono coercizzare a un numero. Una stringa che sembra numerica non è coercizzata — è un mismatch di tipo (non-match).
ltMinore-di, numerico.Stessa regola solo-numerica di gt.
gt e lt sono strettamente numerici. Se un tool invia {"max_rows": "10000"} (una stringa), una clausola gt 5000 non scatta — la stringa non è mai coercizzata. Confronta numeri con numeri; usa regex o contains per valori in forma di stringa.

​
5. Un esempio svolto

Blocca un export di database distruttivo, ma solo quando colpisce una connessione di produzione su un host di rete privata: 
{
  "tool_name_glob": "db.*",
  "args_match": {
    "clauses": [
      {"path": "$.statement", "op": "regex", "value": "(?i)drop|truncate|delete from"},
      {"path": "$.connection.name", "op": "in", "value": ["prod", "prod-replica"]},
      {"path": "$.connection.host_ip", "op": "cidr_match", "value": "10.0.0.0/8"}
    ]
  }
}
Leggila dall’alto in basso: il glob db.* restringe la regola alla famiglia dei tool di database; le tre clausole in AND insieme così il verdetto (un deny, diciamo) scatta solo quando lo statement è distruttivo e la connessione è uno di due target prod nominati e il suo host cade nel range privato 10.0.0.0/8. Una db.query contro una connessione dev su un IP pubblico scivola oltre questa regola intatta.
Prova la clausola prima di fidartene: la tab Test su una policy fa un dry-run di una chiamata a tool di esempio e mostra la regola corrispondente e il verdetto, senza persistere nulla e senza dispatchare nulla. Vedi Osservabilità del firewall.

​
6. Regole di egress (host / CIDR)

L’operatore cidr_match qui sopra corrisponde a un IP che un tool riporta nei suoi argomenti. Questo è diverso da una regola sulla superficie egress, che valuta la destinazione in uscita che un tool effettivamente raggiunge con una allow o deny list di host/CIDR — la difesa principale da SSRF ed esfiltrazione di dati. Le regole di egress usano la stessa notazione CIDR ma vivono sulla superficie egress; vedi Regole del firewall per il formato dell’elenco di egress.
Nessun preset fornisce regole di egress CIDR per te — il livello di autonomia tight nega i comuni nomi di tool in forma di fetch (http_fetch, fetch_url, web_search, request), non i range di rete. Crea la tua regola di deny host/CIDR quando hai bisogno di fissare l’egress a destinazioni specifiche.

​
7. Riferimento rapido

Forme di glob

* tutti · foo.* prefisso · *.exec suffisso (+ verbo nudo) · *.X.* infisso · qualsiasi altra cosa esatto. Case-sensitive.

JSONPath

$.foo · $.foo.bar · $.foo[0] · $.arr[1].k. No wildcard, filtri, slice o discesa ricorsiva.

Operatori su stringhe

eq (tipizzato) · contains (sottostringa) · regex (RE2) · in (appartenenza a lista).

Operatori numerici e di rete

gt / lt (solo numerici, no coercizione di stringhe) · cidr_match (IPv4/IPv6 nel range).

​
Correlati

Regole del firewall

Il modello completo delle regole — superfici, ordinamento, sanitizer, sequenze ed elenchi di egress.

Chiamate a tool pericolose

La minaccia da cui queste clausole difendono, e come restringere una regola ad essa.

Glossario dei verdetti

Cosa fanno allow, audit, deny, sanitize e gli altri una volta che una regola corrisponde.

Perché è stato bloccato?

Risali da un block specifico alla regola e alla clausola che sono scattate.