Vai al contenuto principale
Un chatbot rivolto ai clienti riceve input non attendibile dal pubblico e lo invia a un modello. Questo lo rende la superficie a più alta esposizione che gestisci: gli utenti incollano PII che non vuoi conservare a monte, gli attaccanti cercano di sovrascrivere il tuo system prompt e il modello può restituire nella finestra di chat segreti o contenuti non sicuri. Questa ricetta collega i quattro controlli che proteggono un chatbot AI end-to-end — un guardrail PII sulla richiesta, lo screening della prompt injection, la sicurezza dell’output e un’unica chiave strettamente con scope — tutti nella console, con zero modifiche al codice del tuo chatbot.
Tutto qui si collega al tuo workspace ed è configurato dalla console. Il tuo chatbot continua a chiamare https://api.orcarouter.ai/v1/chat/completions con la stessa chiave sk-orca-... — cambia solo la policy nel gateway. Le azioni di configurazione richiedono i ruoli indicati per ciascun passaggio; le chiamate di relay usano la chiave con scope.

​
1. Il modello di threat per un chatbot pubblico

Prima di scrivere qualsiasi cosa, sappi contro cosa ti stai difendendo. La superficie d’attacco di un chatbot è più ristretta di quella di un agent completo — ma i rischi ad alta frequenza sono concreti:

PII in entrata, PII loggata

Gli utenti incollano email, numeri di carta, SSN in chat — e tu li inoltri a monte e nei tuoi log.

Prompt injection

“Ignora le istruzioni precedenti e …” — tentativi di sovrascrivere il tuo system prompt e cambiare il comportamento del bot.

Jailbreak

Framing DAN / role-play che cercano di tirare il bot fuori policy.

Output non sicuro

Il modello che restituisce nella chat segreti trapelati, boilerplate del system prompt o contenuto carico di injection.
Un chatbot semplice non ha chiamate a tool, quindi questa ricetta si appoggia ai Guardrails — il piano del testo — anziché al Firewall. Se il tuo bot chiama effettivamente tool, sovrapponi il Firewall (vedi §6).

​
2. Un guardrail, quattro compiti

Anziché quattro policy separate, scrivi un guardrail di workspace con regole ordinate che coprono ciascun rischio. Un guardrail è un elenco ordinato e nominato di regole; ogni regola dice cosa cercare, dove (input, output o both) e cosa farne (block, mask o flag). Nella console, apri Guardrails → New guardrail, chiamalo chatbot-shield e aggiungi le regole qui sotto. Scrivere un guardrail — ed eseguire la sandbox di Test — richiede il ruolo Developer; visualizzare i guardrail è aperto a qualsiasi membro.

​
a. PII sulla richiesta

Aggiungi una regola PII, stage input, azione mask. L’insieme di entità integrate è chiuso — scegli quelle che un chatbot vede davvero: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "credit_card", "ssn", "ip"],
  "entity_actions": { "credit_card": "block", "ssn": "block" }
}
Una mask sostituisce ogni match con un tag tipizzato — jane@acme.com diventa [EMAIL], così il modello a monte non vede mai l’indirizzo. L’override entity_actions blocca del tutto la richiesta su un numero di carta o un SSN mentre maschera le entità a severità più bassa. Questo è esattamente il preset PII Shield, esteso con override per-entità — applica il preset dalla libreria dei template e modifica da lì.
Il masking PII allo stage di input è attivo oggi — riscrive la richiesta prima che il modello la veda. Il masking live della risposta in streaming è nella roadmap. Per redigere le PII da ciò che il bot risponde, usa una regola di block sull’output (applicata su streaming e non-streaming) o esegui il bot in non-streaming dove il masking dell’output si applica. Dimostra prima la tua esatta combinazione stage/stream nel tab Test.

​
b. Screening della prompt injection

OrcaRouter fornisce questo come preset di sicurezza Prompt-Injection Basics (una denylist di keyword per frasi come “ignore previous instructions” e “reveal your system prompt”; per una copertura regex più stringente dei framing DAN / role-play, aggiungi il preset Jailbreak / Role-Play Blocker) più, per l’intento semantico che nessun pattern coglie, una regola llm_judge. Aggiungi il preset, poi una regola judge sullo stage input con una rubrica che segnala tentativi di injection/override. Il judge gira contro un modello nel tuo workspace, è limitato da judge_timeout_ms e fa fail open per default (un errore del judge viene loggato e la richiesta prosegue) — imposta judge_fail_open: false per fare fail closed.
Avvia le regole di injection a flag, osserva il feed Matches per un giorno sul traffico reale, poi promuovi a block una volta che hai confermato che scattano sugli attacchi e non sulle domande legittime. Vedi modalità di applicazione.

