Saltar para o conteúdo principal
Quando você lê um evento de firewall ou um match de guardrail, a linha lhe diz o que o gateway decidiu — deny, sanitize, [EMAIL]. Esta página é a tabela de consulta para essas palavras: o que cada uma significa, o que ela faz com a chamada e para onde ir para a mecânica completa. Mantenha-a aberta enquanto cria regras ou faz triagem do feed de eventos. Dois planos de controle produzem dois vocabulários. O Firewall governa ações de ferramenta e emite um veredito. Os Guardrails filtram o texto de prompt e resposta e emitem uma ação mais, em uma máscara, uma tag de mascaramento tipada. Eles nunca compartilham uma palavra — um guardrail nunca diz deny, um firewall nunca diz mask.
Este é um índice de referência, não um how-to. Para o caso de uso por trás de cada controle, veja Guardrails vs Firewall; para os corpos HTTP, veja Códigos de erro de segurança.

​
1. O glossário de vereditos de firewall

Uma regra de firewall (ou o default_verdict da política) resolve cada chamada de ferramenta para exatamente um destes seis vereditos. O motor percorre as regras em ordem de prioridade, a primeira correspondência vence, e cai de volta para o padrão se nada corresponder.
A chamada prossegue para a ferramenta. Ainda registrada como um evento de firewall, então aparece em Runs e no feed de eventos. É o que você quer para ferramentas que um agente é explicitamente confiado a usar.
Tráfego idêntico ao de allow, mas marcado como algo que você queria observar. É o default_verdict recomendado: observe tudo, bloqueie nada, até suas regras estarem ajustadas. O nível de autonomia balanced traz o guardrail PII Shield como apenas-flag (audit), então a PII é registrada sem reter a chamada.
A chamada nunca chega à ferramenta. Na superfície inbound isso retorna HTTP 400 firewall_blocked; através do gateway MCP volta como um erro de ferramenta (firewall deny: <reason>) para que o modelo possa reagir em vez de quebrar. Marcado skip-retry. Não custa nenhum token de modelo.
Substitui substrings correspondentes (segredos, PII) nos argumentos da chamada de ferramenta por um token [redacted:<preset>], depois encaminha a chamada com os argumentos limpos. Ele redige apenas argumentos — nunca o conteúdo que uma ferramenta retorna. Na superfície inbound, onde ainda não há argumentos em tempo de chamada, sanitize escala para um deny.
A chamada é enfileirada para revisão e o agente recebe uma resposta retida carregando um id de aprovação (HTTP 400 firewall_approval_pending). Um revisor a resolve no console ou via um callback de webhook HMAC; o agente consulta o id e reenvia uma vez com um header de aprovação de uso único. Veja Aprovação humana.
Criado como uma regra com um teto por regra em centavos. Resolve para allow enquanto a run do agente está dentro do orçamento e para deny assim que o gasto acumulado cruza o limite — então um evento mostra allow ou deny, não a palavra literal cap_cost. Um disjuntor para loops descontrolados.
No shadow mode, deny / sanitize / pending_approval são todos rebaixados para audit e o motivo recebe o prefixo [shadow] would …. O evento registra o veredito que teria disparado, mas o tráfego não é alterado — esse é o objetivo central de um rollout seguro.

​
Veredito padrão

default_verdict aceita apenas os três vereditos não-interativos:
ValorSignificado quando nenhuma regra corresponde
allowPermite chamadas de ferramenta não cobertas silenciosamente.
auditPermite mas registra — o padrão.
denyBloqueia qualquer coisa que nenhuma regra permita explicitamente (postura default-deny).
O nível de autonomia tight define default_verdict: deny; balanced e o padrão entregue usam audit.

​
2. Ações de guardrail

Uma regra de guardrail dispara uma de cinco ações. Elas são o equivalente em plano de texto dos vereditos — e uma regra de guardrail nunca produz um veredito de firewall.
AçãoO que fazCota
blockRejeita a requisição inteira com HTTP 400 guardrail_blocked.Nenhuma — bloqueios de entrada disparam antes da medição; bloqueios de saída reembolsam.
maskRedige cada correspondência para uma tag tipada (veja §3) e encaminha o texto limpo.Normal — a chamada prossegue.
flagApenas registra. Registra uma correspondência; não altera nada no tráfego.Normal.
annotateNão-bloqueante. Anexa uma nota legível por humanos à requisição (injetada upstream como um aviso de segurança) sem mascarar ou bloquear o texto.Normal.
spotlightNão-bloqueante. Envolve o texto (não confiável) correspondente em delimitadores e diz ao modelo para tratar a região delimitada como dado, nunca instruções — a defesa de “spotlighting” contra injeção de prompt.Normal.
Uma requisição de guardrail bloqueada é marcada skip-retry — reexecutar o mesmo prompt contra outro canal apenas bloquearia de novo.
Use flag para medir uma nova regra contra tráfego real antes de mudá-la para block ou mask. O feed de Matches mostra o que teria sido pego com zero impacto no tráfego — o equivalente de guardrail ao shadow mode do firewall.
Uma única regra pii pode aplicar ações diferentes a entidades diferentes com entity_actions — mascarar e-mails e telefones, mas bloquear em credit_card e ssn, a partir de uma regra. As chaves devem ser uma entidade habilitada na regra; os valores devem ser block / mask / flag / annotate.

