Saltar para o conteúdo principal
Nomear uma ferramenta e negá-la é contundente: mata a ferramenta para cada chamada. Na maior parte do tempo a ferramenta está bem e uma forma de chamada é o problema — shell.exec está bem até o comando ser rm -rf, db.query está bem até atingir prod. Essa distinção é o que uma cláusula de argumento expressa: um predicado de argumento de ferramenta com jsonpath que corresponde aos valores que um agente passa, de modo que o veredito dispara apenas na chamada perigosa e deixa o resto em paz. Esta página é um cookbook — um punhado de receitas args_match_json para copiar-colar para os casos que mais aparecem. Para a gramática de cláusula completa, a tabela de operadores e a semântica de fail-closed, veja Validar argumentos e a referência de Schema de regra.

​
1. Como uma cláusula de argumento de ferramenta com jsonpath funciona

O args_match_json de uma regra é uma string codificada em JSON carregando um conjunto de cláusulas, todas combinadas com AND. O valor decodificado é um objeto, {"clauses": [ … ]}, onde cada cláusula é um triplo { path, op, value }:
  • path — um pequeno subconjunto de JSONPath sobre o objeto de argumentos da ferramenta: $.command, $.foo.bar, $.items[0], ou $ para o objeto inteiro. Sem wildcards, filtros, slices ou descida recursiva.
  • op — um entre um conjunto fechado: eq, contains, regex, in, cidr_match, gt, lt.
  • value — o literal a comparar (uma string, número, bool, ou — para in — um array JSON).
Uma cláusula é combinada com AND ao tool_name_glob da regra: a regra dispara apenas quando o nome da ferramenta corresponde e cada cláusula vale. Omita args_match_json inteiramente (ou deixe-o um "{}" vazio) e a regra corresponde ao glob sozinho.
As cláusulas falham fechadas — a regra, não a requisição. Se um path não resolve, os argumentos são malformados, ou um valor é do tipo errado, a cláusula avalia para false e a regra simplesmente não dispara — a chamada cai para a próxima regra ou o veredito padrão. Uma cláusula quebrada nunca auto-nega. Escreva seu backstop rígido como um deny de glob simples, não como uma cláusula na qual você está confiando para falhar de certa forma.

​
2. Receita: bloquear um comando destrutivo

O caso canônico. Permita shell.exec em geral, negue-o apenas quando o comando parece destrutivo. Uma cláusula regex em $.command faz isso: 
{
  "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=\"}]}"
}
Regexes são Go RE2 — tempo linear, sem backreferences, sem backtracking catastrófico — então são seguros para rodar em cada chamada de ferramenta. Um $.command não-string (ou um ausente) nunca corresponde, então uma chamada malformada cai através em vez de ser erroneamente bloqueada.
Prefira contains a regex quando estiver correspondendo a uma substring fixa — é mais simples de ler e não pode ser disparado por um metacaractere não escapado. Recorra a regex apenas quando você genuinamente precisar de alternância ou âncoras.

​
3. Receita: negar uma ferramenta contra um ambiente nomeado

Deixe db.query rodar, mas apenas contra conexões seguras — negue-o quando o alvo for prod ou uma replica. O operador in corresponde ao valor resolvido contra qualquer elemento de um 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\"]}]}"
}
O valor de in deve ser um array JSON — um não-array é rejeitado quando você salva a regra. Os elementos comparam com igualdade escalar, então números e strings cada um corresponde a seu próprio tipo.

​
4. Receita: negar um destino de IP privado ou metadata

Quando uma ferramenta recebe um IP alvo como argumento, cidr_match testa se ele cai dentro de um CIDR — a forma de SSRF de “um agente buscando 10.x ou o endereço de 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\"}]}"
}
O valor do argumento deve parsear como um literal de IP que se posiciona dentro do CIDR; um hostname ou uma string não-IP nunca corresponde.
cidr_match só inspeciona um valor que já está nos argumentos da ferramenta. Para governar o destino que uma ferramenta de fato alcança na camada de rede — listas de allow e deny de host/CIDR — use uma regra de egress dedicada na superfície egress em vez disso. As duas são complementares: inspeção de argumento na entrada, controle de egress na saída.

