Saltar para o conteúdo principal
Uma política de firewall é uma lista ordenada de regras, e uma regra é apenas um pequeno conjunto de campos: a quais chamadas de ferramenta ela corresponde, em qual superfície, e o que fazer a respeito delas. Quando você precisa ler uma regra que outra pessoa escreveu — ou raciocinar com precisão sobre uma que está construindo — você quer a lista de campos em um só lugar. É esta página. Você cria regras no editor de regras do console (escritas exigem Developer+); o editor escreve os campos estruturados abaixo. Esta página é o mapa em nível de campo; o motor de correspondência profundo vive em Regras de Firewall.

​
1. O schema de regra do firewall num relance

Cada regra carrega os mesmos campos. Apenas verdict é sempre obrigatório — todo o resto restringe o que a regra corresponde ou configura o veredito escolhido, e um matcher ausente é vacuamente verdadeiro.
CampoPropósito
priorityOrdem de avaliação — menor roda primeiro.
verdictA ação quando a regra corresponde (obrigatório).
stageA superfície a que limitar; vazio = todas.
tool_name_globGlob no nome da ferramenta.
args_match_jsonPredicado de argumento JSONPath, como uma string codificada em JSON.
egress_jsonLista de allow-deny de host / CIDR (regras de egress), como uma string codificada em JSON.
sanitize_jsonConfig de redação (quando verdict = sanitize), como uma string codificada em JSON.
cap_cost_centsTeto de custo de run em centavos de USD (quando verdict = cap_cost).
sequence_jsonPredicado de cadeia ordenada de múltiplos passos (regras de sequência), como uma string codificada em JSON.
label / notesNome humano e justificativa — mostrados em eventos, ignorados pelo motor.
Uma regra dispara quando todos os seus matchers declarados se sustentam ao mesmo tempo — o stage corresponde (ou está vazio), o glob de ferramenta corresponde, as cláusulas de argumento correspondem (ou estão ausentes), e o escopo de egress corresponde (apenas regras de egress). O motor percorre as regras em ordem de prioridade e a primeira correspondência vence; se nada corresponder, o default_verdict da política se aplica.

​
2. priority — ordem de avaliação

Um ordinal inteiro. Menor roda primeiro; duas regras com a mesma prioridade quebram o empate pelo id da regra (ordem de inserção). Ponha suas exceções específicas acima dos seus catch-alls amplos — um allow para uma ferramenta confiável na prioridade 10 vence um deny * na prioridade 100.
Deixe lacunas (10, 20, 30) para que você possa encaixar uma nova regra entre duas existentes mais tarde sem renumerar a política inteira. Veja Prioridade de regra para estratégia de ordenação.

​
3. verdict — a ação

O único campo obrigatório. Quando uma regra corresponde, seu veredito decide o que acontece com a chamada:
VereditoEfeito
allowDeixa a chamada passar, registrada.
auditPermite e registra para revisão — o default_verdict usual.
denyBloqueia a chamada.
sanitizeRedige substrings correspondentes dos argumentos da ferramenta, depois encaminha.
pending_approvalRetém a chamada para um revisor humano.
cap_costNega assim que o gasto acumulado de uma run de agente cruza um limite.
Um deny retorna HTTP 400 firewall_blocked na superfície inbound, ou um erro de ferramenta na superfície mcp. Uma chamada retida retorna HTTP 400 firewall_approval_pending com um id que o agente consulta. No shadow mode cada veredito de enforcement é rebaixado para audit e o motivo recebe o prefixo [shadow] would …. Veja Vereditos para a tabela completa e os formatos de block.

​
4. stage — a superfície de enforcement

Fixa a regra a uma das superfícies do firewall. Deixe-o vazio e a regra se aplica a todas as superfícies:
As ferramentas que um agente anuncia ao modelo na requisição. Bloqueie uma ferramenta perigosa antes que o modelo sequer possa escolhê-la.
Os tool_calls que o modelo emite em sua resposta.
Um tools/call roteado através do gateway MCP do Firewall.
Um host / IP / CIDR outbound que uma ferramenta alcança — a superfície de SSRF e exfiltração de dados.
Algumas combinações de veredito + stage são rejeitadas ao salvar porque o veredito não pode disparar ali: cap_cost é um teto de custo de run pré-dispatch, inerte em response e egress; pending_approval só retém em inbound, então um pin explícito de response/egress é recusado. O editor oculta essas combinações; a API as rejeita. Veja Stages.

​
5. tool_name_glob — qual ferramenta

Um glob pequeno e sensível a maiúsculas no nome da ferramenta — shell.* para uma família inteira, *.delete para um verbo entre servidores, http_fetch para uma ferramenta exata. Vazio ou * corresponde a cada ferramenta. Um glob de nome de skill opcional (mesma gramática) faz AND de uma segunda condição na skill proprietária, de modo que você pode confiar em uma ferramenta de uma skill embutida e limitá-la a partir de uma da comunidade. A gramática completa — prefixo, sufixo, infixo, exato, e os extremos que confundem as pessoas — é sua própria referência: Sintaxe de padrão glob.

​
6. args_match_json — com quais argumentos