​
3. O glossário de tags de mascaramento

Em uma ação mask, cada entidade correspondente é substituída inline por uma tag tipada — [<NOME_DA_ENTIDADE_EM_MAIUSCULAS>] — de modo que o modelo (estágio de entrada) ou o chamador (estágio de saída) vê o formato do dado sem o valor. O mascaramento roda em ambos os estágios, incluindo respostas em streaming: um scanner de stream ciente de tokens mascara correspondências que cruzam fronteiras de chunk antes que cheguem ao cliente.
EntidadeTag
email[EMAIL]
phone[PHONE]
credit_card[CREDIT_CARD]
ssn[SSN]
ip[IP]
iban[IBAN]
mac_address[MAC_ADDRESS]
jwt[JWT]
aws_access_key[AWS_ACCESS_KEY]
api_key_openai[API_KEY_OPENAI]
bitcoin_address[BITCOIN_ADDRESS]
Três identificadores regionais vêm por cima do conjunto base:
EntidadeTagRegião
jp_mynumber[JP_MYNUMBER]Japão
kr_rrn[KR_RRN]Coreia do Sul
cn_resident_id[CN_RESIDENT_ID]China
Entidades personalizadas seguem a mesma convenção. Uma entidade personalizada chamada employee_id mascara para [EMPLOYEE_ID] a menos que você defina uma substituição mask_with explícita. Até 25 entidades personalizadas por regra, cada uma uma regex RE2 com um checksum luhn opcional. Veja Detecção de PII.

​
4. Um exemplo trabalhado

Uma única chamada de ferramenta db.query, lida de cima a baixo, toca ambos os vocabulários: 
firewall verdict : sanitize        # secret stripped from the SQL argument
guardrail action : mask            # an email in the prompt redacted
masking tag      : [EMAIL]         # what the model actually receives
O sanitize do firewall limpou os argumentos da ferramenta; o mask do guardrail limpou o texto do prompt; a tag [EMAIL] é o que o modelo vê no lugar do endereço. Mesma requisição, três camadas diferentes, três palavras deste glossário.

​
5. Palavras de postura que você verá ao lado dos vereditos

Estas não são vereditos nem ações, mas decidem se um veredito é aplicado de todo — então aparecem nas mesmas visões de eventos e settings.
PalavraPlanoSignificado
Shadow modeFirewallFlag por política. Rebaixa todo veredito de enforcement para audit, prefixa o motivo com [shadow] would ….
Observe modeFirewallConfiguração de workspace. Quando nenhuma política resolve, permite a chamada mas a registra como um gap de cobertura (Discovered tools).
EnforceFirewallShadow desligado + uma política vinculada: os vereditos entram em vigor.
Fail-openGuardrailsPadrão para regras avançadas (llm_judge, grounding, external) — um timeout é observado, a requisição continua. Mude para fail-closed por regra.
Log raw contentGuardrailsDesligado por padrão. Quando desligado, uma correspondência registra que uma regra disparou mas não a substring correspondente.
Para a distinção deny-vs-audit-vs-shadow em profundidade, veja Modos de enforcement.

​
6. Onde cada palavra é definida

SuperfícieVocabulárioPágina inicial
Política de firewallallow audit deny sanitize pending_approval cap_costFirewall
Correspondência de regra de firewalltool_name_glob, args_match, egress, sequenceRegras de firewall
Regra de guardrailblock mask flag annotate spotlightGuardrails
PII de guardrailnomes de entidade + tags de mascaramentoGuardrails
MCP & skillsbandas de risco de skill, modos quarantine / blockFirewall MCP, Firewall skills
Corpos de erro HTTPguardrail_blocked, firewall_blocked, firewall_approval_pendingCódigos de erro
Todo termo aqui também aparece no Glossário de conceitos mais amplo, que adiciona termos de identidade, escopo e ameaça. Esta página é a fatia estreita e focada em decisão — apenas vereditos, ações e tags de mascaramento.

​
7. Leitura relacionada

Por que isto foi bloqueado?

Rastreie uma única chamada negada de volta à regra e veredito exatos que a interromperam.

Modos de enforcement

Como audit, shadow, observe e enforce se relacionam — e como fazer rollout com segurança.

Guardrails vs Firewall

Qual plano detém qual decisão, e por que uma requisição pode passar por ambos.

Chamadas de ferramenta perigosas

A ameaça que os vereditos deny e sanitize existem para interromper.