Secret Guard e i gateway LLM locali: proteggere i segreti quando l'agente li usa

Un agente che fa lavoro serio non si limita a rispondere a domande: chiama tool, apre connessioni, interroga database. E per farlo gli servono segreti — chiavi API, token, credenziali. Il problema è che i segreti entrano nel contesto dell'agente, e da lì finiscono nel prompt inviato al modello.

Immagina un impiegato a cui consegni la chiave della cassaforte e poi lo lasci lavorare nel corridoio: la chiave resta nelle sue tasche, visibile a chiunque gli passi accanto. Il gateway locale fa l'opposto: il segreto resta sul tuo hardware, e al modello arriva solo una copia di prova che non vale nulla fuori da quella porta.

Come funziona il redact

Secret Guard (https://github.com/luochen1990/secret-guard) è un gateway in Rust, licenza MIT, che si mette tra il tuo agente e il provider. Due passaggi, uno per ogni direzione:

1. Redact in uscita: quando la richiesta passa dal gateway, ogni valore di segreto che trova viene sostituito con un mock realistico: stessa lunghezza, stesso charset. Per il modello un token API da 32 caratteri sembra un token API da 32 caratteri — il prompt non si rompe e la struttura che mantiene il prefix caching del provider resta intatta.
2. Restore in ingresso: la risposta passa di nuovo dal gateway, che riporta i mock ai valori reali. Se un tool call contiene un mock nelle sue argomentazioni, lo stesso avviene lì: l'agente riceve il valore utilizzabile senza che il modello l'abbia mai visto.

La mappa mock è deterministica e uno-a-uno: lo stesso segreto produce sempre lo stesso mock, e mock diversi non si sovrappongono mai. È la proprietà che preserva il prefix cache — se i mock saltassero a caso, ogni richiesta ricomincerebbe da zero.

Le quattro strategie per segreto

Ogni segreto registrato ha la sua policy, e qui sta il punto: non esiste «nascondi tutto», esiste la scelta per caso d'uso.

Strategia	Comportamento	Quando usarla
redact/restore (default)	Sostituisce in uscita, riporta in ingresso	Il tool ha bisogno del valore reale
reject	Restituisce 503 se il segreto è presente nella richiesta	Quel segreto non deve mai uscire, neppure mascherato
placeholder	Sostituisce con [REDACTED:{id}] e scatta un allarme canary se riappare	Vuoi solo capire se e dove circola
monitor	Passa tutto, logga gli attraversamenti	Audit, senza cambiare il comportamento

Protocolli supportati

Il gateway inoltra OpenAI Chat Completions, Anthropic, Gemini, Ollama e Responses. Il redact/restore completo funziona sui protocolli OpenAI, Anthropic e Responses, incluso il passaggio incrociato tra protocolli (streaming compreso). Gemini e Ollama oggi sono in pass-through byte-esatto: la redaction per loro è nella roadmap, e se un segreto sconosciuto passasse comunque in chiaro il gateway risponde 503 — il fallimento è chiuso, non silenzioso.

Setup in cinque passi

cargo install --git https://github.com/luochen1990/secret-guard
cd /opt/secret-guard
secret-guard register --name "stripe" --value "sk_live_xxx"
secret-guard run --port 18787

1. Installa il binario (serve rustc 1.96+; c'è anche il modulo NixOS services.secret-guard).
2. Registra i segreti con secret-guard register: finiscono in secret-guard.state.toml, in chiaro. Mettilo dove lo proteggi: è il file da gitignore e da backup crittografato.
3. Avvia il gateway: secret-guard run --port 18787. L'interfaccia web di gestione è su http://127.0.0.1:8787.
4. Punta il client al gateway: per Claude Code, imposta ANTHROPIC_BASE_URL=http://127.0.0.1:18787 e un ANTHROPIC_AUTH_TOKEN dummy — il gateway inoltra con le sue credenziali.
5. Verifica: chiedi al modello di ripetere una chiave registrata. Se funziona, risponde col mock — il valore reale non è nel contesto.

Se non va: la prima cosa da controllare è che il client punti davvero al gateway (un curl alla porta 18787), poi che il registro contenga il segreto — un segreto non registrato non viene mai intercettato, e l'opzionale suspect scanner (mai attivo di default) segnala solo valori sospetti, senza registrarli da solo.

E i limiti?

Sii onesto su cosa questo copre e cosa no:

• Il modello non vede mai il valore reale, ma può provare a farlo uscire con prompt injection o con un tool call costruito male: le strategie reject e placeholder esistono proprio per quei casi, a costo di blocco.
• Il file di stato è in chiaro: la protezione dipende da dove lo metti, non dal gateway.
• È una v0.1.0: le proprietà critiche (pass-through byte-esatto, reversibilità, determinismo, assenza di collisioni, routing multi-provider) sono coperte da test property-based ed end-to-end, ma la validazione sui provider reali di Anthropic, Gemini e Ollama è dichiarata come ancora da fare nella roadmap.
• Configurazione per segreto: non esiste auto-protection; registri tu cosa è un segreto, e per quello che non sai non lo sia, il suspect scanner è l'unico sentinella.

Il confronto con le alternative (LiteLLM, LLM Guard, PasteGuard) è nel repository, in docs/comparison.md, su sette dimensioni.

Il pattern da ricordare

L'idea non è una password più lunga: è un confine. Il segreto vive sul tuo hardware, il modello vede solo un'ombra realistica, e il valore reale attraversa il confine in entrambe le direzioni senza mai fermarsi in mezzo. Se oggi i tuoi agenti toccano dati reali — clienti, ordini, documenti — quel confine vale più di una buona policy scritta.

Per capire cosa gira davvero in rete quando l'IA è locale, leggi Privacy: cosa gira in rete; per il quadro più ampio sugli agenti che lavorano in locale, Agenti ML che girano in locale.

Fonti

• Secret Guard — GitHub
• Confronto con LiteLLM, LLM Guard, PasteGuard

In sintesi

Secret Guard è un gateway locale in Rust che intercetta le richieste del tuo agente e sostituisce i segreti con mock realistici prima che arrivino al provider, riportandoli al valore reale nella risposta. Ogni segreto ha la propria strategia (redact, reject, placeholder, monitor), i protocolli OpenAI, Anthropic e Responses hanno la redaction completa, Gemini e Ollama sono in pass-through per ora. Il modello non vede mai i valori reali, il prefix cache resta intatto, e il fallimento è chiuso (503) invece che silenzioso. È una v0.1.0 con i limiti che gli competono, ma il pattern — un confine tra agente e segreti — è quello che un'attività che fa girare agenti su dati veri dovrebbe avere da subito.

Articolo generato con IA