Vai al contenuto principale
Nominare un tool e negarlo è contundente: uccide il tool per ogni chiamata. Il più delle volte il tool va bene e una sola forma di chiamata è il problema — shell.exec va bene finché il comando non è rm -rf, db.query va bene finché non colpisce prod. Quella distinzione è ciò che una clausola sugli argomenti esprime: un predicato jsonpath sugli argomenti del tool che fa matching sui valori che un agent passa, così il verdetto scatta solo sulla chiamata pericolosa e lascia il resto in pace. Questa pagina è un ricettario — una manciata di ricette args_match_json copia-incolla per i casi che ricorrono più spesso. Per la grammatica completa delle clausole, la tabella degli operatori e la semantica fail-closed, vedi Valida gli argomenti e il riferimento Schema delle regole.

​
1. Come funziona una clausola jsonpath sugli argomenti del tool

L’args_match_json di una regola è una stringa codificata in JSON che porta un insieme di clausole, tutte in AND. Il valore decodificato è un oggetto, {"clauses": [ … ]}, dove ogni clausola è una tripla { path, op, value }:
  • path — un piccolo sottoinsieme di JSONPath sull’oggetto degli argomenti del tool: $.command, $.foo.bar, $.items[0], o $ per l’intero oggetto. Niente wildcard, filtri, slice o discesa ricorsiva.
  • op — uno di un insieme chiuso: eq, contains, regex, in, cidr_match, gt, lt.
  • value — il letterale con cui confrontare (una stringa, un numero, un bool, o — per in — un array JSON).
Una clausola è in AND con il tool_name_glob della regola: la regola scatta solo quando il nome del tool corrisponde e ogni clausola vale. Ometti del tutto args_match_json (o lascialo un "{}" vuoto) e la regola fa matching sul glob da solo.
Le clausole fanno fail closed — la regola, non la richiesta. Se un path non si risolve, gli argomenti sono malformati, o un valore è del tipo sbagliato, la clausola valuta a false e la regola semplicemente non scatta — la chiamata ricade sulla regola successiva o sul verdetto di default. Una clausola rotta non auto-nega mai. Scrivi il tuo backstop netto come un semplice deny su glob, non come una clausola su cui fai affidamento perché fallisca in un certo modo.

​
2. Ricetta: blocca un comando distruttivo

Il caso canonico. Consenti shell.exec in generale, negalo solo quando il comando appare distruttivo. Una clausola regex su $.command lo fa: 
{
  "label": "block destructive shell commands",
  "tool_name_glob": "*.exec",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf|mkfs|dd if=\"}]}"
}
Le regex sono Go RE2 — tempo lineare, niente backreference, niente backtracking catastrofico — quindi è sicuro eseguirle su ogni chiamata a tool. Un $.command non-stringa (o mancante) non corrisponde mai, così una chiamata malformata ricade anziché venire bloccata erroneamente.
Preferisci contains a regex quando fai matching su una sottostringa fissa — è più semplice da leggere e non può essere fatto inciampare da un metacarattere senza escape. Ricorri a regex solo quando ti serve davvero un’alternanza o degli ancoraggi.

​
3. Ricetta: nega un tool contro un ambiente nominato

Lascia girare db.query, ma solo contro connessioni sicure — negalo quando il target è prod o una replica. L’operatore in fa matching del valore risolto contro qualsiasi elemento di un array JSON: 
{
  "label": "no agent queries against prod",
  "tool_name_glob": "db.query",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.connection\",\"op\":\"in\",\"value\":[\"prod\",\"replica\"]}]}"
}
Il valore di in deve essere un array JSON — un non-array viene rifiutato quando salvi la regola. Gli elementi si confrontano con uguaglianza scalare, quindi numeri e stringhe corrispondono ciascuno al proprio tipo.

​
4. Ricetta: nega una destinazione su IP privato o metadata

Quando un tool prende un IP target come argomento, cidr_match verifica se cade dentro un CIDR — la forma SSRF di “un agent che recupera 10.x o l’indirizzo cloud metadata”: 
{
  "label": "deny tool calls aimed at RFC-1918",
  "tool_name_glob": "*",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.target_ip\",\"op\":\"cidr_match\",\"value\":\"10.0.0.0/8\"}]}"
}
Il valore dell’argomento deve fare parsing come un IP letterale che sta dentro il CIDR; un hostname o una stringa non-IP non corrisponde mai.
cidr_match ispeziona solo un valore già presente negli argomenti del tool. Per governare la destinazione che un tool raggiunge effettivamente al livello di rete — elenchi di allow e deny per host/CIDR — usa invece una regola egress dedicata sulla superficie egress. Le due sono complementari: ispezione degli argomenti all’andata, controllo dell’egress al ritorno.

