Vai al contenuto principale
Un guardrail troppo zelante è peggio di nessun guardrail — il tuo team impara a ignorare il feed dei Matches, oppure allenti la regola e perdi la cattura che volevi davvero. OrcaRouter ti dà una via di mezzo precisa: segna un singolo match come falso positivo, e il motore ricorda quel finding e lo salta sulle richieste future — senza toccare la regola, allentare il pattern o mettere in produzione una modifica all’SDK. Questa è una landing focalizzata sul workflow dei falsi positivi. Per il motore di guardrail completo — ogni tipo di regola, campo e rotta — vedi il riferimento Guardrails.
Ogni passaggio qui è un’azione di console sul gateway gestito (api.orcarouter.ai). Tri i match sotto la tua sessione; solo la chiamata /v1/* finale usa una chiave di relay sk-orca-.... Segnare un match come falso positivo richiede il ruolo Admin del workspace; leggere il feed dei Matches e l’elenco di soppressioni risultante è aperto a ogni member.

​
1. Riduci i falsi positivi dei guardrail senza indebolire la regola

L’istinto quando una regola scatta troppo è allentarla — allargare un’esclusione regex, rimuovere un’entità, portare block su flag. Questo scambia un falso positivo con un buco nella policy. La soppressione mark-false-positive è l’alternativa chirurgica:

Sopprimi un finding

Silenzia il match esatto che ha mancato il bersaglio — una sottostringa specifica sotto una regola specifica — non l’intera regola. Il successivo hit genuinamente sensibile scatta comunque.

Nessuna modifica alla regola, nessun redeploy

La soppressione vive nel gateway come memoria del workspace. La regola resta esattamente come scritta; la tua app continua a chiamare /v1/* invariata.

Memoria a livello di workspace

Un Admin la segna una volta; la soppressione è deduplicata nel workspace, così il traffico di ogni membro ne beneficia — nessun fan-out per chiave.

Reversibile

Desegna il match (o elimina la soppressione) e il finding scatta di nuovo alla richiesta successiva. Nulla viene distrutto.
La soppressione è per un finding che hai giudicato benigno. Se un’intera regola è mal calibrata — forma sbagliata, stage sbagliato — correggi la regola e dimostralo nell’harness di eval anziché silenziare match dopo match.

​
2. Come un match diventa una soppressione

Ogni regola che scatta registra un match nel feed Matches del workspace — tipo di regola, azione, stage e una stringa di detail. Quando segni uno di quei match come falso positivo, il gateway deriva un fingerprint stabile per il finding e lo scrive nell’elenco di soppressioni del workspace. Su ogni richiesta futura, il motore controlla il fingerprint di ogni finding contro quell’elenco e salta uno soppresso prima che possa bloccare, mascherare o segnalare. Due tipi di finding producono un fingerprint:
Un finding CVE / SBOM è già fornito con un’identità stabile — l’identità dell’avviso o del componente viaggia con il finding. Sopprimerne uno silenzia quel CVE/componente esatto, e solo quello. Questo è il caso nativo per cui lo store di soppressioni è stato costruito.
Keyword, regex, PII e gli altri tipi di regola deterministici non portano un’identità propria, quindi il gateway ne sintetizza una da dati che sono identici sul lato di scrittura (il tuo clic mark-FP) e sul lato di applicazione (la richiesta successiva): il guardrail, l’identità di matching della regola e — quando la cattura grezza è attiva — le sottostringhe corrispondenti stesse.
La precisione del fingerprint sintetico dipende da Log raw content, che è disattivato per default. Con la cattura attiva, il fingerprint si basa sulla sottostringa corrispondente esatta, quindi sopprimere ORD-48291507 silenzia quel numero d’ordine e nient’altro. Con la cattura disattivata, non c’è sottostringa su cui basarsi, quindi la soppressione ripiega su un silenziamento a livello di regola — silenzia quell’unica regola (a quello stage) per il workspace. Il fallback non va mai oltre la regola da cui proviene. Vedi Logging e privacy.

​
3. Un esempio concreto

Supponi di eseguire una regola regex che maschera numeri d’ordine interni a forma di ORD- più otto cifre. Un ticket di supporto cita legittimamente ORD-48291507 in un modo che hai deciso vada bene far passare. Non vuoi indebolire la regola — vuoi solo che questo singolo numero smetta di scattare.
1

Apri il feed dei Matches

Nella console, apri Guardrails → Matches. Filtra per guardrail e tipo di regola per trovare la riga per l’hit ORD-48291507. (Per vedere la sottostringa letterale, Log raw content del guardrail deve essere stato attivo quando il match è stato registrato — è disattivato per default.)
2

Segnalo come falso positivo

Apri il dettaglio del match e scegli Mark as false positive. Come Admin del workspace, questo timbra il match e rispecchia una soppressione del workspace basata sul fingerprint del finding.
3

Conferma che è soppresso

Apri l’elenco Suppressions — la nuova voce appare, etichettata con il guardrail e la regola da cui proviene e il motivo “Marked as false positive from Matches”. Ogni membro del workspace può leggere questo elenco.
4

Invia di nuovo la stessa richiesta

Usando la tua chiave di relay, chiama OrcaRouter esattamente come prima — nessun nuovo header, nessuna modifica all’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?"}
    ]
  }'
Il finding soppresso viene saltato — ORD-48291507 passa — mentre qualsiasi altro numero d’ordine corrisponde comunque ed è mascherato come prima.

​
4. Soppressione vs. le alternative

La soppressione è uno dei quattro modi per silenziare una regola rumorosa. Scegli il più ristretto che si adatta:
ApproccioCosa cambiaQuando ricorrervi
Mark FPUn finding (o una regola, cattura disattivata)Un hit benigno specifico; la regola è altrimenti giusta
Modifica la regolaIl matching stessoForma/stage sbagliati — correggila, poi ri-valuta
Azione flagSolo osservazione, nessun bloccoUna nuova regola di cui non ti fidi ancora
Harness di evalNulla di attivo — misuraDimostrare la precisione prima di mettere in produzione
Non coprire una regola sistematicamente sbagliata segnando FP dopo FP. Se stai sopprimendo ripetutamente la stessa forma, la regola è mal calibrata — ancora la regex, restringi l’ elenco di keyword, o scegli un’ entità PII più stretta, e verifica con un’esecuzione di eval.

​
5. Inverti una soppressione

Nulla qui è a senso unico:
  • Desegna il match — la stessa azione Admin, invertita, rimuove il timbro FP del match e (quando nessun altro match segnato FP vi mappa ancora) elimina la soppressione. Il finding scatta di nuovo alla richiesta successiva.
  • Elimina la soppressione direttamente — dall’elenco Suppressions, un’azione Developer+ rimuove la voce. Stesso effetto: il finding è di nuovo attivo.
Poiché le soppressioni sono memoria del workspace, invertirne una ripristina la cattura per il traffico di ogni membro in una volta — come per il segnarla soppressa per tutti.

​
6. Superficie API

Queste sono rotte di console, autenticate dalla tua sessione — non da chiavi di relay. Gestisci a ruolo ogni azione: segnare un match FP è Admin; le letture di soppressione sono Member; le scritture di soppressione sono Developer+.
Metodo & pathRuoloScopo
GET /api/guardrail/matchMemberElenca i match da triare.
POST /api/guardrail/match/:id/mark-fpAdminSegna un match come falso positivo (rispecchia una soppressione).
DELETE /api/guardrail/match/:id/mark-fpAdminDesegna — ripristina il finding.
GET /api/guardrail/suppressionsMemberElenca le soppressioni attive del workspace.
POST /api/guardrail/suppressionsDeveloper+Aggiungi una soppressione direttamente.
DELETE /api/guardrail/suppressions/:idDeveloper+Rimuovi una soppressione.
Gli endpoint mark-FP sono rate-limited — sono un’azione di triage deliberata, a basso volume, non un’API bulk. Ricorri all’harness di eval, non a un loop di chiamate mark-FP, quando stai mettendo a punto un’intera policy.

​
7. Dove andare dopo

Feed dei match

Dove ogni regola scattata atterra — il posto da cui tri prima di segnare qualsiasi cosa.

Testing ed eval

Dimostra la precisione di una regola contro un corpus prima di metterla in produzione — la correzione sistematica quando la soppressione sta trattando un sintomo.

Logging e privacy

Come Log raw content controlla se la soppressione si basa sulla sottostringa esatta o ripiega su un silenziamento a livello di regola.

Riferimento Guardrails

Il motore completo — ogni tipo di regola, azione e rotta.
La soppressione governa i finding di contenuto. Per silenziare una regola rumorosa dell’agent firewall — un match di tool che hai giudicato sicuro — quella è una superficie separata; vedi il Firewall e il suo feed di anomalie. Per comprendere dove guardrails e firewall si dividono, leggi Guardrails vs Firewall.