Modos de enforcement: observe, shadow e enforce

Antes que uma regra bloqueie tráfego de produção, você quer saber que ela dispara nas coisas certas e em nada mais. O OrcaRouter fornece três posturas — observe, shadow e enforce — que permitem fazer o rollout de forma incremental, com visibilidade em cada etapa e sem surpresas. Esta página explica o que cada postura significa mecanicamente, como transitar por elas e como os níveis de autonomia definem tudo isso em um único passo.

​

1. As três posturas em resumo

​

2. Postura de observe — meça antes de criar regras

A postura de observe não é um único interruptor. É uma combinação de três mecanismos independentes que juntos produzem “permita tudo, registre tudo”:

​

Observe mode do firewall (configuração de workspace)

Quando uma chamada de ferramenta resolve para nenhuma política — sem vinculação de chave e sem padrão de workspace — o observe mode em nível de workspace do firewall determina o que acontece:

• Observe mode ativado: a chamada é permitida e registrada como um gap de cobertura. A visão de Ferramentas Descobertas se preenche com esses eventos de gap, mostrando exatamente quais ferramentas seus agentes estão usando sem nenhuma regra cobrindo-as.
• Observe mode desativado: a chamada é permitida silenciosamente — byte-idêntica à de um workspace que nunca habilitou o recurso.

O observe mode é a superfície de detecção de gaps. Ele só dispara quando nenhuma política é resolvida. Ele não é o mesmo que ter uma política definida como audit.

​

Veredito audit do firewall (padrão por política)

Quando uma política é resolvida mas nenhuma regra corresponde a uma chamada de ferramenta, o default_verdict da política se aplica. O valor padrão para default_verdict é audit — permita a chamada e registre para revisão. Uma nova política sem regras e sem mudanças de configuração não bloqueia nada e não permite nada silenciosamente: ela audita tudo que vê. audit também é um veredito de regra normal. Uma regra que corresponde e produz audit deixa a chamada passar e a registra — o análogo do modo de auditoria de guardrail para o firewall.

​

Ação flag de guardrail (ação por regra)

No lado dos guardrails, a ação flag é o equivalente ao observe: a regra dispara, uma correspondência é registrada no feed de Matches e a requisição continua sem alteração. Sem bloqueio. Sem redação. Use flag quando você quiser medir uma regra — ver com que frequência ela dispara e em quê — antes de se comprometer com block ou mask.

---

Juntos, esses três produzem a postura de observe: o observe mode captura chamadas de ferramenta não cobertas; vereditos audit cobrem chamadas de ferramenta sob uma política mas ainda não sob uma regra específica; ações flag cobrem verificações de guardrail para as quais você ainda não está pronto para aplicar enforcement.

​

3. Postura de shadow — valide antes de aplicar

O shadow mode é uma flag por política (shadow_mode: true) em uma política de firewall. Quando ela está ativa:

• A política avalia cada chamada de ferramenta exatamente como faria em produção — regras são correspondidas, vereditos são calculados, predicados de argumento são testados.
• Todo veredito de enforcement (deny, sanitize, pending_approval) é rebaixado para audit antes de chegar à ferramenta.
• O motivo registrado recebe o prefixo [shadow] would … para que você possa ver no feed de eventos exatamente o que teria sido bloqueado, sanitizado ou retido.

O shadow mode é o seu interruptor de rollout seguro. Escreva uma política, ative o shadow, aponte tráfego real a ela, observe as visões de eventos e runs por algumas horas ou dias, confirme que a política dispara nas ferramentas certas e em nada inesperado, depois desligue o shadow mode para começar a aplicar.

​

4. Postura de enforce — vereditos reais, consequências reais

Na postura de enforce, nada é rebaixado:

• Firewall deny → o agente vê um erro de ferramenta (MCP) ou HTTP 400 firewall_blocked (superfície inbound). O erro nomeia a ferramenta e o motivo. Marcado como skip-retry.
• Firewall sanitize → substrings correspondentes são redigidas dos argumentos da ferramenta e a chamada limpa é encaminhada.
• Firewall pending_approval → a chamada é retida; o agente recebe HTTP 400 firewall_approval_pending e um id de aprovação para consultar.
• Guardrail block → HTTP 400 guardrail_blocked, nomeando o guardrail e a regra que disparou. Não custa cota.
• Guardrail mask → a correspondência é redigida (ex.: jane@acme.com → [EMAIL]) e a requisição continua com o texto sanitizado.

Para alcançar a postura de enforce: desligue shadow_mode na política de firewall e altere as ações de regra de guardrail de flag para block ou mask conforme apropriado.

​

5. Rollout recomendado

​

6. Níveis de autonomia — defina tudo de uma vez

Ajustar políticas regra por regra é o caminho preciso; os níveis de autonomia são o caminho rápido — um único controle que atomicamente define a postura de Firewall e Guardrails do seu workspace em uma transação, com desfazer em um clique: Aplique via POST /api/workspace/firewall/autonomy (Developer+). O endpoint Simulate (GET /api/workspace/firewall/simulate?level=) pré-visualiza o que uma mudança de nível faria antes que você a aplique.

​

7. Mapa de mecanismos — qual configuração faz o quê

Esta tabela é a referência autoritativa. Os quatro termos são distintos — não os confunda:

---

Os modos de enforcement não são um binário ligado/desligado. Mova-se por observe → shadow → enforce e suas regras são verificadas no tráfego real antes de bloqueá-lo.