Vai al contenuto principale
Una policy del firewall è un elenco ordinato di regole. Questa pagina è il riferimento completo di ciò che una regola può esprimere — il linguaggio di matching, i verdetti e come il motore le valuta. Le regole sono create nel rule editor della console, che scrive oggetti di match JSON strutturati. Tutto ciò che segue descrive quel vocabolario così puoi leggere, ragionare e verificare una regola con precisione — sia che tu la costruisca nell’UI sia che tu la posti tramite l’API.

​
1. Anatomia di una regola

CampoTipoSignificato
priorityintLa più bassa gira per prima. Parità risolta per id della regola.
labelstringNome leggibile, mostrato negli eventi e nell’audit.
stageenumLa superficie — inbound / response / mcp / egress. Vuoto = tutte le superfici.
tool_name_globstringGlob sul nome del tool.
skill_name_globstringGlob opzionale sulla skill proprietaria. Messo in AND con il glob del tool; vuoto = qualsiasi skill.
verdictenumL’azione — vedi §7.
args_matchobjectPredicato sugli argomenti opzionale.
sanitizeobjectConfig di redazione, usata quando verdict = sanitize. Vedi §5.
egressobjectElenco allow/deny di host/CIDR, usato quando stage = egress. Vedi §6.
cap_cost_centsintTetto al costo dell’esecuzione, usato quando verdict = cap_cost.
sequenceobjectMatch multi-step ordinato, applicato reattivamente. Vedi §8.
notesstringRazionale dell’autore; ignorato dal motore.
Una regola corrisponde a una chiamata a tool quando tutte le sue condizioni dichiarate valgono: lo stage corrisponde (o è vuoto), il glob del tool corrisponde, il glob della skill corrisponde (o è vuoto), 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.

​
2. Glob sul nome del tool

Una grammatica deliberatamente piccola, case-sensitive — nessuna sorpresa da regex, tempo lineare, sicura sull’hot path del relay:
PatternCorrisponde a
"" o *Ogni tool.
foo.*Prefisso — foo.bar, foo.exec (non il nudo foo).
*.execSuffisso — shell.exec, db.exec (non il nudo exec).
*.shell.*Infisso — local.shell.exec (richiede ≥1 carattere per lato).
qualsiasi altra cosaCorrispondenza esatta di stringa (incluso foo.*.bar).
I tool sono per convenzione namespacizzati server.tool o category.action, quindi shell.* cattura un’intera famiglia e *.delete cattura un verbo tra i server.

​
3. Glob sul nome della skill

La stessa grammatica di glob, abbinata alla skill proprietaria della chiamata a tool (es. community.*, builtin.send). È messa in AND con tool_name_glob, quindi: 
tool_name_glob:  http.fetch
skill_name_glob: community.*
corrisponde a http.fetch solo quando è di proprietà di una skill community.* — fidati dello stesso tool da una skill integrata, mettilo sotto controllo da una della community. Un glob di skill vuoto corrisponde a qualsiasi proprietario. Come una chiamata a tool viene attribuita a una skill è trattato in Skill.

​
4. Clausole sugli argomenti

Il matching sul nome del tool risponde a quale tool; le clausole sugli argomenti rispondono a con quali argomenti — la differenza tra “blocca shell.exec” e “blocca shell.exec solo quando il comando è rm -rf.” args_match è un insieme di clausole, tutte messe in AND tra loro: 
{
  "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" }
  ]
}
Un args_match vuoto / assente è vacuamente vero — la regola corrisponde sul solo glob.

​
Operatori

OperatoreCorrisponde quando
eqUguaglianza scalare (i numeri confrontati numericamente; type mismatch → nessun match).
containsSottostringa (entrambi gli operandi devono essere stringhe).
regexUn pattern Go RE2 corrisponde al valore stringa (tempo lineare, nessuna backreference).
inIl valore è un elemento dell’array JSON dato.
cidr_matchL’IP stringa rientra nel CIDR dato.
gt / ltMaggiore-di / minore-di numerico (le stringhe non vengono convertite).

