Saltar para o conteúdo principal
Um agente de IA não apenas gera texto — ele age. Ele chama shell.exec, consulta um banco de dados, busca uma URL, despacha uma ferramenta através de um servidor MCP. Cada uma dessas é uma ação no mundo real que os guardrails em nível de prompt não conseguem ver. O agent firewall é o plano da camada de ação que as governa: uma política nomeada e com escopo de workspace que o gateway avalia em cada chamada de ferramenta, antes de ela chegar à ferramenta. Esta página é o hub da seção Firewall — o modelo de política, os vereditos, as superfícies e como uma política se vincula a uma chave. Cada ramo aprofunda, e a referência completa do motor vive em Firewall e Regras do Firewall.

​
1. O que o agent firewall faz

Você cria uma política uma vez no console do seu workspace, vincula uma chave de API a ela (ou define uma como padrão do workspace), e a partir daí cada chamada de ferramenta que essa chave emite é verificada contra a política no gateway. Sem redeploy, sem mudança no código do agente — seu agente continua emitindo chamadas de ferramenta exatamente como antes, e editar a política entra em vigor na próxima chamada para cada chave vinculada a ela. Uma política é uma lista ordenada de regras. Cada regra decide a quais chamadas de ferramenta ela se aplica e o que fazer a respeito delas. O motor percorre as regras em ordem de prioridade, a primeira correspondência vence, e cai de volta para o veredito padrão da política se nada corresponder.
A detecção acontece no gateway, no primeiro uso — não no momento da instalação. Uma ferramenta, servidor MCP ou skill que um agente autoinstala é capturada na primeira vez que sua chamada cruza o gateway. Esse é o único ponto de estrangulamento que vê cada fornecedor, cada agente e cada chamada de ferramenta independentemente de como a capacidade chegou ali.

​
2. Um exemplo concreto

Suponha que você queira bloquear comandos shell destrutivos mas deixar todo o resto passar sob audit. No console você cria uma política com default_verdict = audit e uma regra: 
{
  "label": "block rm -rf",
  "tool_name_glob": "*.exec",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf|drop table\"}]}",
  "verdict": "deny"
}
args_match_json é uma string codificada em JSON (o gateway a valida contra o schema de cláusula ao salvar): path é um JSONPath dentro dos argumentos da chamada, op é um entre eq, contains, regex, in, cidr_match, gt, lt. Vincule uma chave à política (defina firewall_policy_id na chave). Agora, quando um agente emite shell.exec com command: "rm -rf /", o gateway retorna HTTP 400 com o código de erro firewall_blocked e um motivo nomeando a ferramenta — e a chamada nunca chega ao shell. Toda outra chamada de ferramenta é permitida e registrada para revisão.
Faça o rollout de uma nova política primeiro sob shadow mode: ela avalia e registra exatamente como faria em produção, mas todo veredito de enforcement é rebaixado para audit e o motivo recebe o prefixo [shadow] would …. Observe o feed de events, depois desligue o shadow para aplicar.

​
3. Política, regras e resolução

Uma política tem escopo de workspace e é nomeada, com enabled, is_default, um default_verdict (allow / audit / deny, padrão audit) e uma flag shadow_mode. Uma regra é uma verificação dentro dela — veja Criar uma política e Schema de regra. Para qualquer chamada de ferramenta o gateway resolve a política ativa em ordem:
  1. Vínculo da chave — o firewall_policy_id da chave chamadora, quando essa política existe e está habilitada.
  2. Padrão do workspace — caso contrário, a política is_default habilitada.
Uma política de firewall vinculada que está desabilitada cai de volta para o padrão do workspace — isso difere dos guardrails, onde um vínculo desabilitado resolve para nenhum. O interruptor de desligar do firewall de uma chave é “use o padrão”, não “sem enforcement”. Veja Gerenciar políticas.
Quando nenhuma política resolve, o comportamento depende da configuração firewall_observe_mode do workspace: com o observe mode ligado, a chamada é permitida mas registrada como um gap de cobertura (ela aparece em Discovered Tools); com ele desligado, a chamada é permitida silenciosamente.

​
4. Vereditos

Uma regra — ou o padrão — produz um entre:
VereditoO que faz
allowDeixa passar, registrado.
auditPermite + registra para revisão. O padrão usual.
denyBloqueia. HTTP 400 firewall_blocked no inbound; erro de ferramenta no MCP.
sanitizeRedige substrings correspondentes dos argumentos da ferramenta e encaminha.
pending_approvalRetém para um humano; HTTP 400 firewall_approval_pending.
cap_costNega assim que o gasto da run cruzar um limite por regra.
Um veredito sanitize redige apenas os argumentos da chamada — nunca o conteúdo que uma ferramenta retorna. Na superfície inbound, onde ainda não há argumentos em tempo de chamada, o sanitize escala para um block. Veja Vereditos e Sanitizar respostas.

​
5. As quatro superfícies de enforcement

Cada chamada de ferramenta é avaliada contra exatamente uma superfície — fixe uma regra a uma com o campo stage, ou deixe-o vazio para aplicar a todas.

inbound

