Saltar para o conteúdo principal
Quando duas regras poderiam ambas corresponder à mesma chamada de ferramenta, a prioridade de regra do firewall decide qual vence. Uma política de firewall é uma lista ordenada de regras — o motor as percorre em ordem de prioridade, para na primeira que corresponde, e aplica seu veredito. Acerte a ordem e uma guarda ampla mais uma exceção estreita coexistem de forma limpa; erre-a e a regra ampla engole a exceção que você pretendia carvar. Esta página é a referência focada para ordenação. Para a gramática completa de regras veja Regras de Firewall; para os vereditos que uma regra pode produzir veja Vereditos.

​
1. A ordem: prioridade ascendente, primeira correspondência vence

Dentro de uma política, as regras são avaliadas em ordem priority ASC, id ASC:
  1. priority menor roda primeiro. Uma regra com priority: 0 é verificada antes de uma com priority: 10. Pense nisso como uma posição de fila, não um score de força — o número menor tem a primeira palavra.
  2. Empates quebram pelo id da regra. Duas regras na mesma priority rodam em ordem de criação (id de regra ascendente), então a regra mais antiga vence o empate. Use prioridades distintas quando a ordem realmente importa em vez de depender do desempate por id.
  3. Primeira correspondência vence. O motor para na primeira regra cujas condições todas se sustentam e aplica seu veredito. Regras mais abaixo na lista nunca são consultadas para aquela chamada.
  4. Nenhuma correspondência → o veredito padrão. Se nada corresponder, o default_verdict da política se aplica — audit a menos que você o tenha mudado.
Uma regra corresponde apenas quando toda condição declarada se sustenta de uma vez: a superfície, o glob de nome de ferramenta, o glob de skill opcional, as cláusulas de argumento opcionais, e o escopo de egress (apenas regras de egress). Uma correspondência parcial não é correspondência, e a avaliação passa para a próxima regra.

​
2. Um exemplo concreto: específico antes de amplo

O trabalho canônico de ordenação é deixar um allow estreito sobreviver a um deny amplo. Ponha a regra específica em uma prioridade menor para que ela seja alcançada primeiro: 
// Rule A — priority 10: trust this one exact tool.
{ "label": "allow safe shell", "priority": 10,
  "tool_name_glob": "shell.echo", "verdict": "allow" }

// Rule B — priority 20: block the rest of the shell family.
{ "label": "block shell family", "priority": 20,
  "tool_name_glob": "shell.*", "verdict": "deny" }
Uma chamada a shell.echo atinge a Rule A primeiro (prioridade 10), corresponde, e é permitida — o motor nunca alcança a Rule B. Uma chamada a shell.exec cai pela A (o glob não corresponde), atinge a Rule B, e é negada. Inverta as prioridades e o deny amplo shell.* na prioridade 10 pegaria shell.echo primeiro, e seu allow na prioridade 20 seria código morto. A regra de bolso: mais específico primeiro, mais amplo por último.
Não dependa do desempate por id para isso. Se o allow e o deny compartilham a mesma priority, o vencedor é qualquer regra que você criou primeiro — uma ordenação frágil que silenciosamente inverte se você deletar e recriar uma regra. Dê à regra específica uma priority menor e a intenção fica explícita.

​
3. Verifique a ordem antes de depender dela

Raciocinar sobre prioridade no papel é propenso a erros uma vez que uma política tem mais que um punhado de regras. O sandbox Test roda o motor real contra uma chamada de ferramenta de amostra e lhe diz não apenas o veredito mas qual regra venceu — para que você possa confirmar que a regra que esperava de fato disparou:
1

Abra a aba Test da política

No console, abra a política e mude para Test (Developer+).
2

Submeta uma chamada de amostra

Entre um nome de ferramenta (e argumentos, se suas regras os inspecionam) e rode. Nada é despachado e nada é persistido — é um dry run.
3

Leia a regra correspondente

