Vai al contenuto principale
Qualsiasi prompt che la tua app invia a un modello può portare con sé dati personali che non dovrebbe — un’email incollata in un ticket di supporto, un SSN in una nota CRM, un numero di carta che un utente ha digitato in una chat. Una volta che quel testo raggiunge un provider upstream è fuori dal tuo controllo: loggato, messo in cache, magari usato per l’addestramento. Anche la risposta del modello può far trapelare PII di ritorno, riecheggiando o inferendo dettagli che poi finiscono nei log della tua applicazione. Questa pagina mostra come fermare una fuga di PII verso l’LLM al gateway con un guardrail PII — una regola con scope a livello di workspace che maschera o blocca le entità sensibili sulla richiesta prima ancora che il modello le veda. È il corrispettivo a livello di contenuto dell’Agent Firewall, e non richiede alcuna modifica al codice della tua applicazione.
Un guardrail PII filtra il testo di prompt e risposte. Per governare le azioni che un agent compie con i dati — tool di fetch, host di egress — vedi Esfiltrazione di dati. I due piani si compongono; la maggior parte dei team li usa entrambi.

​
1. Come avviene l’esposizione

Le PII raggiungono un provider upstream attraverso traffico ordinario e ben intenzionato:
  • Un utente incolla i propri contatti in una chat e la tua app inoltra l’intero messaggio alla lettera.
  • Una pipeline RAG recupera un documento contenente record di clienti e lo inserisce nel prompt come contesto.
  • Un agent legge una riga di database e include campi grezzi in un argomento di un tool o in un prompt successivo.
  • La risposta del modello riformula o inferisce PII, che la tua app poi scrive nei propri log.
Nessuno di questi è un attacco — sono la forma normale delle app LLM. La soluzione è una policy che filtra ogni richiesta e risposta in un unico punto di strozzatura, invece di sottoporre ad audit ogni punto di chiamata nel tuo codice.

​
2. Difenditi dalla fuga di PII verso l’LLM con un guardrail PII

Un guardrail è una policy di contenuto nominata, con scope a livello di workspace. Una regola pii al suo interno rileva le entità sensibili e applica una azione a ciascun match:
AzioneEffetto
maskSostituisce ogni match con un tag tipizzato — jane@acme.com → [EMAIL] — e inoltra il testo ripulito. Il modello non vede mai l’originale.
blockRifiuta l’intera richiesta con HTTP 400 guardrail_blocked. Da usare quando le PII non devono mai raggiungere il provider.
flagNon cambia nulla del traffico; registra un match. Misura l’esposizione prima di applicare.
Il set di rilevatori è integrato e deterministico — puro pattern matching, nessuna chiamata di rete, sicuro sul percorso caldo. Entità integrate: email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address, più gli identificatori regionali con checksum jp_mynumber, kr_rrn e cn_resident_id. Su un’azione mask ogni match viene reso come il suo tag tipizzato — [EMAIL], [SSN], [CREDIT_CARD] e così via — così la struttura del prompt sopravvive mentre il valore scompare.
Ti serve un rilevatore non integrato (un ID dipendente interno, un numero di account)? Aggiungi un’entità custom — una regex con checksum Luhn opzionale, fino a 25 per regola — proprio accanto a quelle integrate. Vedi il riferimento Guardrails.

​
3. Esempio concreto — mascherare le PII sulla richiesta

L’avvio più rapido è il preset PII Shield: una singola regola pii che maschera email, phone, ssn, credit_card e ip. Configuralo nella console — nessuna modifica al codice, nessuna chiave in questo passaggio.
1

Crea il guardrail

Nella console, apri Guardrails e clicca New guardrail. Scegli il preset PII Shield dalla categoria pii, oppure scrivi a mano una regola pii con azione mask sulle entità sopra. Salva. (Le scritture richiedono il ruolo Developer o superiore.)
2

Verificalo nella sandbox

Apri il tab Test, incolla “reply to jane@acme.com”, scegli lo stage input ed esegui. La sandbox restituisce reply to [EMAIL] — localmente, senza chiamata upstream e senza consumo di quota.
3

Collegalo a una chiave

