Vai al contenuto principale
Un agent che è stato oggetto di prompt injection, mal configurato o a cui è stata semplicemente concessa troppa libertà può chiamare tool che non avrebbe mai dovuto toccare — o chiamare un tool legittimo con argomenti pericolosi: shell.exec con rm -rf /, un’API di pagamento con un importo di trasferimento eccessivo, un tool di database che punta alla replica di produzione. Questo è l’abuso dei tool da parte degli agent, ed è uno dei rischi più significativi nei sistemi agentici perché le chiamate a tool hanno effetti collaterali nel mondo reale che sono spesso irreversibili. L’Agent Firewall ha tre difese a strati. Puoi distribuirle indipendentemente o in combinazione.

​
1. Allowlisting: nega tutto ciò che non hai esplicitamente consentito

Il controllo più forte è una allowlist. Invece di cercare di enumerare ogni tool pericoloso, enumeri i tool di cui questo agent ha legittimamente bisogno — e neghi tutto il resto. Questo è il baseline zero-trust. Una policy con default_verdict: deny e regole allow esplicite per ogni tool approvato raggiunge questo obiettivo. Esempio: un agent che dovrebbe solo leggere da un CRM: 
[
  {
    "priority": 10,
    "label": "allow crm reads",
    "tool_name_glob": "crm.get*",
    "verdict": "allow"
  },
  {
    "priority": 20,
    "label": "allow crm search",
    "tool_name_glob": "crm.search",
    "verdict": "allow"
  },
  {
    "priority": 9999,
    "label": "deny everything else",
    "tool_name_glob": "*",
    "verdict": "deny"
  }
]
Qualsiasi chiamata a shell.exec, db.delete, payment.transfer — che sia emessa intenzionalmente o attivata da un’istruzione iniettata — colpisce il catch-all * e restituisce un errore HTTP 400 firewall_blocked. L’agent vede un errore di tool strutturato e non può ritentare (il block è marcato skip-retry), quindi non può aggirare il diniego in loop.
Imposta il default_verdict della tua policy su deny per l’applicazione completa della allowlist. Con il verdetto audit di default, le chiamate senza match sono consentite e loggata ma non bloccate — utile durante il rollout ma non un controllo di sicurezza di per sé.
I pattern glob ti permettono di consentire intere famiglie di tool con una sola regola. I pattern comuni:
PatternCosa copre
crm.*Tutti i tool nel namespace crm
*.readQualsiasi tool con verbo read su tutti i server
db.queryEsattamente questo singolo tool
*Tutto (usa per il tuo catch-all deny)
Il matching dei tool è first-match-wins in ordine di priorità crescente. Metti le tue regole allow specifiche a numeri di priorità bassi e il deny catch-all a uno alto.

​
2. Validazione degli argomenti: consenti il tool, blocca l’invocazione pericolosa

Una allowlist sui nomi dei tool è grossolana — blocca shell.exec interamente. A volte vuoi consentire un tool ma vincolare come può essere chiamato. Le clausole sugli argomenti ti permettono di corrispondere su campi specifici dentro gli argomenti della chiamata a tool, usando JSONPath e un set di operatori. Esempio: consenti shell.exec ma blocca rm -rf 
{
  "priority": 10,
  "label": "block destructive rm",
  "tool_name_glob": "shell.exec",
  "args_match": {
    "clauses": [
      {
        "path": "$.command",
        "op": "regex",
        "value": "rm\\s+-[^\\s]*r[^\\s]*f|mkfs|dd\\s+if=|:\\(\\)\\{.*\\}"
      }
    ]
  },
  "verdict": "deny"
}
Questa regola scatta solo quando shell.exec è chiamato e l’argomento $.command corrisponde alla regex dei comandi distruttivi. Una normale chiamata a shell.exec con un comando sicuro passa alla regola successiva (o al verdetto di default). Metti questa regola a un numero di priorità più basso di qualsiasi regola generale allow shell.exec così scatta per prima. Il set completo di operatori per gli argomenti:
OperatoreUsalo quando
eqMatch esatto su un valore scalare (stringa o numero)
containsMatch di sottostringa — es. $.query contains DROP TABLE
regexMatch di pattern RE2 — sicuro sull’hot path, nessun backtracking
inIl valore deve essere in un dato array — es. consenti solo ambienti specifici
cidr_matchIndirizzo IP in un blocco CIDR — utile per i controlli di destinazione egress
gt / ltConfronto numerico — es. $.amount gt 10000 per i limiti di pagamento
Tutte le clausole in un blocco args_match sono in AND. Se un path non esiste negli argomenti della chiamata, la clausola viene valutata false e la regola non scatta — la chiamata passa alla regola successiva o al default. Esempio di guardia ai pagamenti — nega qualsiasi chiamata a tool di pagamento con un importo superiore a una soglia: 
{
  "priority": 5,
  "label": "cap payment amount",
  "tool_name_glob": "payment.*",
  "args_match": {
    "clauses": [
      { "path": "$.amount_cents", "op": "gt", "value": 100000 }
    ]
  },
  "verdict": "deny"
}

