Vai al contenuto principale
Il modo più rapido per impedire a un agent di fare qualcosa di pericoloso è nominare il tool e negarlo. Un verdetto deny su un glob del nome del tool è il primitivo della deny-list dell’agent firewall: una regola, un glob, verdetto deny, collegato a una chiave — e da quel momento il gateway rifiuta quel tool su ogni chiamata, senza alcuna modifica al codice del tuo agent. Questa pagina copre il caso d’uso della deny-list e l’unica decisione che impone: su quale superficie blocchi — i tool che pubblicizzi (inbound) o le chiamate a tool che il modello emette (response). Per il vocabolario di matching completo e la semantica dei verdetti, vedi Schema delle regole e Verdetti.

​
1. Blocca una chiamata a tool che un agent AI fa

Una regola deny-list è la cosa più semplice che una policy del firewall può esprimere: fai matching su un tool per nome, restituisci deny. Usala quando un tool non dovrebbe mai scattare per una data chiave — shell.exec, *.delete, un plugin della community di cui non ti fidi — indipendentemente dagli argomenti. Nella console del tuo workspace, apri una policy (o creane una) e aggiungi una regola: 
{
  "label": "block destructive shell",
  "tool_name_glob": "*.exec",
  "verdict": "deny"
}
Il tool_name_glob è un glob piccolo e case-sensitive — shell.* cattura un’intera famiglia, *.delete cattura un verbo attraverso i server, * cattura tutto. Non serve alcuna clausola sugli argomenti: un glob nudo + deny blocca il tool incondizionatamente. Aggiungi una clausola sugli argomenti solo quando vuoi consentire il tool in generale ma negare una sola forma di chiamata.
Il motore percorre le regole di una policy in ordine di priorità e vince il primo match. Metti le eccezioni di allow strette a un numero di priority più basso (girano per prime) e il tuo deny ampio sotto di esse — es. consenti shell.exec da una skill builtin.* fidata, negalo ovunque altro. Vedi Priorità delle regole.

​
2. Inbound vs response: scegli la superficie

Un deny può atterrare su due punti diversi del ciclo di vita della richiesta, e la differenza conta. Fissa la regola con il campo stage, o lascialo vuoto per coprire entrambi.

inbound

I tool che il tuo agent pubblicizza al modello sulla richiesta (le definizioni dei tool). Un deny qui rimuove il tool prima che il modello possa anche solo sceglierlo — il modello non lo vede mai come opzione.

response

I tool_calls che il modello emette nella sua risposta. Un deny qui cattura la chiamata che il modello ha già deciso di fare, prima che raggiunga il tool.
Preferisci inbound quando vuoi che un tool sia invisibile — il modello non può chiamare ciò che non gli è mai stato offerto, così eviti turni sprecati in cui sceglie un tool solo per vederselo rifiutare. Usa response (o lascia stage vuoto) quando il tool compare legittimamente in alcune richieste e vuoi catturare la chiamata emessa effettiva, o quando controlli solo il loop dell’agent e non l’insieme di tool pubblicizzato.
Una regola senza stage si applica a tutte le superfici — lo stesso deny copre un tool che sia pubblicizzato, emesso o dispatchato attraverso MCP. È il default con cintura e bretelle; fissa una superficie solo quando un deny deve avere scope su una sola. Vedi Stage.

​
3. Collega la policy e osservala scattare

Una policy non fa nulla finché una chiave non si risolve su di essa. Collegala nella console impostando firewall_policy_id sulla chiave, o rendi la policy il default del workspace. La risoluzione è: la policy collegata alla chiave (quando esiste ed è abilitata), altrimenti il default del workspace. (Una policy collegata disabilitata ricade sul default — vedi Gestisci le policy.) Una volta collegata, una chiamata negata sulla superficie inbound restituisce HTTP 400 con codice di errore firewall_blocked e una motivazione che nomina il tool — es. tool "shell.exec" blocked by firewall. L’errore è marcato skip-retry (rieseguire la chiamata identica si limiterebbe a bloccarla di nuovo) e non costa token del modello, dato che un block inbound scatta prima della chiamata upstream. Un deny dispatchato attraverso il gateway MCP compare invece come un errore di tool, così il modello vede il rifiuto e può reagire.
Un deny sulla superficie inbound rimuove il tool da ciò che viene offerto al modello. Se il tuo framework per agent richiede che un tool che ha pubblicizzato sia chiamabile, bloccarlo inbound può confondere il loop — in quel caso blocca su response invece, così il tool rimane pubblicizzato ma la chiamata effettiva viene rifiutata. Testa la differenza prima di fare il rollout (vedi §5).

​
4. Deny è uno di diversi verdetti

Deny è il tool più contundente sulla deny-list. Quando un block netto è troppo, lo stesso glob può portare un verdetto più morbido:
VerdettoQuando ricorrervi al posto di deny
auditVuoi vedere il tool scattare ma non bloccarlo ancora.
sanitizeIl tool va bene ma i suoi argomenti possono portare segreti/PII — redige gli args, mai i risultati del tool.
pending_approvalUn umano dovrebbe approvare ogni chiamata fuori banda.
cap_costConsenti finché la spesa di un’esecuzione dell’agent supera un tetto in centesimi.
Tutti questi sono documentati in Verdetti. Una deny-list è semplicemente il sottoinsieme in cui il verdetto è deny. Per una postura allow-list (nega tutto, permetti un insieme nominato) cambia il default_verdict della policy in deny e aggiungi regole di allow strette — vedi Allow-listing dei tool.

​
5. Fai il rollout in sicurezza

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. Conferma che il tuo glob corrisponda al tool che intendevi (e solo a quel tool) prima di collegare una chiave. Vedi Testa le regole.
Attiva la shadow mode sulla policy e ogni verdetto applicativo — incluso il tuo deny — viene declassato a audit, con la motivazione prefissata [shadow] would …. Misuri esattamente cosa il deny bloccherebbe contro il traffico reale, poi disattivi lo shadow per applicare.
Non sicuro del nome esatto del tool da mettere in glob? La vista Discovered Tools elenca ogni tool che il workspace ha visto, marcato covered o gap. Scrivi il tuo deny direttamente dai nomi che sono effettivamente comparsi. Vedi Analytics.
Ogni valutazione scrive un evento del firewall con il verdetto, la superficie, il tool e la regola corrispondente. Dopo aver applicato, filtra il log degli eventi per verdetto deny per vedere la regola scattare sulle chiamate che ti aspettavi.

​
6. Chi può fare cosa

Tutta la configurazione della deny-list gira nella console sotto la tua sessione (/api/workspace/firewall/*):
AzioneRuolo
Leggere policy, preset, discovered tools, SimulateMember
Dry-run di una policy (Test)Developer+
Creare / modificare / eliminare regole e policyDeveloper+
Leggere il log degli eventi e le aggregazioni delle esecuzioniDeveloper+
Scrivere o modificare una regola di deny è una scrittura Developer+, e così è il dry-run Test della console. Leggere una policy e la vista Simulate (“what-if”) in sola lettura sono aperti a ogni membro.

​
Correlati

Sintassi glob

Esattamente come shell.*, *.exec e *.shell.* fanno match.

Allow-listing dei tool

La postura inversa: default-deny, permetti un insieme nominato.

Valida gli argomenti

Nega una sola forma di chiamata, non l’intero tool.

Chiamate a tool pericolose

La minaccia che una deny-list affronta.

Verdetti

Cosa fanno deny e i suoi fratelli più morbidi sul filo.

Riferimento del firewall

Il riferimento completo di regole + matching.