​
5. Receita: limitar um argumento numérico

gt e lt comparam números. Use-os para recusar um tamanho de batch absurdo, um limite superdimensionado, ou qualquer contagem descontrolada — aqui, negue um bulk delete que mira mais de 100 linhas: 
{
  "label": "block large bulk deletes",
  "tool_name_glob": "*.bulk_delete",
  "verdict": "deny",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.count\",\"op\":\"gt\",\"value\":100}]}"
}
Ambos os lados devem ser números — uma string com aparência numérica como "500" é uma incompatibilidade de tipo e não corresponde, então a regra não dispara num argumento tipado como string. Mantenha o argumento numérico, ou normalize-o antes de a ferramenta vê-lo.

​
6. Receita: combinar cláusulas (AND)

Todas as cláusulas em uma regra se combinam com AND, então você pode estreitar um veredito para uma chamada muito específica — por exemplo, negar shell.exec apenas quando for um comando destrutivo e estiver apontado para um 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\"]}]}"
}
Precisa de um OR em vez disso? Não há OR dentro de um único args_match_json — crie duas regras (ou dois globs) em prioridades diferentes. O motor percorre as regras em ordem de prioridade e a primeira correspondência vence, então coloque as regras estreitas primeiro. Veja Prioridade de regra.

​
7. Escolha o veredito para a forma correspondida

Uma cláusula decide quais chamadas correspondem; o verdict da regra decide o que acontece. deny é o padrão do cookbook, mas a mesma cláusula pode carregar um veredito mais suave:
Quando o argumento correspondido carrega um segredo ou PII em vez de uma instrução perigosa, sanitize redige as substrings correspondidas dos argumentos da ferramenta e encaminha a chamada limpa. Ele redige apenas argumentos — nunca o conteúdo que uma ferramenta retorna. Veja Sanitizar respostas.
Retenha exatamente a forma arriscada para revisão em vez de bloqueá-la totalmente: um revisor aprova ou rejeita fora de banda, e o agente reenvia a chamada aprovada uma vez. Veja Aprovações.
Defina o veredito como audit para registrar a chamada correspondida sem bloquear enquanto você ajusta a cláusula. Combine com shadow mode para medir um deny contra o tráfego ao vivo antes que ele mude qualquer coisa.

​
8. Teste a cláusula antes de depender dela

A aba Test do console faz dry-run de uma política contra uma chamada de ferramenta de amostra e retorna o veredito, a regra correspondente e o motivo — nada é despachado, nada é persistido. Cole um objeto de argumento realista e confirme que a cláusula dispara nas chamadas que você pretende e apenas essas, já que uma cláusula que não pode resolver um valor silenciosamente não dispara. Veja Testar regras.
As cláusulas são validadas estritamente ao salvar — operadores desconhecidos, paths ruins, um valor in não-array, um regex incompilável e CIDRs inválidos são todos rejeitados, então uma cláusula malformada não pode ser persistida em primeiro lugar.

​
9. Quem pode criar cláusulas de argumento

Tudo isso roda no console sob sua sessão (/api/workspace/firewall/*):
AçãoPapel
Ler políticas, presets, ferramentas descobertasMember
Criar / editar / deletar regrasDeveloper+
Sandbox de Test (dry-run de uma política)Developer+
Ler events e agregados de runDeveloper+
Criar ou alterar uma cláusula de argumento é uma escrita Developer+. O sandbox de Test também é Developer+ — ele pode pré-visualizar contra uma política rascunho e seu trace de veredito expõe nomes de política e labels de regra, então fica do lado de escrita da linha, não do lado de leitura.

​
Relacionados

Validar argumentos

O caso de uso de correspondência de argumentos por completo.

Bloquear ferramentas

Negue uma ferramenta inteira pelo nome — nenhuma cláusula necessária.

Controle de egress

Governe destinos outbound de host / IP / CIDR.

Schema de regra

Cada campo que uma regra pode carregar.

Prioridade de regra

A primeira correspondência vence — ordene estreito antes de amplo.

Chamadas de ferramenta perigosas

A ameaça que essas receitas endereçam.