​
Sintassi dei path

Un piccolo sottoinsieme di JSONPath sull’oggetto degli argomenti del tool:
  • $.foo, $.foo.bar — accesso ai campi
  • $.foo[0], $.arr[1].k — indicizzazione di array
  • $ — l’intero oggetto degli argomenti
Nessun wildcard, filtro, slice o discesa ricorsiva.
Le clausole sugli argomenti fanno fail closed — la regola, non la richiesta. Se un path non si risolve, gli argomenti sono malformati o una regex/CIDR è invalida, la clausola valuta false e la regola semplicemente non scatta — la chiamata ricade sulla regola successiva o sul verdetto di default. Una clausola rotta non nega mai automaticamente e non manda mai in crash il relay. Scrivi la tua regola “cattura tutto ciò che è pericoloso” come un deny esplicito con il proprio glob anziché affidarti a una clausola che fallisce in un modo particolare.
La console valida le clausole in modo rigoroso al salvataggio (operatori sconosciuti, path errati, valori in non-array, regex non compilabili e CIDR invalidi vengono tutti rifiutati) così una clausola malformata non può essere persistita in primo luogo.

​
5. Sanitizer

Un verdetto sanitize redige le sottostringhe corrispondenti dagli argomenti del tool e inoltra la chiamata ripulita — utile per rimuovere segreti o PII che un agent ha messo in un argomento di tool senza bloccare l’intera azione. 
{ "presets": ["email", "ssn_us"], "custom": ["foo-\\d+"] }
I match dei preset vengono sostituiti con [redacted:<preset>]; i match della regex custom con [redacted:custom]. La libreria di preset integrata: aws_access_key, aws_secret_key, openai_key, anthropic_key, bearer_token, email, ssn_us, credit_card (con un controllo di Luhn). Una regola sanitize deve dichiarare almeno un preset o un pattern custom — un sanitizer vuoto viene rifiutato al salvataggio. Sulla superficie inbound non ci sono argomenti al momento della chiamata da redigere, quindi lì un verdetto sanitize escala a un block.

​
6. Elenchi di destinazioni egress

Una regola egress (stage egress) abbina su una destinazione in uscita — la superficie di SSRF ed esfiltrazione: 
{
  "deny":  ["169.254.169.254", "10.0.0.0/8"],
  "allow": ["api.openai.com"]
}
Le voci corrispondono come un CIDR, un IP letterale o un hostname case-insensitive; gli hostname vengono risolti best-effort e ri-controllati rispetto alle voci IP/CIDR. La polarità segue il verdetto: con un verdetto allow l’elenco allow definisce cosa è in scope e deny ne ritaglia le eccezioni; con un verdetto applicativo (deny) l’elenco deny definisce cosa è bloccato e allow ne ritaglia le eccezioni. 169.254.169.254 (l’endpoint dei metadati cloud) e i range RFC-1918 sono le cose canoniche da negare — il preset block_ssrf_egress e il livello di autonomia tight forniscono esattamente quello.

​
7. Verdetti

VerdettoEffettoNote
allowLascia passare, loggato.
auditConsente + registra per revisione.Il default_verdict usuale.
denyBlocca la chiamata.HTTP 400 su inbound; errore di tool su mcp.
sanitizeRedige gli argomenti, inoltra.Richiede un sanitizer; escala a deny su inbound.
pending_approvalMette in attesa per un umano.Richiede l’approval store configurato; rifiutato su response/egress.
cap_costNega oltre un tetto di spesa.Richiede un cap_cost_cents non negativo; inerte su response/egress.
In shadow mode ogni verdetto applicativo viene declassato a audit e la motivazione è prefissata con [shadow] would ….

​
8. Sequenze