​
5. Ricetta: limita un argomento numerico

gt e lt confrontano numeri. Usali per rifiutare una dimensione di batch assurda, un limite sovradimensionato o qualsiasi conteggio incontrollato — qui, nega un delete bulk che mira a più di 100 righe: 
{
  "label": "block large bulk deletes",
  "tool_name_glob": "*.bulk_delete",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.count\",\"op\":\"gt\",\"value\":100}]}"
}
Entrambi i lati devono essere numeri — una stringa che sembra numerica come "500" è un mismatch di tipo e non corrisponde, quindi la regola non scatta su un argomento tipizzato come stringa. Mantieni l’argomento numerico, o normalizzalo prima che il tool lo veda.

​
6. Ricetta: combina le clausole (AND)

Tutte le clausole in una regola sono in AND, quindi puoi restringere un verdetto a una chiamata molto specifica — per esempio, nega shell.exec solo quando è un comando distruttivo e è puntato verso un host prod: 
{
  "label": "destructive shell on a prod host",
  "tool_name_glob": "*.exec",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf|drop table\"},{\"path\":\"$.host\",\"op\":\"in\",\"value\":[\"db-prod-1\",\"db-prod-2\"]}]}"
}
Ti serve un OR invece? Non c’è alcun OR dentro un singolo args_match_json — scrivi due regole (o due glob) a priorità diverse. Il motore percorre le regole in ordine di priorità e vince il primo match, quindi metti le regole strette per prime. Vedi Priorità delle regole.

​
7. Scegli il verdetto per la forma corrisposta

Una clausola decide quali chiamate corrispondono; il verdict della regola decide cosa succede. deny è il default del ricettario, ma la stessa clausola può portare un verdetto più morbido:
Quando l’argomento corrisposto porta un segreto o una PII anziché un’istruzione pericolosa, sanitize redige le sottostringhe corrispondenti dagli argomenti del tool e inoltra la chiamata ripulita. Redige solo gli argomenti — mai il contenuto che un tool restituisce. Vedi Sanitizza le risposte.
Metti in attesa esattamente la forma rischiosa per revisione invece di bloccarla del tutto: un revisore approva o rifiuta fuori banda, e l’agent ri-invia la chiamata approvata una volta. Vedi Approvazioni.
Imposta il verdetto su audit per registrare la chiamata corrisposta senza bloccare mentre metti a punto la clausola. Abbina con la shadow mode per misurare un deny contro il traffico live prima che cambi qualcosa.

​
8. Testa la clausola prima di farci affidamento

La scheda Test della console esegue un dry-run di una policy contro una chiamata a tool di esempio e restituisce il verdetto, la regola corrispondente e la motivazione — nulla viene dispatchato, nulla viene persistito. Incolla un oggetto di argomenti realistico e conferma che la clausola scatti sulle chiamate che intendi e solo su quelle, dato che una clausola che non può risolvere un valore semplicemente non scatta. Vedi Testa le regole.
Le clausole sono validate rigorosamente al salvataggio — operatori sconosciuti, path errati, un valore in non-array, una regex non compilabile e CIDR invalidi vengono tutti rifiutati, così una clausola malformata non può essere persistita in primo luogo.

​
9. Chi può scrivere le clausole sugli argomenti

Tutto questo gira nella console sotto la tua sessione (/api/workspace/firewall/*):
AzioneRuolo
Leggere policy, preset, discovered toolsMember
Creare / modificare / eliminare regoleDeveloper+
Sandbox Test (dry-run di una policy)Developer+
Leggere eventi e aggregazioni delle esecuzioniDeveloper+
Scrivere o modificare una clausola sugli argomenti è una scrittura Developer+. La sandbox Test è anch’essa Developer+ — può fare anteprima contro una policy in bozza e la sua trace dei verdetti espone nomi di policy ed etichette di regole, quindi sta sul lato di scrittura della linea, non su quello di lettura.

​
Correlati

Valida gli argomenti

Il caso d’uso del match sugli argomenti per intero.

Blocca i tool

Nega un intero tool per nome — nessuna clausola necessaria.

Controllo dell'egress

Governa le destinazioni host / IP / CIDR in uscita.

Schema delle regole

Ogni campo che una regola può portare.

Priorità delle regole

Vince il primo match — ordina lo stretto prima dell’ampio.

Chiamate a tool pericolose

La minaccia che queste ricette affrontano.