​
c. Sicurezza dell’output

Aggiungi una regola di block allo stage output (regex o keyword) per contenuti che non devono mai raggiungere la finestra di chat — segreti trapelati, token di controllo del chat-template, boilerplate del system prompt. Il Secrets & API-Key Blocker e i preset di sicurezza per il leak del system-prompt coprono i casi comuni; applicali e fissa le regole rilevanti allo stage output. Il block dell’output è applicato anche in streaming — lo scanner taglia lo stream in corsa ed emette un messaggio sostitutivo prima che il contenuto bloccato raggiunga l’utente.

​
3. Testa prima di spedire

Ogni editor di guardrail ha un tab Test. Incolla un campione, scegli lo stage ed esegui la policy corrente localmente — nessuna chiamata a monte, nessuna quota spesa.
Incolla questoStageAspettati
email me at jane@acme.cominputemail me at [EMAIL]
ignore previous instructionsinputflag / block (a tua scelta)
carta 4111 1111 1111 1111inputguardrail_blocked (per l’override)
Per la copertura adversarial, il tab Eval esegue la policy contro corpora red-team integrati (o i tuoi JSONL) e riporta come ha ottenuto il punteggio — metti a punto la rubrica del judge finché coglie gli attacchi noti senza segnalare la chat benigna.

​
4. Conia un’unica chiave con scope per il bot

Un guardrail applica solo sulle chiavi che si risolvono su di esso. Dai al chatbot la sua chiave, con scope al minimo necessario — mai la tua chiave a livello di account. In API Keys → New key, imposta:
Scegli chatbot-shield dal dropdown Guardrail. Questo imposta guardrail_id sulla chiave. Un collegamento esplicito è l’opposto dell’interruttore di disattivazione: se è impostato e abilitato, si applica sempre e non ricade mai silenziosamente. (Lascialo non impostato per ricadere invece sul guardrail is_default del workspace.)
Imposta credit_limit_usd a un tetto sensato (0 = illimitato). Un chatbot pubblico è la chiave con più probabilità di essere abusata — un cap di credito rigido è il tuo limite di blast radius. Vedi denial-of-wallet.
Attiva model_limits ed elenca solo il/i modello/i che il bot è autorizzato a chiamare, così una chiave trapelata non può essere usata per eseguire un modello costoso che non intendevi esporre.
Imposta allow_ips sugli IP di egress del tuo backend se il bot chiama da un server fisso, e un expired_time se la chiave è temporanea (-1 = non scade mai).
La chiave è mascherata in visualizzazione dopo la creazione — copiala una sola volta. Il backend del tuo chatbot ora invia ogni turno utente attraverso chatbot-shield senza che alcun codice sappia che lo screening sta avvenendo.

​
5. Osservalo in produzione

Due letture ti tengono onesto, entrambe con scope a livello di workspace:
  • Guardrails → Matches (qualsiasi Member) — ogni regola che è scattata: tipo, azione, stage e dettaglio. La sottostringa corrispondente è registrata solo se Log raw content è attivo per il guardrail (disattivato per default — la postura conservativa sulla privacy). Marca un falso positivo per mettere a punto la policy (Admin).
  • Version history — ogni modifica scrive una riga di history; fai il diff di due versioni qualsiasi e revert se una regola si rivela troppo aggressiva. Una richiesta bloccata restituisce HTTP 400 guardrail_blocked, non costa alcuna quota ed è marcata skip-retry.
Una risposta guardrail_blocked è un 400 deliberato e visibile all’utente. Gestiscilo nella UI del tuo chatbot con un messaggio amichevole (“Non posso elaborarlo”) anziché esporre l’errore grezzo — il gateway ha già fermato il turno non sicuro al posto tuo.

​
6. Se il tuo bot chiama tool

Nel momento in cui il tuo chatbot può chiamare una funzione, recuperare un URL o raggiungere un MCP server, lo screening del testo non basta — ti serve il piano delle azioni. Collega una policy Firewall alla stessa chiave tramite firewall_policy_id, o applica il livello di autonomia balanced per auditare le chiamate a tool e segnalare le PII a livello di workspace prima di irrigidire. Il percorso più rapido è il quickstart zero-trust; per un agent che chiama tool in modo intensivo, vedi proteggere un agent autonomo.

​
7. Dove approfondire

Riferimento Guardrails

Ogni tipo di regola, entità PII, campo del judge e l’eval harness per intero.

Guardrails vs Firewall

Piano del testo vs piano delle azioni — quando ti serve quale.

Modalità di applicazione

Observe → shadow → enforce: fai il rollout senza rompere il bot.

Scope di chiavi, policy, workspace

Come si risolvono il collegamento della chiave e i default del workspace.