Saltar para o conteúdo principal
Você escreveu uma política de firewall — uma postura default-deny, um deny em shell.exec, uma allow-list de egress — e acredita que está certa. Mas ativá-la contra o tráfego de agente em produção é um salto de fé: uma regra ampla demais e você está bloqueando chamadas que seus agentes fazem legitimamente. O shadow mode do firewall é o interruptor de rollout seguro. É uma flag por política que diz ao gateway para avaliar a política exatamente como faria em produção, registrar tudo, mas bloquear nada. Todo veredito de enforcement é rebaixado para audit, e o motivo do evento recebe o prefixo [shadow] would … para que você possa ler com precisão o que a política teria feito — sem que ela tenha feito nada ainda.
O shadow mode é uma flag na política, definida no console (ou nas rotas de gerenciamento /api/workspace/firewall/policies, que usam sua sessão / token de acesso — não uma chave de relay sk-orca-…). Alterná-lo é uma ação Developer+. As chamadas de relay /v1/* do seu agente não mudam.

​
1. O que o shadow mode do firewall faz

Quando a flag shadow_mode de uma política está ligada, o gateway roda a avaliação completa — resolve a política, percorre as regras em ordem de prioridade, escolhe um veredito — e então, logo antes de o veredito entrar em vigor, rebaixa qualquer coisa que teria mudado a chamada:
Veredito resolvidoSob shadow mode
deny→ audit, motivo [shadow] would deny — …
sanitize→ audit, motivo [shadow] would sanitize — …
pending_approval→ audit, motivo [shadow] would pending_approval — …
allow / auditinalterado (já não bloqueante)
A chamada sempre passa. Nada é bloqueado, nenhum argumento é redigido, nenhuma retenção humana é aberta — mas o evento é registrado com o veredito que a política teria produzido, de modo que o feed de events se lê como uma run de produção com o enforcement desligado.
O prefixo [shadow] would … é seu filtro principal. Ordene o feed de events por ele e você tem uma lista completa de cada chamada que esta política está prestes a começar a bloquear, antes que ela bloqueie uma.

​
2. Um rollout concreto

Digamos que você tenha uma política prod-agents com uma regra deny em comandos shell destrutivos, e queira confirmar que ela não dispara em nada legítimo.
1

Ligue o shadow mode

Em Security → Firewall → Policies, abra prod-agents, alterne Shadow mode para ligado, e salve. A política mantém seu vínculo e suas regras — apenas para de aplicar.
2

Deixe o tráfego real fluir

Seus agentes continuam chamando o gateway exatamente como antes. Cada chamada de ferramenta é avaliada; nada é bloqueado. Dê a ela uma janela representativa — longa o suficiente para cobrir seu mix real de ferramentas.
3

Leia as negações potenciais

Abra Events e filtre pelo motivo [shadow]. Cada linha mostra a ferramenta, a superfície, a run e a regra que correspondeu — então um [shadow] would deny — destructive shell command numa chamada shell.exec é exatamente o que você veria em produção, menos o HTTP 400.
4

Desligue o shadow mode

Uma vez que o feed mostre a política disparando no que você espera e em nada que você não espera, alterne o Shadow mode para desligado. A partir da próxima chamada, esses eventos [shadow] would deny se tornam negações firewall_blocked reais.
Se o shadow mode de fato revelou um falso positivo — uma chamada legítima que correspondeu a uma regra deny — corrija a regra (aperte o glob ou adicione uma cláusula de argumento) enquanto ainda está em shadow, e observe o feed de novo. Você itera contra o tráfego real com raio de explosão zero.

​
3. O que o shadow mode não suaviza

O shadow mode é um preview da política, não um interruptor mestre de desligar.
Skills governadas ainda aplicam enforcement sob uma política em shadow. Uma skill em modo block ainda nega, e uma skill em modo quarantine ainda retém para aprovação, mesmo quando a política correspondente está em shadow. O modo de enforcement de skill é uma propriedade do estado de revisão da skill, não da política que você está pré-visualizando — colocar uma política em shadow nunca foi um pedido para tirar uma skill da quarentena. A política permanece marcada como shadowed nos events, mas a disposição da skill vence.
Mais algumas fronteiras que vale conhecer:
Apenas vereditos de enforcement (deny, sanitize, pending_approval) são rebaixados. Um allow ou audit já deixa a chamada passar, então não há nada a suavizar — esses eventos ainda carregam o badge de shadow para que você possa saber que a política estava em shadow quando foram registrados.
Uma regra cap_cost resolve para um allow ou deny concreto com base no gasto acumulado da run, e esse veredito resolvido é o que o shadow mode então rebaixa — uma negação potencial por estouro de limite aparece como [shadow] would deny como qualquer outra.
O shadow mode vive em cada política independentemente. Você pode colocar uma política novinha em shadow enquanto uma já testada em batalha continua aplicando — não há interruptor de shadow para todo o workspace que você possa esquecer de desligar.

​
4. Shadow mode vs. os outros controles de rollout

O firewall oferece três controles diferentes de “não quebre nada ainda”. Eles resolvem problemas diferentes:
ControleEscopoPergunta que responde
Shadow modeUma política”O que esta política bloquearia se eu a aplicasse?”
Veredito padrão auditUma política”Registre tudo que nenhuma regra nomeia, bloqueie nada.”
Observe modeWorkspace”Quais ferramentas estão rodando sem política cobrindo-as?”
O shadow mode é o que você usa quando tem uma política real de enforcement e quer medir seu impacto exato antes de ela mudar o tráfego. Um veredito padrão de audit é para a cauda não correspondida de uma política; o observe mode é sobre gaps de cobertura em todo o workspace, não sobre o enforcement de uma política específica.
Você pode empilhá-los. Uma nova política default-deny sob shadow mode é o rollout mais suave possível: até o piso default-deny apenas registra [shadow] would deny em vez de bloquear, então você vê o conjunto completo de chamadas que suas regras de allow ainda não cobrem antes que o deny fique ao vivo.

​
5. Compliance packs aterrissam em shadow primeiro

Quando você instala um compliance pack em modo observe (não-enforcing), as políticas de firewall que ele materializa são criadas com o shadow mode ligado — elas avaliam e registram contra seu tráfego sem bloquear nada. Promover o pack para enforcement tira essas políticas do shadow. Mesmo mecanismo, aplicado para você: faça dry-run dos controles, leia os vereditos potenciais, depois aplique.

​
6. Alternando-o

No console, o shadow mode é um toggle no editor de política. A mesma flag é exposta na API de gerenciamento como shadow_mode no objeto de política — essas rotas usam sua sessão / token de acesso e exigem Developer+:
Método & pathPapelNota
PUT /api/workspace/firewall/policiesDeveloper+Defina shadow_mode: true / false na política no corpo.
GET /api/workspace/firewall/policies/:idMemberLê o estado shadow_mode atual de uma política.
Cada mudança escreve uma linha de auditoria e incrementa o inteiro version da política, então ligar e desligar o shadow é ele mesmo rastreado.

​
Para onde ir a seguir

Criar e vincular uma política

A configuração de dois passos cujo rollout o shadow mode faz — crie a política, vincule uma chave.

Log de events

Onde [shadow] would … aparece — filtre, aprofunde em runs e regras.

Vereditos

Os vereditos de enforcement que o shadow mode rebaixa, e o que cada um faz ao vivo.

Modos de enforcement

Como shadow, audit e observe se encaixam no modelo de enforcement mais amplo.
Para as ameaças que uma política deter uma vez que você desliga o shadow, veja chamadas de ferramenta perigosas e agência excessiva.