Saltar para o conteúdo principal
Um agente de código é a coisa de maior alavancagem no seu workspace e a mais perigosa. Ele roda shell.exec, edita arquivos, busca URLs e carrega skills da comunidade — qualquer uma das quais pode rm -rf um volume, ler um .env ou exfiltrar para um host atacante. Esta receita restringe essa superfície com o Firewall: negue shell destrutivo, valide os argumentos das chamadas que você de fato permite, cerque o egress e retenha as operações genuinamente arriscadas para um humano. Nada disso toca no código do seu agente — a política vive no gateway e é aplicada na próxima chamada.
Tudo abaixo é configurado no console (Firewall → Posture / Policies). Essas rotas de gerenciamento usam a sua sessão de console, não uma chave de relay. Apenas as chamadas /v1/* que o seu agente faz carregam uma chave sk-orca-…. Edições de política exigem o papel Developer.

​
1. Comece observando, não bloqueando — a linha de base do agente de código seguro

Não crie regras às cegas. Dê ao agente sua chave sk-orca-…, depois abra Firewall → Posture e aplique o nível de autonomia balanced. Em uma transação isso audita cada chamada de ferramenta, sinaliza PII e nega shell destrutivo — então a pior ação já está cercada enquanto você aprende o resto do comportamento do agente a partir do tráfego real. Deixe-o rodar, depois leia Firewall → Discovered tools: cada ferramenta que o workspace viu, marcada covered (uma regra se aplica) ou gap (nenhuma se aplica). Essa lista é o rascunho da sua allow-list. Quando o feed parecer certo, mude para tight (default-deny) ou crie a política direcionada abaixo.
balanced é a postura inicial recomendada; permissive não bloqueia nada mas ainda registra tudo; tight é default-deny mais os presets de secrets e SSRF. Veja a linha de base para exatamente o que cada uma materializa.

​
2. Negue shell destrutivo — o piso inegociável

A regra mais importante para um agente de código é nenhum shell destrutivo. Os níveis de autonomia balanced e tight já entregam isto como o preset Block destructive shell, que materializa regras deny reais e editáveis cobrindo tanto os nomes de ferramenta diretos do workspace (shell.*, bash, cmd.*, powershell.*, exec.*) quanto as formas com namespace de MCP que um servidor registrado expõe (*.shell.*, *.cmd.*, …). Se você preferir escopar isto mais apertado que “negar todo shell”, crie uma regra que só nega os comandos destrutivos e audita o resto. Uma regra corresponde a um glob de nome de ferramenta mais um predicado de argumento opcional (JSONPath contra os argumentos da chamada):
Em Firewall → Policies, adicione uma regra acima do seu padrão:
  • Tool glob: shell.exec
  • Args match (cláusula JSONPath):
{
  "clauses": [
    { "path": "$.command", "op": "regex", "value": "(?i)\\brm\\s+-[a-z]*[rf]" }
  ]
}
  • Veredito: deny
Os operadores de argumento são um conjunto fechado — eq, contains, regex, in, cidr_match, gt, lt. Uma chamada cujo $.command corresponde ao regex é bloqueada; todo o resto cai para a próxima regra.
Uma chamada negada na superfície inbound retorna HTTP 400 com o código de erro firewall_blocked e uma mensagem nomeando a ferramenta e o motivo. Uma chamada despachada através do gateway MCP volta como um erro de ferramenta (firewall deny: …) para que o modelo possa reagir em vez de quebrar. Blocks inbound disparam antes da chamada ao modelo upstream, então não custam tokens de modelo.
Veja Regras de firewall para a linguagem de correspondência completa (globs de ferramenta, cláusulas de argumento, sequências, limites de custo).

​
3. Valide argumentos nas ferramentas que você mantém

Permitir uma ferramenta não é o mesmo que permitir cada argumento dela. O mesmo predicado JSONPath que escopa um deny permite restringir o formato de uma chamada permitida — para que db.query não possa carregar um DROP, e file.write não possa escapar de um diretório.

Bloqueie um SQL DROP

Glob db.query, cláusula {"path":"$.sql","op":"regex","value":"(?i)\\bdrop\\b"}, veredito deny.

Redija um segredo nos args

O veredito sanitize redige substrings correspondentes dos argumentos da chamada de ferramenta antes que a chamada seja encaminhada. Ele nunca toca no que uma ferramenta retorna; na superfície inbound (sem args em tempo de chamada ainda) ele escala para um block.
O Firewall sanitiza os argumentos da chamada de ferramenta, não os resultados da ferramenta. Para impedir que um segredo entre em uma requisição em primeiro lugar, vincule o guardrail Secrets Blocker à chave — isso filtra o próprio texto do prompt antes que o modelo o veja. Os dois planos se compõem: os guardrails filtram texto, o Firewall governa a ação.

​
4. Controle o egress — cerque onde o agente pode alcançar

Um agente de código que pode buscar URLs pode ser guiado para SSRF (atingindo cloud-metadata ou um host interno 10.x) ou usado para exfiltrar. O nível de autonomia tight entrega um preset de SSRF que nega nomes de ferramenta no formato de fetch (http_fetch, web_search, fetch_url, request e suas formas <server>.*) de imediato. Para controle em nível de destino, crie uma regra de egress. Regras de egress escopam por host ou CIDR com entradas allow / deny, avaliadas na superfície egress: 
{ "deny": ["169.254.169.254", "10.0.0.0/8", "*.internal"] }
Isso dispara em qualquer destino outbound reportado por uma ferramenta que caia em um range privado, no IP de cloud-metadata ou em um hostname interno — deixando destinos públicos passar enquanto cerca os perigosos.
Nenhum preset entrega regras de egress baseadas em CIDR — o preset de SSRF corresponde a nomes de ferramenta no formato de fetch. A denylist de host/CIDR acima é uma que você mesmo cria. Veja Pare a exfiltração para o padrão completo.

​
5. Retenha operações arriscadas para um humano (HITL)

Algumas operações não deveriam ser auto-permitidas nem auto-negadas — um deploy, um git push, uma migração destrutiva. Para essas, use o veredito pending_approval. A chamada é retida, o agente recebe uma resposta “held” com um id de aprovação, e um revisor a resolve fora de banda:
  1. Crie uma regra (ex.: glob deploy.*, veredito pending_approval).
  2. A chamada retida retorna HTTP 400 firewall_approval_pending com um id de aprovação.
  3. Um revisor a aprova a partir do console (Developer+) ou via um callback de webhook assinado por HMAC.
  4. O agente consulta a aprovação, depois reenvia a chamada original com um header X-OrcaRouter-Firewall-Approval de uso único — e o gateway a deixa passar aquela única vez.
Faça o rollout de qualquer política nova em shadow mode primeiro. A política avalia e registra exatamente como faria em produção, mas todo veredito de enforcement é rebaixado para audit com um motivo [shadow] would … — então você pode provar que ela dispara no que você espera antes que possa quebrar um build.

​
6. Governe as skills e servidores MCP que ele carrega

Agentes de código puxam capacidades em tempo de execução — skills da comunidade, servidores MCP próprios. O Firewall governa ambos no gateway:
  • Skills são escaneadas em uma faixa de risco com um modo de enforcement (allow / quarantine / block). Uma skill auto-detectada é quarentenada — retida para aprovação — até que um revisor a libere. Veja Skills.
  • Servidores MCP que você registra despacham cada tools/call através do gateway, que avalia cada um na superfície mcp antes do dispatch. As credenciais são armazenadas criptografadas; uma sonda de saúde reporta ok / degraded / down. Veja Servidores MCP e Endureça um agente MCP.

​
7. Verifique e observe

Antes de depender de uma política, faça um dry-run dela. A aba Test avalia uma chamada de ferramenta de amostra contra a política atual e mostra o veredito, a regra correspondente e o motivo — nada é despachado, nada persistido. Uma vez ao vivo, Firewall → Events / Runs é o registro de cada avaliação, filtrável por veredito, superfície, ferramenta e run, e o feed de anomalias sinaliza picos de taxa/custo contra a baseline aprendida do workspace, retry_loop e caminhos de ferramenta nunca antes vistos.

​
Recapitulação

Referência de Firewall

O plano de política completo — superfícies, vereditos, resolução, autonomia.

Regras de firewall

A linguagem de correspondência: globs, cláusulas de argumento, egress, sequências.

Chamadas de ferramenta perigosas

A ameaça contra a qual esta receita defende.

Agência excessiva

Por que agentes superpermissionados são o risco central de agente.

Receita de agente autônomo

Restrinja um loop de agente totalmente autônomo de ponta a ponta.

Pare a exfiltração

Os padrões de egress e tríade letal em profundidade.