Regras
A linguagem de correspondência — globs de ferramenta, cláusulas de
argumento, listas de egress, sanitizers e sequências.
Servidores MCP
Registre e governe servidores Model Context Protocol atrás de um único
gateway auditado.
Skills
Escaneie e pontue o risco das capacidades que seus agentes instalam
antes que elas possam rodar.
1. O que é o Firewall
Um agente de IA não apenas gera texto — ele age. Ele chamashell.exec,
consulta db.query, busca uma URL, carrega uma skill da comunidade ou
roteia uma chamada de ferramenta através de um servidor MCP de terceiros.
Cada uma dessas é uma ação com consequências no mundo real, e os guardrails
em nível de prompt não conseguem vê-las.
O Firewall é uma política nomeada e com escopo de workspace que o
gateway avalia em cada chamada de ferramenta. Você cria uma política uma
vez, 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 — antes de chegar à ferramenta.
Cada política é uma lista ordenada de regras. Uma regra decide uma
coisa — a quais chamadas de ferramenta ela se aplica (um glob de nome de
ferramenta, opcionalmente com escopo para uma skill e para uma superfície
de enforcement) e o que fazer a respeito delas (um veredito: allow,
audit, deny, sanitize, retenção para aprovação ou limite de custo). 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.
Editar uma política entra em vigor em cada chave vinculada a ela já na
próxima chamada. Sem redeploy. Sem mudança no código do agente. A política
é aplicada no gateway — seu agente continua emitindo chamadas de ferramenta
exatamente como antes.
A detecção acontece no gateway, no primeiro uso. O Firewall fica no
caminho de relay do LLM, não dentro do gerenciador de pacotes ou do sistema
de arquivos do seu agente. Uma ferramenta, servidor MCP ou skill que um
agente autoinstala é capturada na primeira vez que sua chamada cruza o
gateway — não no momento da instalação. Isso é deliberado: é o único ponto
de estrangulamento que vê cada fornecedor, cada agente e cada chamada de
ferramenta independentemente de como a capacidade chegou ali.
2. As quatro superfícies de enforcement
Cada chamada de ferramenta é avaliada contra exatamente uma superfície — o ponto no ciclo de vida da requisição onde o firewall a vê:| Superfície | O que ela vê |
|---|---|
inbound | As ferramentas que um agente anuncia ao modelo na requisição (definições de ferramenta). Permite bloquear 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 do Firewall ou avaliado via o hook do SDK. |
egress | Um destino de rede outbound (host / IP / CIDR) reportado por uma ferramenta — a superfície de SSRF e exfiltração de dados. |
3. Conceitos centrais
| Conceito | Definição |
|---|---|
| Política | Um conjunto nomeado de regras, com escopo de workspace. Tem enabled, is_default, um default_verdict e uma flag shadow_mode. |
| Regra | Uma verificação dentro de uma política: uma prioridade, uma correspondência de tool/skill, uma superfície opcional, um predicado de argumento opcional e um veredito. Veja Regras. |
| Veredito | A ação que uma regra (ou o padrão) produz — veja §4. |
| Veredito padrão | Aplicado quando nenhuma regra corresponde. Um entre allow, audit (padrão) ou deny. |
| Shadow mode | A política avalia e registra mas nunca bloqueia — todo veredito de enforcement é rebaixado para audit e o motivo recebe o prefixo [shadow] would …. Seu interruptor de rollout seguro. |
| Observe mode | Uma configuração em nível de workspace. Quando uma requisição resolve para nenhuma política e o observe mode está ligado, a chamada é permitida mas registrada como um gap de cobertura — é o que popula a visão de Ferramentas descobertas. |
Escopo e resolução
As políticas resolvem exatamente como os Guardrails e as chaves de API — compartilhadas no workspace quando você tem um workspace ativo. Para qualquer chamada de ferramenta, o gateway resolve a política nesta ordem:- Vínculo da chave — se a chave chamadora tem um
firewall_policy_id, essa política se aplica (quando existe e está habilitada). - Padrão do workspace — caso contrário, a política
is_defaulthabilitada do workspace se aplica. - Nenhuma — sem enforcement. Com o observe mode ligado, a chamada é permitida e registrada como um gap; com ele desligado, a chamada é permitida silenciosamente (byte-idêntica à de um workspace que nunca habilitou o recurso).
Fail-open no desconhecido, fail-closed no ambíguo. Se a resolução de
política encontrar um erro transitório, o gateway degrada para
observe/allow em vez de derrubar o tráfego. Mas onde não aplicar
derrotaria a regra — um relatório de egress sem destino utilizável, um
armazenamento de aprovação inalcançável, uma skill cuja propriedade não
pode ser resolvida — o motor falha fechado (deny ou hold). A
disponibilidade é preservada; a segurança não é silenciosamente pulada nos
casos que importam.
4. Vereditos
Uma regra (ou o veredito padrão) produz um entre:| Veredito | O que faz |
|---|---|
allow | Deixa a chamada passar. Registrada. |
audit | Permite, mas registra para revisão. O default_verdict padrão — observe tudo, bloqueie nada, até você estar pronto. |
deny | Bloqueia a chamada. O agente vê um erro de ferramenta (ou HTTP 400 na superfície inbound). |
sanitize | Redige substrings correspondentes dos argumentos da ferramenta (segredos, PII) e encaminha a chamada limpa. Veja sanitizers. Na superfície inbound — onde ainda não há argumentos em tempo de chamada — o sanitize escala para um block. |
pending_approval | Retém a chamada para um humano. O agente recebe uma resposta “held”; um revisor aprova ou rejeita fora de banda; o agente reenvia com um token de aprovação de uso único. Veja §7. |
cap_cost | Nega assim que o gasto acumulado da run do agente exceder um limite por regra em centavos. Um disjuntor para loops descontrolados. |
deny / sanitize / pending_approval são todos rebaixados
para audit para que você possa medir o impacto de uma política antes que
ela altere o tráfego.
5. Como uma chamada de ferramenta é avaliada
- Uma chamada de ferramenta chega ao gateway (anunciada inbound, emitida em uma response, despachada através do gateway MCP, ou reportada como egress).
- O motor resolve a política ativa (§3).
- Ele percorre as regras da política em ordem de prioridade (prioridade menor primeiro; empates resolvidos pelo id da regra). Uma regra corresponde quando sua superfície, seu glob de nome de ferramenta, seu glob opcional de nome de skill, suas cláusulas de argumento opcionais e seu escopo de egress opcional todos correspondem.
- A primeira correspondência vence → o veredito da regra se aplica. Se
nenhuma regra corresponder → o
default_verdictda política. - Se a chamada é de propriedade de uma skill
governada, o modo de enforcement da skill é aplicado por cima — uma skill
em modo
blockforça um deny; uma skill em modoquarantineescala qualquer coisa aquém de deny parapending_approval. - A decisão é registrada como um evento de firewall (a menos que seja um dry run), correlacionada à run e à sessão do agente.
6. Como é um block
Uma chamada negada na superfície inbound retorna HTTP 400 com um corpo de erro no formato da OpenAI, código de errofirewall_blocked e uma
mensagem nomeando a ferramenta e o motivo — ex.: tool "shell.exec" blocked by firewall: destructive shell command. O erro carrega metadata
estruturado (código de motivo, fatores de risco, score) e é marcado como
skip-retry (reexecutar a mesma chamada apenas bloquearia de novo).
Uma chamada despachada através do gateway MCP é bloqueada como um erro
de ferramenta (firewall deny: <reason>) em vez de uma falha de
transporte, de modo que o modelo vê a rejeição e pode reagir — escolher
outra ferramenta, perguntar ao usuário, ou parar — em vez de quebrar.
Uma chamada retida (pending_approval) retorna HTTP 400 com o código
firewall_approval_pending e um id de aprovação que o cliente consulta.
7. Aprovação humana (HITL)
Um vereditopending_approval transforma uma chamada de ferramenta em uma
revisão fora de banda:
- O motor enfileira um registro de aprovação e retorna uma resposta “held” carregando seu id; a chamada não chega à ferramenta.
- Um revisor a resolve — a partir do console (Developer+), ou via um callback de webhook assinado por HMAC para o seu próprio sistema de aprovação.
- Seu agente (ou o SDK MCP) consulta o id de aprovação; uma vez
aprovado, ele reenvia a chamada original com um header
X-OrcaRouter-Firewall-Approvalde uso único, e o gateway a deixa passar aquela única vez.
rule_changed para que os
revisores saibam que o contexto mudou.
8. Níveis de autonomia — um interruptor para toda a sua postura
Ajustar políticas regra por regra é o caminho preciso; os níveis de autonomia são o rápido. Um único controle substitui atomicamente a postura de Firewall e de Guardrails do seu workspace em uma transação, com desfazer em um clique:| Nível | Postura |
|---|---|
tight | Bloqueia shell destrutivo, segredos em argumentos e egress SSRF (default deny); guardrails PII Shield + Secrets Blocker ligados; observe mode desligado. |
balanced | Audita shell destrutivo, sinaliza PII; observe mode desligado. A postura inicial recomendada. |
permissive | Sem política de enforcement, sem guardrails; observe mode ligado para que você ainda veja tudo. |
9. Detecção de anomalias
Além das regras estáticas, o Firewall aprende a forma normal de uso de ferramentas de cada workspace e sinaliza desvios em um feed legível pelo viewer:- Picos de taxa / custo — a atividade por ferramenta é pontuada contra
um baseline de hora-da-semana aprendido (uma média móvel de 14 dias),
de modo que “100 chamadas
db.queryàs 3h de domingo” se destaca mesmo se cada chamada for individualmente permitida. retry_loop— um agente martelando a mesma ferramenta que falha.novel_path— uma transição de ferramenta-para-ferramenta que este workspace nunca fez antes.
10. Observabilidade
O Firewall deixa um rastro sobre o qual você pode agir, todo com escopo de workspace:| Superfície | O que ela oferece |
|---|---|
| Events | Cada avaliação, filtrável por veredito, superfície, ferramenta, run e sessão. O registro bruto por trás de todo o resto. |
| Runs & sessions | Eventos consolidados por run de agente ou conversa — breakdown de veredito, ferramentas e modelos distintos, primeiro/último visto. A visão de “o que este agente realmente fez”. |
| Discovered tools | Cada ferramenta que o workspace viu, marcada covered (uma regra se aplica) ou gap (nenhuma se aplica). Conduz a criação de políticas a partir do tráfego real. |
| Simulate | Pré-visualize o que um nível de autonomia mudaria antes de aplicá-lo. |
| Test | Faça um dry-run de uma política contra uma chamada de ferramenta de amostra e veja o veredito, a regra correspondente e o motivo — nada é persistido, nada é despachado. |
| Audit | Cada mudança de política, regra e configuração escreve uma linha de auditoria (workspace + central) depois que a mudança é commitada. Segredos e blobs de regra nunca são registrados. |
11. Relacionamento com o resto do gateway
| Superfície | Como se compõe com o Firewall? |
|---|---|
| Guardrails | Planos complementares. Os Guardrails filtram o texto de prompt/response; o Firewall governa as ações de ferramenta. Ambos podem se aplicar a uma requisição. Os níveis de autonomia configuram os dois de uma vez. |
| Roteamento | Independente. O roteamento escolhe o modelo/canal; o firewall julga as chamadas de ferramenta independentemente de qual modelo as atendeu. |
| Chaves de API | Uma chave se vincula a uma política via firewall_policy_id; o vínculo vive na chave dentro do gateway. Nenhum vínculo cai de volta para o padrão do workspace. |
| Gateway MCP | O firewall é o gateway MCP — cada servidor que você registra despacha seu tools/call através do motor. |
| Skills | O modo de enforcement de uma skill governada anda por cima do veredito da regra, então uma skill em quarentena é retida mesmo se nenhuma regra nomear suas ferramentas. |
12. Conectando um agente ao gateway do Firewall
Há duas maneiras de uma chamada de ferramenta chegar ao motor:- Gateway MCP — aponte seu cliente MCP (Claude Desktop, Cursor, um
framework de agente) para
https://api.orcarouter.ai/api/v1/firewall/mcp. O gateway expõe as ferramentas de cada servidor registrado alcançável, com namespace<server>.<tool>, e avalia cadatools/callinline. Veja Servidores MCP. - Hook de avaliação — chame
POST /api/v1/firewall/evaluatea partir do seu próprio loop de agente antes de despachar uma chamada de ferramenta, e aja sobre o veredito.
403 nessas rotas.
13. Referência da API
Todas as rotas do console têm escopo de workspace via o contexto de workspace e aplicam RBAC de maneira consistente: leituras e os sandboxes de test/simulate são abertos a cada membro; escritas exigem Developer+.Políticas & configurações
| Método & path | Papel | Propósito |
|---|---|---|
GET /api/workspace/firewall/settings | Member | Lê as configurações de firewall do workspace (observe mode, padrões). |
PUT /api/workspace/firewall/settings | Developer+ | Atualiza configurações. |
GET /api/workspace/firewall/policies | Member | Lista políticas (com contagens de regra + chaves vinculadas). |
GET /api/workspace/firewall/policies/:id | Member | Detalhe de uma única política. |
POST /api/workspace/firewall/policies | Developer+ | Cria uma política. |
PUT /api/workspace/firewall/policies | Developer+ | Atualiza uma política. |
DELETE /api/workspace/firewall/policies/:id | Developer+ | Deleta uma política (409 se chaves ainda estiverem vinculadas). |
Postura, presets & sandboxes
| Método & path | Papel | Propósito |
|---|---|---|
GET /api/workspace/firewall/presets | Member | Presets de regra embutidos. |
POST /api/workspace/firewall/autonomy | Developer+ | Aplica um nível de autonomia. |
POST /api/workspace/firewall/autonomy/undo/:audit_id | Developer+ | Desfaz uma mudança de autonomia. |
GET /api/workspace/firewall/simulate | Member | Pré-visualiza um nível de autonomia (?level=). |
POST /api/workspace/firewall/test | Developer+ | Dry-run de uma política contra uma chamada de ferramenta de amostra. |
Observabilidade
| Método & path | Papel | Propósito |
|---|---|---|
GET /api/workspace/firewall/discovered-tools | Member | Ferramentas vistas, marcadas covered / gap. |
GET /api/workspace/firewall/events | Developer+ | Lista eventos de firewall (filtrável). |
GET /api/workspace/firewall/events/by-request/:request_id | Developer+ | Eventos de uma requisição. |
GET /api/workspace/firewall/events/aggregate | Developer+ | Rollup de runs / sessions. |
GET /api/workspace/firewall/trace/by-run | Developer+ | Nós de trace de uma run (?run_id=). |
GET /api/workspace/firewall/anomalies | Member | Feed de anomalias (?window=). |
POST /api/workspace/firewall/anomalies/snooze | Developer+ | Dá snooze no feed de anomalias. |
Gateway (machine-to-machine)
Estas rodam em um token com escopo de firewall-gateway, não na sessão do console:| Método & path | Propósito |
|---|---|
POST /api/v1/firewall/evaluate | Veredito pré-dispatch para uma chamada de ferramenta. |
POST /api/v1/firewall/evaluate_plan | Verificação pré-execução para um plano de múltiplos passos. |
ANY /api/v1/firewall/mcp | O endpoint unificado do gateway MCP. |
GET /api/v1/firewall/approvals/:id | Consulta o estado de aprovação de uma chamada retida. |
POST /api/v1/firewall/approvals/:id/callback | Callback de aprovação assinado por HMAC. |
14. FAQ
E se nenhuma política for resolvida em uma chamada de ferramenta?
E se nenhuma política for resolvida em uma chamada de ferramenta?
Com o observe mode desligado, o comportamento é byte-idêntico ao de
um workspace que nunca habilitou o recurso — nada é bloqueado ou
registrado. Com o observe mode ligado, a chamada é permitida mas
registrada como um gap de cobertura, de modo que aparece em Discovered
tools.
Como faço o rollout de uma política com segurança?
Como faço o rollout de uma política com segurança?
Ligue o shadow mode. A política 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 as
visões de events e runs, confirme que ela dispara no que você espera e
em nada que você não espera, depois desligue o shadow mode para começar
a aplicar.Uma chamada de ferramenta bloqueada custa cota?
Uma chamada de ferramenta bloqueada custa cota?
Um block inbound dispara antes da chamada ao modelo upstream, então não
custa tokens de modelo. Vereditos audit / allow não alteram o billing.
Uma regra
cap_cost é, ela mesma, um controle de billing — ela nega
assim que o gasto da run cruza seu limite em centavos.Firewall ou Guardrails — qual eu uso?
Firewall ou Guardrails — qual eu uso?
Ambos, para camadas diferentes. Os Guardrails filtram o texto em
prompts e respostas (PII, segredos, jailbreaks). O Firewall governa
as ações que um agente toma (quais ferramentas, quais servidores MCP,
quais hosts). Uma requisição pode passar por ambos. O nível de autonomia
tight configura os dois juntos.O enforcement é garantido para cada ferramenta que um agente roda?
O enforcement é garantido para cada ferramenta que um agente roda?
O Firewall aplica enforcement nas chamadas de ferramenta que cruzam o
gateway — o caminho de relay, o gateway MCP e o hook de avaliação. Uma
ferramenta que seu agente executa inteiramente dentro de seu próprio
processo, nunca tocando o gateway, está fora da visão do firewall. O
objetivo de design é tornar o gateway o único caminho auditado para as
chamadas que importam (ferramentas mediadas por modelo, dispatch de MCP,
egress de rede); roteie-as por ele e elas estão governadas.
Veja também
Aprofundando-se em segurança de agentes? Os guias Proteja seus agentes (Zero Trust) colocam este recurso em um fluxo de trabalho zero-trust.Proteja seus agentes (Zero Trust)
O manual do firewall de agentes zero-trust — listas de permissão de ferramentas, verificações de argumentos e controle de egress.
Baseline de Agentes Seguros
Um único interruptor que define juntas as posturas do seu Firewall e dos seus Guardrails.