O glob responde qual ferramenta; args_match_json responde com quais argumentos — a diferença entre “bloquear shell.exec” e “bloquear shell.exec só quando o comando for rm -rf”. Seu valor é uma string codificada em JSON carregando um conjunto de cláusulas JSONPath, todas AND-adas. Decodificado, o objeto de cláusula se parece com: 
{
  "clauses": [
    { "path": "$.command",    "op": "regex",      "value": "rm -rf|drop table" },
    { "path": "$.connection", "op": "in",         "value": ["prod", "replica"] },
    { "path": "$.ip",         "op": "cidr_match", "value": "10.0.0.0/8" }
  ]
}
Em um corpo de requisição o campo carrega esse objeto como uma string com escape, ex.: "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf\"}]}". Os operadores são eq, contains, regex, in, cidr_match, gt e lt. Um args_match_json ausente é vacuamente verdadeiro — a regra corresponde no glob sozinho. A linguagem de predicado completa, a sintaxe de path, e o comportamento fail-closed de uma cláusula quebrada estão em Validar argumentos e no cookbook de argumentos.

​
7. egress_json — quais destinos

Usado na superfície egress: uma string codificada em JSON contendo uma lista de allow-and-deny de host / CIDR correspondida contra um destino outbound que uma ferramenta alcança. Decodificado, o objeto se parece com: 
{
  "deny":  ["169.254.169.254", "10.0.0.0/8"],
  "allow": ["api.openai.com"]
}
As entradas correspondem como um CIDR, um literal de IP, ou um hostname insensível a maiúsculas. A polaridade segue o veredito — com um veredito de enforcement a lista deny define o que é bloqueado e allow carva exceções dela.
O template de firewall Baseline entrega uma regra de deny de egress com uma denylist de SSRF / cloud-metadata pronta (o IP de metadata 169.254.169.254, faixas RFC-1918, loopback, link-local, e metadata.google.internal), de modo que você não precisa criá-las à mão. Adicione seus próprios destinos por cima para qualquer outra coisa que queira limitar. Veja Controle de egress para a receita completa e Exfiltração de dados para por que importa.

​
8. sanitize_json — redigir argumentos

Usado quando verdict = sanitize: uma string codificada em JSON nomeando quais presets / regexes custom redigem substrings correspondentes dos argumentos da ferramenta antes de a chamada limpa ser encaminhada — útil para remover um segredo ou um valor de PII que um agente colocou em um argumento sem bloquear a ação inteira. Decodificado, o objeto se parece com: 
{ "presets": ["email", "ssn_us"], "custom": ["foo-\\d+"] }
O sanitize redige apenas argumentos — nunca o conteúdo que uma ferramenta retorna. Uma regra de sanitize deve nomear pelo menos um preset ou padrão custom (um sanitizer vazio é rejeitado). Na superfície inbound não há argumentos em tempo de chamada para redigir, então um veredito de sanitize ali escala para um deny.
Veja Sanitize de respostas para a biblioteca de presets e os formatos de redação.

​
9. cap_cost_cents — um teto de gasto

Usado quando verdict = cap_cost: um teto de custo de run por regra, um inteiro em centavos de USD. Quando a regra corresponde, a chamada é negada assim que o gasto acumulado da run de agente cruza o limite — um disjuntor para um loop descontrolado, resolvendo para allow ou deny em eventos. O limite deve ser explícito e não-negativo, e a regra não pode ser fixada a response ou egress (onde o veredito é inerte). Comportamento completo em Limitar custo.

​
10. Uma regra completa

Juntando os campos — negar shell.exec, mas só quando o comando parecer destrutivo, com escopo às chamadas de ferramenta emitidas pelo modelo: 
{
  "priority": 10,
  "label": "block destructive shell",
  "stage": "response",
  "tool_name_glob": "shell.exec",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf|mkfs|:\\\\(\\\\)\\\\{\"}]}",
  "verdict": "deny",
  "notes": "fork bombs and recursive deletes only — plain shell.exec audits"
}
O stage corresponde à superfície response, o glob escolhe shell.exec, a cláusula única restringe a um comando destrutivo, e o veredito nega. Qualquer shell.exec cujo comando não corresponda ao regex cai para a próxima regra ou o padrão da política. Vincule uma chave à política (firewall_policy_id na chave) e ela está ao vivo na próxima chamada — sem redeploy.
Confirme que uma regra dispara exatamente no que você espera antes de depender dela: Testar regras faz dry-run de uma política contra uma chamada de ferramenta de amostra e retorna o veredito, a regra correspondente e o motivo sem despachar nada.

​
11. Como os campos se combinam

Um verdict. Todo o resto é opcional: um stage vazio corresponde a todas as superfícies, um tool_name_glob vazio (ou *) corresponde a cada ferramenta, e um args_match_json ausente corresponde a quaisquer argumentos. Um { "verdict": "audit" } puro é um catch-all válido.
Eles fazem AND. Uma regra dispara apenas quando seu stage, glob de ferramenta, glob de skill, cláusulas de argumento, e escopo de egress todos se sustentam. Para expressar OR, escreva regras separadas.
sanitize_json é lido apenas para o veredito sanitize; cap_cost_cents apenas para cap_cost; egress_json apenas na superfície egress. O console valida esses pareamentos ao salvar, de modo que uma regra que exibe um comportamento mas nunca pode aplicá-lo não pode ser persistida.
A priority menor vence (empates quebrados pelo id da regra) — primeira correspondência vence, e a avaliação para ali. Veja Prioridade de regra.

​
Relacionado

Crie uma política

Crie sua primeira política e vincule uma chave.

Sintaxe de glob

A gramática completa de glob de nome de ferramenta.

Vereditos

Cada veredito e como é um block.

Validar argumentos

Cláusulas de argumento JSONPath em profundidade.

Gerenciar políticas

Edite, versione e reverta políticas.

Regras de Firewall

A referência completa do motor de correspondência.
Novo no plano de ação? Comece na Visão geral do Firewall, ou veja como ele se combina com a filtragem de texto em Guardrails vs Firewall.