tool_name_glob avaliadas na
superfície mcp.
Cada tools/call que cruza o gateway MCP roda
através da sua política de firewall antes de chegar
ao servidor real. Então a lista de permissão não é apenas consultiva — uma
chamada a uma ferramenta que você não permitiu nunca despacha.
Editar política é uma ação de console. As rotas
/api/workspace/firewall/* autenticam com seu session / access token, não com
uma chave de relay sk-orca-…. Escrever regras exige o papel de Developer+;
qualquer membro do workspace (até Viewer) pode ler políticas e o feed de
ferramentas descobertas.1. Por que uma lista de permissão default-deny para ferramentas mcp seguras
Uma lista de negação — “bloqueie as ferramentas perigosas” — falha no momento em que um servidor adiciona uma nova ferramenta, renomeia uma, ou você conecta um segundo servidor. O conjunto de ferramentas perigosas é aberto; o conjunto que você pretendeu usar é pequeno e conhecido. Uma lista de permissão inverte o padrão de modo que o desconhecido é recusado, não admitido:- Novas ferramentas são negadas por padrão. Um servidor que cresce uma
ferramenta
delete_repodepois que você o conectou não pode ser chamado até você adicioná-la à lista de permissão. - O escopo é por servidor. O namespace
<server>.<tool>permite que você permitagithub.create_issueenquanto nega tudo o mais sobgithub.*. - Um ponto de estrangulamento. A mesma política governa o servidor empacotado e cada servidor BYO atrás do gateway, então há um lugar para ler a lista de permissão.
2. As duas peças
Uma lista de permissão é umdefault_verdict mais um conjunto ordenado de
regras.
default_verdict: deny
O fallback da política para qualquer
tools/call que nenhuma regra
corresponde. Defina-o como deny e qualquer coisa que você não permitiu
explicitamente é bloqueada. (Ele também aceita allow e audit — audit
é o padrão.)regras de allow
Uma regra por ferramenta (ou por glob). Cada uma carrega um
tool_name_glob e um veredito de allow. Um tools/call que corresponde
ao glob resolve para allow e despacha; tudo o mais cai para o padrão
deny.github.create_issue, shell.exec. * corresponde a qualquer ferramenta
(use-o com parcimônia; uma regra de allow com * desfaz toda a lista de
permissão). Um <server>. inicial escopa o glob a um servidor.
3. Um exemplo concreto
Você conectou um servidorgithub e só quer que os agentes leiam e abram
issues — nunca deletem ou administrem nada. No console, abra
Firewall → Policies, defina o veredito padrão da política como deny, e
adicione duas regras de allow:
| Ordem | tool_name_glob | Veredito |
|---|---|---|
| 1 | github.create_issue | allow |
| 2 | github.list_issues | allow |
deny:
github.create_issue→ corresponde à regra 1 → allow, despacha.github.delete_repo→ não corresponde a nada → deny por padrão.
firewall deny: …) — o mesmo formato que qualquer ferramenta que falha
retorna — de modo que o agente pode se adaptar em vez de quebrar. (Na
superfície inbound um deny é em vez disso um HTTP 400 com código de erro
firewall_blocked.)
4. Apertando com argumentos
Um nome de ferramenta na lista de permissão ainda pode ser chamado com argumentos ruins. Estreite ainda mais adicionando uma cláusulaargs_match
(JSONPath + um operador como eq, contains, regex, in ou cidr_match)
à regra, ou em camadas com uma regra deny acima do allow para um formato de
argumento específico — por exemplo, permita github.create_issue mas faça
deny quando o repo alvo não estiver em uma lista aprovada. Veja a
referência de regras do firewall para o conjunto
completo de operadores.
sanitize redige os argumentos de uma chamada de ferramenta antes de
encaminhar — ele nunca toca o que uma ferramenta retorna. Para aparar
conteúdo retornado, isso é um controle diferente; veja
sanitize de saída de ferramenta.5. Faça rollout com segurança
Vire um default-deny de servidor inteiro em produção e você arrisca quebrar um agente que silenciosamente dependia de uma ferramenta que você esqueceu. Duas configurações reduzem o risco:shadow_mode — veja denies sem enforcing
shadow_mode — veja denies sem enforcing
Um flag por política que rebaixa vereditos de enforcing para
audit. Seu
padrão deny e regras de deny registram [shadow] would deny … em vez de
bloquear, de modo que você pode validar a lista de permissão contra
tráfego real antes que ela morda. Leia mais em
modos de enforcement.observe mode — exponha as ferramentas que você perdeu
observe mode — exponha as ferramentas que você perdeu
Uma configuração de workspace que registra cada chamada não coberta como
uma lacuna no feed de
Ferramentas Descobertas. Rode-a antes de
escrever a lista de permissão para aprender exatamente quais ferramentas
seus agentes chamam, depois promova cada uma em uma regra de allow
explícita.
shadow_mode e a lista de permissão enforça.
6. Verifique que funciona
Depois de enforcing, confirme que as ferramentas negadas de fato são recusadas:- Dry-run um
tools/callcontra a política (Developer+) para ver o veredito e qual regra — ou o padrão — o produziu, sem enviar tráfego real. Passe um nome de ferramenta, superfície e args de amostra; o motor os avalia e retorna o trace do veredito sem registrar um evento. - Observe os eventos. Cada chamada bloqueada registra um evento de firewall que um Developer+ pode ler no console; a página de eventos de auditoria cobre o feed e seus campos.
Relacionados
Conectar um servidor MCP
Registre um servidor antes de poder fazer lista de permissão de suas
ferramentas.
Firewall: Servidores MCP
O comportamento de runtime do gateway e os vereditos por chamada.
Referência de regras do firewall
O DSL completo de regras — globs, args_match, egress, sanitize.
Chamadas de ferramenta perigosas
A ameaça que uma lista de permissão é construída para conter.
Limites de egress
Governe onde uma ferramenta permitida pode alcançar.
Guardrails vs. firewall
Quando recorrer à política de conteúdo vs. política de ferramenta.