Alcuni rischi sono visibili solo attraverso diverse chiamate — leggere 50 record CRM, poi esportare, poi colpire un host esterno. Una regola sequence abbina una catena ordinata anziché una singola chiamata: 
{
  "window_seconds": 600,
  "steps": [
    { "match": "crm.*",   "min_count": 3 },
    { "match": "*.export" },
    { "match": "*",       "egress": true }
  ]
}
Ogni step è un glob di tool con un min_count opzionale (default 1) e un egress: true opzionale (lo step deve essere una chiamata egress). Gli step devono verificarsi in ordine — l’interleaving con altre chiamate va bene — e l’intera catena deve completarsi entro window_seconds (0 = nessun limite).
Le sequenze sono applicate reattivamente da un matcher asincrono, non inline su ogni chiamata — una sequenza con uno step * corrisponderebbe altrimenti a ogni singola chiamata a tool. Illuminano il feed degli eventi e possono innescare un’azione successiva, ma non bloccano in tempo reale la singola chiamata che completa la catena.

​
9. Preset integrati

Parti da un preset anziché da una regola vuota. Sono creati lato server così la console e questi docs descrivono comportamenti identici:
PresetCosa fa
block_destructive_shellNega i comandi shell distruttivi (rm -rf, mkfs, dd, fork bomb, …) tramite un insieme di regole deny-by-glob.
block_ssrf_egressFa audit dell’egress verso l’endpoint dei metadati e i range RFC-1918.
block_secrets_in_argsOrientato alla detection — segnala credenziali che compaiono negli argomenti dei tool.
block_pii_in_tool_resultsOrientato alla detection — fa emergere PII nei risultati dei tool.
Applica un preset come seme, poi modificalo liberamente — un preset è un punto di partenza, non un lucchetto.

​
10. Valutazione, limiti e sicurezza

  • Vince il primo match. Le regole girano in ordine priority ASC, id ASC; la prima regola le cui condizioni valgono tutte decide il verdetto. Nessuna regola corrisponde → il default_verdict della policy.
  • Deterministico e privo di dipendenze. Il matching di glob e clausole sono pure operazioni su stringhe/JSON senza chiamate di rete, sicuro da eseguire su ogni chiamata a tool. Le regex sono RE2 — tempo lineare, nessun backtracking catastrofico.
  • Clausole fail-closed. Una clausola che non può essere valutata fa non scattare la sua regola anziché negare automaticamente (§4).
  • Validazione rigorosa al salvataggio. Gli accoppiamenti verdetto/stage, la non vacuità del sanitizer, la presenza di cap_cost_cents, la forma delle clausole e la risoluzione dei ref vengono tutti controllati al salvataggio — le regole invalide non possono essere persistite.
  • Sottoposto ad audit. Ogni create/update/delete di regola scrive una riga di audit dopo il commit della modifica; i blob delle regole e i segreti non vengono mai scritti nell’audit log.

​
Riferimento API

Le regole vivono sotto una policy e hanno scope a livello di workspace; le scritture richiedono Developer+.
Metodo & pathRuoloScopo
POST /api/workspace/firewall/rulesDeveloper+Crea una regola.
PUT /api/workspace/firewall/rulesDeveloper+Aggiorna una regola (id nel body).
DELETE /api/workspace/firewall/rules/:idDeveloper+Elimina una regola.
GET /api/workspace/firewall/presetsMemberElenca i preset integrati.
POST /api/workspace/firewall/testDeveloper+Esegue un dry-run di una policy (regole incluse) contro una chiamata a tool di esempio.
Per fare l’anteprima di una regola prima di dipenderne, usa Test — restituisce il verdetto, la regola corrispondente e la motivazione senza dispatchare nulla.

​
Vedi anche

Vuoi approfondire la sicurezza degli agent? Le guide Proteggi i tuoi agenti (Zero Trust) inseriscono questa feature in un workflow zero-trust.

Crea una policy di firewall

Scrivi una policy zero-trust passo dopo passo, poi mettila in shadow prima di applicarla.

Riferimento dello schema delle regole

Ogni campo di una regola — glob, predicati sugli argomenti, egress e tetti di costo.