Saltar para o conteúdo principal
Uma regra de firewall corresponde a uma chamada de ferramenta em dois eixos: qual ferramenta (um tool_name_glob) e quais argumentos (cláusulas args_match sobre campos JSONPath). Esta página é a gramática precisa para ambos — o que um padrão corresponde, o que ele não corresponde, e como cada operador coage tipos — para que uma regra que você cria no console se comporte exatamente como você a lê aqui. O caso de uso principal: transformar um rude “bloqueie shell.exec” em um cirúrgico “bloqueie shell.exec somente quando o comando se parecer com rm -rf”. O glob escolhe a família de ferramentas; os operadores de argumento escolhem a chamada perigosa dentro dela.
Esta é a referência de sintaxe. Para onde essas cláusulas vivem em uma regra, a ordenação de regras e os vereditos, veja a referência aprofundada de Regras de firewall. Para os campos de regra em si, veja a visão geral de Firewall.

​
1. Onde esta sintaxe se aplica

Ambas as formas são criadas em uma regra de firewall, no console sob /console/firewall (escritas exigem Developer+). Você nunca chama o matcher diretamente — o gateway o avalia em cada chamada de ferramenta contra a política resolvida. Uma regra corresponde quando sua superfície, seu tool_name_glob, seu glob de skill opcional e suas cláusulas args_match todas correspondem; a primeira correspondência vence.
Uma regra sem cláusulas args_match corresponde apenas pelo glob de nome de ferramenta. Adicione cláusulas de argumento apenas quando o nome da ferramenta não for específico o suficiente.

​
2. Gramática de glob de nome de ferramenta

O tool_name_glob é uma gramática deliberadamente pequena e previsível — não uma regex completa. Os padrões são correspondidos de forma sensível a maiúsculas (nomes de ferramenta MCP são convencionalmente minúsculos-com-pontos, então uma case-fold surpreenderia você ao copiar um nome da aba Discovered tools).
Um padrão vazio ou um * simples corresponde a todas as ferramentas. Use-o em uma regra catch-all, ou confie no default_verdict da política em vez disso.
shell.* corresponde a shell.exec, shell.read, shell.write. Ele não corresponde ao shell simples (o ponto é obrigatório — um glob de prefixo só cobre filhos com namespace).
*.exec corresponde ao shell.exec com namespace e ao exec simples e sem namespace (chamadas de função nativas do provedor e servidores MCP sem namespacing expõem ferramentas sob o verbo simples, então uma regra de sufixo cobre ambos os formatos). O sufixo permanece ancorado em um ponto ou no início da string, então *.exec não corresponde a shell.execute.
*.shell.* corresponde a qualquer formato <server>.shell.<verb> — local.shell.exec, byo.shell.run. Ele requer ao menos um caractere de cada lado do infixo, então *.shell.* não corresponde ao shell simples nem a .shell. sozinho. Apenas o formato simétrico *.X.* é tratado como um infixo; um padrão misto como foo.*.bar cai para correspondência exata.
Qualquer padrão que não seja um dos quatro formatos de wildcard acima (incluindo um nome literal de ferramenta, ou um combo malformado como foo.*.bar) é comparado como uma string exata e sensível a maiúsculas.
Não há wildcard de caractere único ?, nem classes de caractere, nem * no meio do token (ex.: sh*l.exec). Um padrão que não seja um dos quatro formatos suportados é correspondido literalmente — sh*l.exec só corresponde a uma ferramenta literalmente chamada sh*l.exec. Crie com os formatos acima, não com memória muscular de regex.

​
3. Cláusulas de argumento JSONPath

args_match é um conjunto de cláusulas, cada uma um triplo {path, op, value}. O path é um JSONPath para o objeto de argumentos da chamada de ferramenta; op é um de sete operadores; value é o que comparar. Todas as cláusulas em uma regra são combinadas com AND — toda cláusula deve corresponder para que a regra dispare. 
{
  "clauses": [
    {"path": "$.command", "op": "regex", "value": "rm -rf|drop table"},
    {"path": "$.connection", "op": "in", "value": ["prod", "replica"]}
  ]
}

​
Subconjunto de JSONPath suportado

FormatoCorresponde
$.fooUma chave de nível superior.
$.foo.barUma chave aninhada.
$.foo[0]Um elemento de array por índice.
$.arr[1].kÍndice depois chave (combinações dos acima).
Esse é o subconjunto inteiro. Não há wildcards ($.*), filtros ($.foo[?(...)]), slices ($.foo[0:2]) nem descida recursiva ($..foo).
Fail-closed no path. Se o path de uma cláusula resolver para nada — a chave está ausente, os argumentos não são JSON válido, ou o valor é do tipo errado para o operador — essa cláusula avalia para false, a regra não dispara, e a avaliação cai para a próxima regra ou o padrão da política. Um argumento malformado nunca auto-nega e nunca derruba o motor.

