A linguagem de correspondência por trás de uma política de firewall. Corresponda chamadas de ferramenta por nome, skill, argumentos e destino — depois allow, audit, deny, sanitize, retenha para aprovação ou limite o custo. Determinística, fail-closed e segura no caminho quente.
Uma política de firewall é uma lista ordenada de
regras. Esta página é a referência completa do que uma regra pode
expressar — a linguagem de correspondência, os vereditos e como o motor os
avalia.As regras são criadas no editor de regras do console, que escreve objetos
de correspondência em JSON estruturado. Tudo abaixo descreve esse
vocabulário para que você possa ler, raciocinar sobre e verificar uma regra
com precisão — quer você a construa na UI ou a poste através da
API.
Configuração de redação, usada quando verdict = sanitize. Veja §5.
egress
object
Lista de allow/deny de host/CIDR, usada quando stage = egress. Veja §6.
cap_cost_cents
int
Teto de custo da run, usado quando verdict = cap_cost.
sequence
object
Correspondência ordenada de múltiplos passos, aplicada reativamente. Veja §8.
notes
string
Justificativa do autor; ignorada pelo motor.
Uma regra corresponde a uma chamada de ferramenta quando todas as suas
condições declaradas valem: o stage corresponde (ou está vazio), o glob de
ferramenta corresponde, o glob de skill corresponde (ou está vazio), 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.
Uma gramática deliberadamente pequena e sensível a maiúsculas/minúsculas —
sem surpresas de regex, tempo linear, segura no caminho quente de relay:
Padrão
Corresponde a
"" ou *
Toda ferramenta.
foo.*
Prefixo — foo.bar, foo.exec (não foo sozinho).
*.exec
Sufixo — shell.exec, db.exec (não exec sozinho).
*.shell.*
Infixo — local.shell.exec (precisa de ≥1 char de cada lado).
qualquer outra coisa
Correspondência exata de string (incluindo foo.*.bar).
As ferramentas são convencionalmente namespaceadas como server.tool ou
category.action, então shell.* captura uma família inteira e *.delete
captura um verbo entre servidores.
A mesma gramática de glob, correspondida contra a skill proprietária da
chamada de ferramenta (ex.: community.*, builtin.send). É combinada com
AND ao tool_name_glob, então:
corresponde a http.fetchsomente quando ele é de propriedade de uma
skill community.* — confie na mesma ferramenta de uma skill embutida,
gateie-a de uma da comunidade. Um glob de skill vazio corresponde a qualquer
proprietário. Como uma chamada de ferramenta é atribuída a uma skill é
coberto em Skills.
A correspondência de nome de ferramenta responde qual ferramenta; as
cláusulas de argumento respondem com quais argumentos — a diferença entre
“bloquear shell.exec” e “bloquear shell.exec somente quando o comando é
rm -rf.”args_match é um conjunto de cláusulas, todas combinadas com AND:
Um pequeno subconjunto de JSONPath sobre o objeto de argumentos da
ferramenta:
$.foo, $.foo.bar — acesso a campo
$.foo[0], $.arr[1].k — indexação de array
$ — o objeto de argumentos inteiro
Sem wildcards, filtros, slices ou descida recursiva.
As cláusulas de argumento falham fechado — a regra, não a requisição. Se
um path não resolve, os argumentos estão malformados, ou um regex/CIDR é
inválido, a cláusula avalia como false e a regra simplesmente não
dispara — a chamada cai para a próxima regra ou para o veredito padrão. Uma
cláusula quebrada nunca auto-nega e nunca quebra o relay. Escreva sua regra
de “capturar tudo perigoso” como um deny explícito com seu próprio glob em
vez de depender de uma cláusula falhar de uma forma específica.
O console valida as cláusulas estritamente ao salvar (operadores
desconhecidos, paths ruins, valores in não-array, regexes incompiláveis e
CIDRs inválidos são todos rejeitados) para que uma cláusula malformada não
possa ser persistida de início.
Um veredito sanitize redige substrings correspondentes dos argumentos da
ferramenta e encaminha a chamada limpa — útil para remover segredos ou PII
que um agente colocou em um argumento de ferramenta sem bloquear a ação
inteira.
Correspondências de preset são substituídas por [redacted:<preset>];
correspondências de regex personalizado por [redacted:custom]. A
biblioteca de presets embutidos:aws_access_key, aws_secret_key, openai_key, anthropic_key,
bearer_token, email, ssn_us, credit_card (com uma verificação de
Luhn).Uma regra de sanitize deve declarar pelo menos um preset ou padrão
personalizado — um sanitizer vazio é rejeitado ao salvar. Na superfície
inbound não há argumentos em tempo de chamada para redigir, então um
veredito sanitize ali escala para um block.
As entradas correspondem como um CIDR, um IP literal ou um hostname
insensível a maiúsculas/minúsculas; os hostnames são resolvidos em
best-effort e reverificados contra as entradas de IP/CIDR. A polaridade
segue o veredito: com um veredito allow a lista allow define o que está
em escopo e deny recorta exceções dela; com um veredito de enforcement
(deny) a lista deny define o que é bloqueado e allow recorta exceções.169.254.169.254 (o endpoint de metadados de nuvem) e os ranges RFC-1918
são as coisas canônicas a negar — o preset block_ssrf_egress e o
nível de autonomiatight entregam exatamente isso.
Alguns riscos só são visíveis ao longo de várias chamadas — ler 50
registros de CRM, depois exportar, depois alcançar um host externo. Uma
regra sequence corresponde a uma cadeia ordenada em vez de uma única
chamada:
Cada step é um glob de ferramenta com um min_count opcional (padrão 1) e um
egress: true opcional (o step deve ser uma chamada de egress). Os steps
devem ocorrer em ordem — intercalar com outras chamadas é aceitável — e a
cadeia inteira deve completar dentro de window_seconds (0 = sem limite).
As sequências são aplicadas reativamente por um matcher assíncrono, não
inline a cada chamada — uma sequência com um step * de outra forma
corresponderia a cada chamada de ferramenta. Elas acendem o feed de events e
podem disparar uma ação subsequente, mas não bloqueiam em tempo real a
chamada individual que completa a cadeia.
A primeira correspondência vence. As regras rodam em ordem
priority ASC, id ASC; a primeira regra cujas condições todas valem decide
o veredito. Nenhuma regra corresponde → o default_verdict da política.
Determinística e sem dependências. A correspondência de glob e cláusula
são operações puras de string/JSON sem chamada de rede, seguras para rodar
em cada chamada de ferramenta. Os regexes são RE2 — tempo linear, sem
backtracking catastrófico.
Cláusulas fail-closed. Uma cláusula que não pode ser avaliada faz sua
regra não disparar em vez de auto-negar (§4).
Validação estrita no momento de salvar. Pareamentos de
veredito/stage, não-vacuidade do sanitizer, presença de cap_cost_cents,
formato de cláusula e resolução de ref são todos verificados quando você
salva — regras inválidas não podem ser persistidas.
Auditada. Cada criação/atualização/exclusão de regra escreve uma linha
de auditoria depois que a mudança é commitada; blobs de regra e segredos
nunca são escritos no log de auditoria.