O resultado nomeia o veredito, a regra correspondente (por label/id), e o motivo. Se uma regra ampla venceu onde você esperava uma estreita, abaixe a priority da regra estreita e re-teste.
Veja Testar regras para o sandbox completo, e Gerenciar políticas para editar a ordem de regras no lugar.

​
4. O enforcement de skill anda por cima

A prioridade de regra decide o veredito da regra vencedora — mas essa nem sempre é a resposta final. Se a chamada de ferramenta é de propriedade de uma skill governada, o modo de enforcement da skill é aplicado por cima do veredito vencedor, depois da resolução de primeira-correspondência:
Modo da skillEfeito sobre o veredito vencedor
allowSem mudança — o veredito da regra se mantém.
quarantineEscala qualquer coisa aquém de deny para pending_approval; um deny existente é deixado como está.
blockForça um deny independentemente do veredito da regra.
Então uma skill quarantine pode transformar um allow de regra em uma chamada retida, e uma skill block nega uma chamada mesmo quando nenhuma regra nomeia suas ferramentas. A quarentena apenas escala — ela nunca rebaixa um deny para algo mais brando. É por isso que uma skill autodetectada como arriscada permanece em quarentena até você revisá-la, não importa quão permissivas sejam suas regras.
O modo de skill não é uma regra, então não tem uma priority e você não pode reordená-lo relativo às suas regras. Ele sempre avalia depois que o veredito vencedor é escolhido. Se o modo de uma skill governada está bloqueando chamadas que você esperava permitir, conserte-o na skill, não adicionando uma regra de allow de prioridade mais alta — a regra não pode sobrescrever o modo.

​
5. Coisas que não andam por primeira-correspondência

Alguns mecanismos ficam fora da caminhada de prioridade por regra — saiba onde eles aterrissam para que você não tente ordená-los:
Uma regra cap_cost abaixo de seu teto é tratada como não-correspondente, então a avaliação continua para a próxima regra em vez de deixá-la vencer por primeira-correspondência como uma concessão. Acima do teto resolve para um deny. Ela nunca dá curto-circuito em uma regra de prioridade menor só por ser alcançada.
Uma regra de sequência corresponde a uma cadeia de chamadas ao longo de uma janela de tempo, então é aplicada reativamente por um matcher assíncrono em vez de na única chamada que completa a cadeia. Ela acende o feed de eventos mas não vence a caminhada de primeira-correspondência para uma chamada individual.
O shadow mode não muda qual regra vence — ele rebaixa o veredito de enforcement vencedor para audit (motivo prefixado [shadow] would …) depois da resolução de primeira-correspondência, para que você possa medir o impacto de uma política antes que ela altere o tráfego.

​
6. Juntando tudo

Para qualquer chamada de ferramenta a resolução completa é:
  1. Resolver a política — a vinculada à chave chamadora, ou o padrão do workspace. Veja escopo.
  2. Percorrer regras em priority ASC, id ASC — primeira correspondência vence; nenhuma correspondência → default_verdict.
  3. Aplicar enforcement de skill — o modo de uma skill governada anda por cima do veredito vencedor (block força deny, quarantine escala).
  4. Aplicar shadow mode — se ligado, rebaixa vereditos de enforcement para audit.
  5. Registrar o evento — veredito, superfície, ferramenta e regra correspondente aterrissam no feed de eventos.
Editar a prioridade de uma regra entra em vigor na próxima chamada para cada chave vinculada à política — sem redeploy, sem mudança no código do agente. Re-rode o sandbox Test depois de reordenar para confirmar o novo vencedor antes que o tráfego ao vivo dependa dele.

​
Para onde ir a seguir

Vereditos

O que cada veredito vencedor de fato faz.

Sintaxe de glob

Como a correspondência de nome de ferramenta decide se uma regra é sequer um candidato.

Testar regras

Faça dry-run de uma política e veja qual regra vence.

Allow-listing de ferramentas

O padrão default-deny que mais depende da ordenação.
Para a linguagem de correspondência por trás de uma regra, veja a referência completa de Regras de Firewall; para como as skills se sobrepõem, veja Firewall Skills e modos de enforcement.