​
4. Operadores de argumento

Sete operadores, um conjunto fechado. O validador do console e o motor ao vivo compartilham exatamente o mesmo vocabulário, então uma cláusula que salva é uma cláusula que roda.
OperadorComparaRegras de tipo
eqIgualdade exata.Tipado: string↔string, bool↔bool ou number↔number. Tipos mistos nunca correspondem.
containsContenção de substring.Ambos os lados devem ser strings; qualquer outra coisa é não-correspondência. Um valor vazio corresponde a qualquer string.
regexUm padrão RE2 (tempo linear, sem backreferences) contra uma string.Valor e arg resolvido devem ambos ser strings. Um padrão inválido desabilita a cláusula (nunca corresponde).
inPertinência — o valor é igual a qualquer elemento de uma lista.Valor deve ser um array JSON; cada elemento compara com a semântica de eq.
cidr_matchO valor resolvido é um IP dentro da rede dada.Valor é uma string CIDR (IPv4 ou IPv6, ex.: 10.0.0.0/8, fd00::/8); o arg deve fazer parse como um IP.
gtMaior-que, numérico.Ambos os lados devem coagir para um número. Uma string com aparência numérica não é coagida — é uma incompatibilidade de tipo (não-correspondência).
ltMenor-que, numérico.Mesma regra apenas-numérica de gt.
gt e lt são estritamente numéricos. Se uma ferramenta envia {"max_rows": "10000"} (uma string), uma cláusula gt 5000 não dispara — a string nunca é coagida. Compare números contra números; use regex ou contains para valores com formato de string.

​
5. Um exemplo trabalhado

Bloqueie um export destrutivo de banco de dados, mas apenas quando ele mira uma conexão de produção em um host de rede privada: 
{
  "tool_name_glob": "db.*",
  "args_match": {
    "clauses": [
      {"path": "$.statement", "op": "regex", "value": "(?i)drop|truncate|delete from"},
      {"path": "$.connection.name", "op": "in", "value": ["prod", "prod-replica"]},
      {"path": "$.connection.host_ip", "op": "cidr_match", "value": "10.0.0.0/8"}
    ]
  }
}
Leia de cima para baixo: o glob db.* escopa a regra para a família de ferramentas de banco de dados; as três cláusulas se combinam com AND, então o veredito (um deny, digamos) dispara apenas quando o statement é destrutivo e a conexão é um de dois alvos de prod nomeados e seu host cai na faixa privada 10.0.0.0/8. Um db.query contra uma conexão de dev em um IP público passa por esta regra intocado.
Prove a cláusula antes de confiar nela: a aba Test em uma política faz dry-run de uma chamada de ferramenta de amostra e mostra a regra correspondente e o veredito, sem persistir nada e sem despachar nada. Veja Observabilidade do firewall.

​
6. Regras de egress (host / CIDR)

O operador cidr_match acima corresponde a um IP que uma ferramenta reporta em seus argumentos. Isso é diferente de uma regra de superfície de egress, que avalia o destino outbound que uma ferramenta realmente alcança com uma lista de allow ou deny de host/CIDR — a principal defesa contra SSRF e exfiltração de dados. As regras de egress usam a mesma notação CIDR mas vivem na superfície egress; veja Regras de firewall para o formato da lista de egress.
Nenhum preset traz regras CIDR de egress prontas para você — o nível de autonomia tight nega os nomes de ferramenta comuns com formato de fetch (http_fetch, fetch_url, web_search, request), não faixas de rede. Crie sua própria regra de deny de host/CIDR quando precisar fixar o egress a destinos específicos.

​
7. Referência rápida

Formatos de glob

* tudo · foo.* prefixo · *.exec sufixo (+ verbo simples) · *.X.* infixo · qualquer outra coisa exato. Sensível a maiúsculas.

JSONPath

$.foo · $.foo.bar · $.foo[0] · $.arr[1].k. Sem wildcards, filtros, slices ou descida recursiva.

Operadores de string

eq (tipado) · contains (substring) · regex (RE2) · in (pertinência a lista).

Operadores numéricos & de rede

gt / lt (apenas numérico, sem coerção de string) · cidr_match (IPv4/IPv6 na faixa).

​
Relacionado

Regras de firewall

O modelo completo de regra — superfícies, ordenação, sanitizers, sequências e listas de egress.

Chamadas de ferramenta perigosas

A ameaça contra a qual essas cláusulas defendem, e como escopar uma regra para ela.

Glossário de vereditos

O que allow, audit, deny, sanitize e o resto fazem uma vez que uma regra corresponde.

Por que isto foi bloqueado?

Rastreie um bloqueio específico de volta à regra e cláusula que dispararam.