​
3. Human-in-the-loop: trattieni le chiamate ad alto rischio per l’approvazione

Per i tool che sono genuinamente necessari ma ad alto rischio — attivare un deployment, approvare un rimborso, inviare un’email in bulk — puoi richiedere la firma di un essere umano prima che la chiamata proceda. Il verdetto pending_approval trattiene la chiamata e restituisce una risposta firewall_approval_pending all’agent: 
{
  "priority": 20,
  "label": "hold deployment calls for review",
  "tool_name_glob": "deploy.*",
  "verdict": "pending_approval"
}
L’agent (o il tuo framework) fa polling sull’id di approvazione. Un revisore approva o rifiuta dalla console o tramite un webhook callback. Se approvato, l’agent ri-invia la chiamata originale con il token di approvazione monouso e il gateway la lascia passare una sola volta. pending_approval è compatibile con le clausole sugli argomenti — puoi trattenere solo le invocazioni che corrispondono a una soglia, e lasciare passare quelle di routine: 
[
  {
    "priority": 10,
    "label": "hold large deploys",
    "tool_name_glob": "deploy.release",
    "args_match": {
      "clauses": [
        { "path": "$.environment", "op": "eq", "value": "production" }
      ]
    },
    "verdict": "pending_approval"
  },
  {
    "priority": 20,
    "label": "allow staging deploys",
    "tool_name_glob": "deploy.*",
    "verdict": "allow"
  }
]

​
4. Come appare una chiamata bloccata

Una chiamata negata sulla superficie inbound (tool pubblicizzato nella richiesta) restituisce HTTP 400 con codice di errore firewall_blocked. La risposta include metadata strutturati — il label della regola corrispondente, il codice di motivazione e i fattori di rischio — ed è marcata skip-retry così un loop non può martellare la stessa chiamata negata. Una chiamata bloccata sulla superficie response (il modello ha già emesso tool_calls) restituisce un errore di tool visibile al modello, dandogli la possibilità di reagire — scegliere un tool diverso, chiedere all’utente, o fermarsi — invece di andare in crash.

​
5. Ordinamento first-match-wins

L’ordine di priorità conta. Il motore percorre le regole in ordine di priorità crescente e si ferma al primo match. Un pattern comune:
PrioritàRegolaVerdetto
5shell.exec + regex distruttivadeny
10shell.* (generale)allow
20crm.*allow
9999* (catch-all)deny
La priorità 5 scatta prima della priorità 10 — così shell.exec con un comando distruttivo viene negato anche se c’è un allow generale per shell.*. Senza il deny a priorità bassa, la regola allow shell.* vincerebbe per prima.

​
6. Rollout sicuro con la shadow mode

Prima di portare una nuova policy all’applicazione, attiva la shadow mode. La policy valuta ogni chiamata a tool e logga il verdetto esattamente come farebbe in produzione, ma ogni verdetto applicativo (deny, pending_approval, sanitize) viene declassato a audit — nulla viene bloccato. La motivazione nel log degli eventi è prefissata con [shadow] would deny così puoi misurare l’impatto nelle viste Events e Runs. Una volta che hai confermato che la policy scatta su ciò che ti aspetti — e su nulla che non intendevi — disattiva la shadow mode. La chiamata successiva viene applicata.
Il livello di autonomia tight applica il preset block_destructive_shell automaticamente. Se hai bisogno di una postura rapida senza scrivere regole, applica tight dalla console e installa una policy di deny per le chiamate alla shell distruttiva in un unico passo. Poi puoi sovrapporre le tue regole di allowlist sopra. Vedi Livelli di autonomia.

​
7. Minacce correlate

L’abuso dei tool da parte degli agent raramente arriva isolato. Una chiamata a tool non autorizzata è spesso la conseguenza di un altro vettore di attacco:
  • Prompt injection — un attaccante incorpora istruzioni nel contenuto recuperato che dirottano l’agent verso tool che non avrebbe dovuto chiamare.
  • Eccessiva agenzia — all’agent è stato concesso più accesso ai tool di quanto il suo compito richieda, rendendo qualsiasi injection o mal configurazione immediatamente pericolosa.
  • Il modello di threat — come l’abuso dei tool si inserisce nella superficie d’attacco completa per i sistemi agentici.
L’Agent Firewall è il layer di applicazione; il principio del least privilege (allowlist dei tool ristrette, chiavi con scope) è la postura di design che lo rende efficace.

Riferimento regole del firewall

Il linguaggio di matching completo — glob dei tool, clausole sugli argomenti, tutti gli operatori, verdetti e API.

Panoramica del firewall

Policy, superfici, livelli di autonomia, approvazione HITL e osservabilità.