shell.exec com rm -rf /, uma API de
pagamento com um valor de transferência excessivo, uma ferramenta de banco de
dados direcionada à réplica de produção. Isso é abuso de ferramenta de
agente, e é um dos riscos mais consequentes em sistemas agênticos porque
chamadas de ferramenta têm efeitos colaterais no mundo real que frequentemente
são irreversíveis.
O Agent Firewall tem três defesas em camadas. Você pode implantá-las
independentemente ou em combinação.
1. Lista de permissão: nega tudo que você não permitiu explicitamente
O controle mais forte é uma lista de permissão. Em vez de tentar enumerar cada ferramenta perigosa, você enumera as ferramentas de que este agente legitimamente precisa — e nega todo o resto. Esta é a linha de base de zero trust. Uma política comdefault_verdict: deny e regras allow explícitas para cada
ferramenta aprovada consegue isso. Exemplo: um agente que deve apenas ler de
um CRM:
shell.exec, db.delete, payment.transfer —
seja emitida intencionalmente ou acionada por uma instrução injetada — acerta
o catch-all * e retorna um erro HTTP 400 firewall_blocked. O agente vê
um erro estruturado de ferramenta e não pode fazer retry (o bloqueio é marcado
como skip-retry), então não pode dar a volta à volta da negação.
Defina o
default_verdict da sua política como deny para enforcement
completo de lista de permissão. Com o veredito padrão audit, chamadas não
correspondidas são permitidas e registradas mas não bloqueadas — útil durante
o rollout mas não é um controle de segurança por si só.| Padrão | O que cobre |
|---|---|
crm.* | Todas as ferramentas no namespace crm |
*.read | Qualquer ferramenta de verbo de leitura em todos os servidores |
db.query | Exatamente esta uma ferramenta |
* | Tudo (use para seu catch-all deny) |
allow específicas em números de
prioridade baixos e o deny catch-all em um número alto.
2. Validação de argumento: permite a ferramenta, bloqueia a invocação perigosa
Uma lista de permissão em nomes de ferramenta é grosseira — ela bloqueiashell.exec completamente. Às vezes você quer permitir uma ferramenta mas
restringir como ela pode ser chamada. As cláusulas de argumento permitem
corresponder a campos específicos dentro dos argumentos da chamada de ferramenta,
usando JSONPath e um conjunto de operadores.
Exemplo: permite shell.exec mas bloqueia rm -rf
shell.exec é chamado e o argumento
$.command corresponde ao regex de comando destrutivo. Uma chamada normal
shell.exec com um comando seguro passa para a próxima regra (ou o veredito
padrão). Coloque esta regra em um número de prioridade menor do que qualquer
regra geral allow shell.exec para que ela dispare primeiro.
O conjunto completo de operadores de argumento:
| Operador | Use quando |
|---|---|
eq | Correspondência exata em um valor escalar (string ou número) |
contains | Correspondência por substring — ex.: $.query contains DROP TABLE |
regex | Correspondência de padrão RE2 — seguro no caminho quente, sem backtracking |
in | Valor deve estar em um array fornecido — ex.: permite apenas ambientes específicos |
cidr_match | Endereço IP em um bloco CIDR — útil para verificações de destino de egress |
gt / lt | Comparação numérica — ex.: $.amount gt 10000 para limites de pagamento |
args_match são com AND. Se um caminho não
existe nos argumentos da chamada, a cláusula avalia como false e a regra não
dispara — a chamada passa para a próxima regra ou o padrão.
Exemplo de guarda de pagamento — nega qualquer chamada de ferramenta de
pagamento com um valor excedendo um threshold:
3. Humano no loop: retém chamadas de alto risco para aprovação
Para ferramentas que são genuinamente necessárias mas de alto risco — acionar um deployment, aprovar um reembolso, enviar um email em massa — você pode exigir a assinatura de um humano antes que a chamada prossiga. O vereditopending_approval retém a chamada e retorna uma resposta
firewall_approval_pending ao agente:
pending_approval é compatível com cláusulas de argumento — você pode reter
apenas as invocações que correspondem a um threshold e deixar as rotineiras
passar:
4. Como uma chamada bloqueada parece
Uma chamada negada na superfície inbound (ferramenta anunciada na requisição) retorna HTTP 400 com código de errofirewall_blocked. A resposta inclui
metadata estruturado — o rótulo da regra correspondida, código de motivo e
fatores de risco — e é marcada como skip-retry para que um loop não possa
martelar a mesma chamada negada.
Uma chamada bloqueada na superfície response (o modelo já emitiu
tool_calls) retorna um erro de ferramenta visível ao modelo, dando-lhe
uma chance de reagir — escolher uma ferramenta diferente, perguntar ao usuário
ou parar — em vez de travar.
5. Ordenação de primeira correspondência vence
A ordenação de prioridade importa. O motor percorre regras em ordem crescente de prioridade e para na primeira correspondência. Um padrão comum:| Prioridade | Regra | Veredito |
|---|---|---|
| 5 | shell.exec + regex destrutivo | deny |
| 10 | shell.* (geral) | allow |
| 20 | crm.* | allow |
| 9999 | * (catch-all) | deny |
shell.exec com um
comando destrutivo é negado mesmo que haja um allow geral para shell.*.
Sem o deny de baixa prioridade, a regra allow shell.* venceria primeiro.
6. Rollout seguro com shadow mode
Antes de mudar uma nova política para enforcement, ative o shadow mode. A política avalia cada chamada de ferramenta e registra o veredito exatamente como faria em produção, mas todo veredito de enforcement (deny,
pending_approval, sanitize) é rebaixado para audit — nada é bloqueado.
O motivo no log de eventos recebe o prefixo [shadow] would deny para que
você possa medir o impacto nas visões de Events e Runs.
Uma vez que você confirmou que a política dispara no que você espera — e em
nada que você não pretendia — desligue o shadow mode. A próxima chamada é
aplicada com enforcement.
O nível de autonomia
tight aplica o preset block_destructive_shell
automaticamente. Se você precisa de uma postura rápida sem escrever regras,
aplique tight pelo console e ele inclui uma política de deny para chamadas
shell destrutivas em um passo. Você pode então adicionar suas próprias regras
de lista de permissão por cima. Veja Níveis de autonomia.7. Ameaças relacionadas
O abuso de ferramenta de agente raramente chega de forma isolada. Uma chamada de ferramenta não autorizada frequentemente é a consequência de outro vetor de ataque:- Injeção de prompt — um atacante embute instruções em conteúdo recuperado que direciona o agente para ferramentas que nunca deveria chamar.
- Agência excessiva — o agente recebeu mais acesso a ferramentas do que sua tarefa exige, tornando qualquer injeção ou configuração incorreta imediatamente perigosa.
- O modelo de ameaças — como o abuso de ferramenta se encaixa na superfície de ataque completa para sistemas agênticos.
Referência de regras do Firewall
A linguagem de correspondência completa — globs de ferramenta, cláusulas
de argumento, todos os operadores, vereditos e a API.
Visão geral do Firewall
Políticas, superfícies, níveis de autonomia, aprovação HITL e
observabilidade.