In API Keys, modifica una chiave e seleziona il guardrail dal menu a tendina Guardrail, oppure imposta il guardrail come default del workspace così ogni chiave non collegata lo eredita. Il binding vive sulla chiave nel gateway.
4

Chiama il gateway come al solito

Usando quella chiave, la tua chiamata di relay è invariata:
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": "Draft a reply to jane@acme.com"}
    ]
  }'
Il gateway riscrive l’email in [EMAIL] prima di inoltrare. Il modello upstream non riceve mai l’indirizzo.
PII Shield è una regola sullo stage both, ma il masking live in fase di richiesta è ciò che è disponibile oggi — il gateway maschera il prompt prima che parta per il modello. Il masking in fase di output (response) sul relay live è in roadmap. Per verificare come si comporta una regola in fase di response, valutala nel tab Test. Per lo streaming, vedi §5.

​
4. Maschera la maggior parte, blocca il peggio — override per entità

Una singola regola può applicare azioni diverse a entità diverse tramite entity_actions. Maschera gli identificatori a basso rischio ma blocca in modo netto le entità che non vuoi mai inoltrare — una regola invece di tre sovrapposte: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
Qui email, telefoni e IP vengono mascherati e passano; un prompt che porta un numero di carta o un SSN viene invece rifiutato con HTTP 400 guardrail_blocked. Una richiesta bloccata non costa quota — un block in fase di input scatta prima della contabilizzazione — ed è marcata skip-retry. Ogni chiave di entity_actions deve essere un’entità dichiarata sulla regola (integrata o custom); la sua azione viene validata rispetto al set di azioni della regola.

​
5. Cosa funziona oggi sullo streaming

Azione e stage interagiscono con lo streaming in modo diverso — conosci la matrice prima di farci affidamento:
Completamente live. Il prompt viene filtrato prima della chiamata upstream, quindi masking e blocking funzionano in modo identico sia che la risposta sia in streaming sia che non lo sia. È la superficie che PII Shield applica oggi.
Applicato sia sulle risposte in streaming sia su quelle non in streaming. Su uno stream, uno scanner interrompe lo stream a metà ed emette un messaggio sostitutivo prima che qualsiasi contenuto bloccato raggiunga il client; un block di output rimborsa la quota pre-consumata.
Attualmente solo non-streaming. Su una risposta in streaming il chunk originale passa non mascherato — la riscrittura in-band dello stream è un miglioramento pianificato. Per il masking delle risposte oggi, usa richieste non-streaming, oppure affidati al masking in fase di input. Verifica prima la tua esatta combinazione stage/stream nel tab Test.

​
6. Vedi cosa è stato catturato

Ogni regola che scatta registra un match — il suo tipo, l’azione, lo stage e una stringa di dettaglio — visibile sul feed Matches del workspace (GET /api/guardrail/match, aperto a ogni membro). Da lì puoi raggruppare, filtrare, esportare in CSV e marcare i falsi positivi.
I valori grezzi non vengono loggati di default. Il toggle Log raw content di un guardrail è disattivato — la postura conservativa per la privacy — quindi il feed Matches registra che una regola PII è scattata e quale entità, ma non la sottostringa corrispondente (l’indirizzo email stesso). Attivalo per singolo guardrail solo quando ti serve il valore per il triage; l’impostazione non è retroattiva. Catturare PII nella tua stessa traccia di audit per fare il debug di una fuga di PII sarebbe controproducente.

​
7. Vai oltre

Per controlli completi di residenza, retention e diritto alla cancellazione — inclusa l’installazione di un compliance pack che materializza questi guardrail per GDPR, HIPAA o PCI DSS — parti dalle pagine di riferimento qui sotto.

Riferimento Guardrails

Ogni tipo di regola, stage, azione, entità custom, versioning e l’eval harness — il riferimento approfondito dietro questa pagina.

Fuga di segreti

Il fratello a forma di credenziale — token AWS, OpenAI, GitHub — catturato dal guardrail Secrets Blocker.

Output non sicuro

Filtrare ciò che il modello rimanda indietro, non solo ciò che riceve.

Guardrails vs Firewall

Quando filtrare il testo e quando governare le azioni — e perché di solito li vuoi entrambi.