As ferramentas que um agente anuncia ao modelo na requisição. Bloqueie uma ferramenta perigosa antes que o modelo sequer possa escolhê-la.

response

Os tool_calls que o modelo emite em sua resposta.

mcp

Um tools/call despachado através do gateway MCP. Veja Servidores MCP.

egress

Um host / IP / CIDR outbound que uma ferramenta alcança — a superfície de SSRF e exfiltração de dados.

​
6. Correspondência

As regras expressam a quais chamadas de ferramenta capturam com um vocabulário pequeno e determinístico que é seguro no hot path:
Um glob case-sensitive no nome da ferramenta (shell.*, *.delete), opcionalmente combinado com AND a um glob na skill proprietária. Veja Sintaxe de glob e Allow-listing de ferramentas.
Predicados JSONPath sobre os argumentos da chamada com os operadores eq, contains, regex, in, cidr_match, gt, lt — a diferença entre “bloquear shell.exec” e “bloqueá-lo apenas quando o comando for rm -rf”. As cláusulas falham fechadas (a regra, não a requisição). Veja Validar argumentos.
Listas de allow e deny de host / IP / CIDR na superfície egress. Você pode criar sua própria regra de deny para faixas de cloud-metadata ou RFC-1918. Veja Controle de egress.
Uma regra sequence corresponde a uma cadeia ordenada de chamadas ao longo de uma janela (aplicada reativamente); uma regra cap_cost nega assim que o gasto acumulado de uma run do agente cruzar um teto em centavos. Veja Regras de sequência e Limite de custo.

​
7. Aprovação humana, autonomia e anomalias

  • Human-in-the-loop. Um veredito pending_approval retém a chamada e retorna seu id de aprovação. Um revisor a resolve no console (Developer+) ou via um callback de webhook assinado por HMAC; o agente consulta e reenvia com um header X-OrcaRouter-Firewall-Approval de uso único. Veja Aprovações e Webhook de aprovação.
  • Níveis de autonomia. Um interruptor define toda a sua postura: tight (default-deny + nega shell destrutivo + nega ferramentas com formato de fetch (http_fetch/web_search/fetch_url/request, o vetor de SSRF) + PII Shield + Secrets Blocker aplicados), balanced (audit por padrão, nega shell destrutivo, PII Shield apenas-audit) ou permissive (apenas observe). Cada um escreve linhas reais e editáveis de política e guardrail, com desfazer em um clique a partir do snapshot de auditoria.
  • Detecção de anomalias. Além das regras estáticas, o firewall pontua o uso de ferramentas contra um baseline de hora-da-semana aprendido (14 dias) e sinaliza picos de taxa/custo, retry_loop e novel_path num feed legível por Member no qual você pode dar snooze por até 7 dias.

​
8. Onde o firewall se encaixa

O firewall é o par na camada de ação de dois planos adjacentes:
PlanoGovernaQuando recorrer a ele
GuardrailsTexto de prompt e responsePII, segredos, jailbreaks, intenção de injeção
Agent firewallAções de ferramentaQuais ferramentas, chamadas MCP, hosts e custo
ComplianceEvidência e frameworksProntidão para SOC 2 / HIPAA / EU AI Act
Tanto o plano de conteúdo quanto o de ação podem se aplicar a uma única requisição, e um nível de autonomia os configura juntos. Veja Guardrails vs. Firewall e a pilha de controle.

​
9. Vinculando e conectando

Uma política se vincula a uma chave via firewall_policy_id (configurado no console; o vínculo vive na chave dentro do gateway). Duas maneiras de uma chamada de ferramenta chegar ao motor, ambas exigindo uma chave com escopo de firewall-gateway (is_firewall_gateway = true) — uma chave de relay normal recebe 403 nessas rotas:
  • Gateway MCP — aponte seu cliente MCP para o endpoint unificado ANY /api/v1/firewall/mcp; cada tools/call é avaliado inline. Veja Servidores MCP.
  • Hook de avaliação — chame POST /api/v1/firewall/evaluate (ou /evaluate_plan para um plano de múltiplos passos) a partir do seu próprio loop de agente antes de despachar, e aja sobre o veredito.
Toda a configuração do console roda na sua sessão via /api/workspace/firewall/*. Leituras de políticas, configurações, ferramentas descobertas, o simulador de autonomia somente-leitura e o feed de anomalias são abertas a cada membro do workspace; o sandbox dry-run de Test, o log de Events / Runs e todas as escritas exigem Developer+. Veja Chaves de gateway e Testar regras.

​
10. Ameaças que este plano endereça

Chamadas de ferramenta perigosas

Nega shell destrutivo, drops de DB e verbos arriscados por glob + args.

Exfiltração de dados

Listas de egress e regras de sequência ler-depois-exportar.

Envenenamento de ferramenta MCP

Avaliação por chamada na superfície mcp antes do dispatch.

Agência excessiva

Aprovações, limites de custo e postura default-deny.

​
Próximos passos

Criar uma política

Crie sua primeira política e regra.

Vereditos

O que cada veredito faz na prática.

Log de events

Leia o que o firewall decidiu e por quê.