Saltar para o conteúdo principal
Um guardrail ávido demais é pior que nenhum guardrail — seu time aprende a ignorar o feed de Matches, ou você afrouxa a regra e perde a captura que realmente queria. O OrcaRouter te dá um caminho do meio preciso: marque um único match como falso positivo, e o motor lembra aquela descoberta e a pula em requisições futuras — sem tocar na regra, sem afrouxar o padrão, sem publicar uma mudança de SDK. Este é um destino focado no fluxo de falso positivo. Para o motor de guardrail completo — cada tipo de regra, campo e rota — veja a referência de Guardrails.
Cada passo aqui é uma ação de console no gateway hospedado (api.orcarouter.ai). Você tria matches sob sua própria sessão; apenas a chamada final /v1/* usa uma chave de relay sk-orca-.... Marcar um match como falso positivo exige o papel Admin do workspace; ler o feed de Matches e a lista de supressão resultante está aberto a cada membro.

​
1. Reduza falsos positivos de guardrail sem enfraquecer a regra

O instinto quando uma regra dispara demais é afrouxá-la — ampliar uma exclusão de regex, remover uma entidade, virar block para flag. Isso troca um falso positivo por um buraco na política. A supressão por mark-false-positive é a alternativa cirúrgica:

Suprima uma descoberta

Silencie o match exato que disparou errado — uma substring específica sob uma regra específica — não a regra inteira. O próximo acerto genuinamente sensível ainda dispara.

Sem edição de regra, sem redeploy

A supressão vive no gateway como memória do workspace. A regra fica exatamente como escrita; sua app continua chamando /v1/* inalterada.

Memória de todo o workspace

Um Admin a marca uma vez; a supressão é deduplicada no workspace, então o tráfego de cada membro se beneficia — sem fan-out por chave.

Reversível

Desmarque o match (ou delete a supressão) e a descoberta dispara de novo na próxima requisição. Nada é destruído.
A supressão é para uma descoberta que você julgou benigna. Se uma regra inteira está mal calibrada — forma errada, estágio errado — corrija a regra e prove-a no Eval harness em vez de silenciar match após match.

​
2. Como um match vira uma supressão

Toda regra que dispara registra um match no feed de Matches do workspace — tipo de regra, ação, estágio e uma string de detalhe. Quando você marca um desses matches como falso positivo, o gateway deriva uma impressão digital estável para a descoberta e a escreve na lista de supressão do workspace. Em cada requisição futura, o motor verifica a impressão digital de cada descoberta contra essa lista e pula uma suprimida antes que ela possa bloquear, mascarar ou sinalizar. Dois tipos de descoberta produzem uma impressão digital:
Uma descoberta de CVE / SBOM já vem com uma identidade estável — a identidade do aviso ou componente viaja com a descoberta. Suprimir uma silencia aquele CVE/componente exato, e apenas aquele. Este é o caso nativo para o qual o armazenamento de supressão foi construído.
Keyword, regex, PII e os outros tipos de regra determinísticos não carregam uma identidade própria, então o gateway sintetiza uma a partir de dados que são idênticos no lado de escrita (seu clique de mark-FP) e no lado de enforcement (a próxima requisição): o guardrail, a identidade de correspondência da regra e — quando a captura bruta está ligada — as próprias substrings correspondentes.
A precisão da impressão digital sintética depende de Log raw content, que está desligado por padrão. Com a captura ligada, a impressão digital se baseia na substring correspondente exata, então suprimir ORD-48291507 silencia aquele número de pedido e nada mais. Com a captura desligada, não há substring para se basear, então a supressão cai para um silenciamento de nível de regra — ela silencia aquela uma regra (naquele estágio) para o workspace. O fallback nunca vai além da regra de onde veio. Veja Logging e privacidade.

​
3. Um exemplo concreto

Digamos que você roda uma regra regex que mascara números de pedido internos no formato ORD- mais oito dígitos. Um ticket de suporte legitimamente cita ORD-48291507 de uma forma que você decidiu que é aceitável deixar passar. Você não quer enfraquecer a regra — você só quer que este um número pare de disparar.
1

Abra o feed de Matches

No console, abra Guardrails → Matches. Filtre por guardrail e tipo de regra para encontrar a linha do acerto ORD-48291507. (Para ver a substring literal, o Log raw content do guardrail deve estar ligado quando o match foi registrado — está desligado por padrão.)
2

Marque-o como falso positivo

Abra o detalhe do match e escolha Mark as false positive. Como um Admin do workspace, isso carimba o match e espelha uma supressão do workspace baseada na impressão digital da descoberta.
3

Confirme que está suprimido

Abra a lista Suppressions — a nova entrada aparece, rotulada com o guardrail e a regra de onde veio e o motivo “Marked as false positive from Matches”. Cada membro do workspace pode ler esta lista.
4

Envie a mesma requisição de novo

Usando sua chave de relay, chame o OrcaRouter exatamente como antes — sem novos headers, sem mudança de SDK:
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Status of order ORD-48291507?"}
    ]
  }'
A descoberta suprimida é pulada — ORD-48291507 passa — enquanto qualquer outro número de pedido ainda corresponde e é mascarado como antes.

​
4. Suprimir vs. as alternativas

A supressão é uma de quatro formas de silenciar uma regra ruidosa. Escolha a mais estreita que se encaixa:
AbordagemO que ela mudaQuando recorrer a ela
Mark FPUma descoberta (ou uma regra, captura-desligada)Um acerto benigno específico; a regra está de resto certa
Editar a regraA correspondência em siForma/estágio errados — corrija, depois re-eval
Ação flagSomente observação, sem bloqueioUma nova regra em que você ainda não confia
Eval harnessNada ao vivo — medeProvar precisão antes de publicar
Não disfarce uma regra sistematicamente errada marcando FP após FP. Se você está suprimindo a mesma forma repetidamente, a regra está mal calibrada — ancore o regex, estreite a lista de keywords, ou escolha uma entidade PII mais apertada, e verifique com uma run de eval.

​
5. Reverter uma supressão

Nada aqui é de mão única:
  • Desmarcar o match — a mesma ação de Admin, revertida, remove o carimbo de FP do match e (quando nenhum outro match marcado como FP ainda mapeia para ele) derruba a supressão. A descoberta dispara de novo na próxima requisição.
  • Deletar a supressão diretamente — a partir da lista Suppressions, uma ação Developer+ remove a entrada. Mesmo efeito: a descoberta está ao vivo de novo.
Como as supressões são memória do workspace, reverter uma restaura a captura para o tráfego de cada membro de uma vez — igual a como marcá-la a suprime para todos.

​
6. Superfície de API

Estas são rotas de console, autenticadas pela sua sessão — não chaves de relay. Faça role-gate de cada ação: marcar um match FP é Admin; leituras de supressão são Member; escritas de supressão são Developer+.
Método e pathPapelPropósito
GET /api/guardrail/matchMemberLista matches para triar.
POST /api/guardrail/match/:id/mark-fpAdminMarca um match como falso positivo (espelha uma supressão).
DELETE /api/guardrail/match/:id/mark-fpAdminDesmarca — restaura a descoberta.
GET /api/guardrail/suppressionsMemberLista as supressões ativas do workspace.
POST /api/guardrail/suppressionsDeveloper+Adiciona uma supressão diretamente.
DELETE /api/guardrail/suppressions/:idDeveloper+Remove uma supressão.
Os endpoints de mark-FP são rate-limited — são uma ação de triagem deliberada, de baixo volume, não uma API em massa. Recorra ao Eval harness, não a um loop de chamadas de mark-FP, quando estiver ajustando uma política inteira.

​
7. Para onde ir a seguir

Feed de matches

Onde toda regra disparada cai — o lugar de onde você tria antes de marcar qualquer coisa.

Testes e eval

Prove a precisão de uma regra contra um corpus antes de publicá-la — a correção sistemática quando a supressão está tratando um sintoma.

Logging e privacidade

Como Log raw content controla se a supressão se baseia na substring exata ou cai para um silenciamento de nível de regra.

Referência de Guardrails

O motor completo — cada tipo de regra, ação e rota.
A supressão governa descobertas de conteúdo. Para silenciar uma regra ruidosa do agent firewall — uma correspondência de ferramenta que você julgou segura — essa é uma superfície separada; veja o Firewall e seu feed de anomalias. Para entender onde guardrails e o firewall se dividem, leia Guardrails vs Firewall.