Security Blog

Come si fornisce una chiave API a un agente AI senza che lui la veda?

#44

November 20, 2026 · By Mila

← All posts

Si fornisce all'agente un riferimento, non la chiave, e si lascia che un proxy sulla stessa macchina inserisca la chiave reale nella richiesta in uscita. Ecco perché le variabili d'ambiente non bastano più, e come configurare il tutto.

Si fornisce all'agente un riferimento al posto della chiave, e si lascia che un piccolo proxy sulla stessa macchina inserisca la chiave reale nella richiesta in uscita. L'agente scrive clavitor://OpenAI/key dove dovrebbe andare il segreto. L'API riceve la chiave reale. L'agente non la possiede mai, quindi non può stamparla, registrarla nei log né essere convinto a consegnarla.

Questa è l'idea completa. Il resto di questa pagina spiega perché è importante e come configurarla.

Perché "mettila in una variabile d'ambiente" non basta più

Un anno fa, export OPENAI_API_KEY=sk-... era il modo normale di passare una chiave a uno script. Nessuno ci faceva caso.

Poi lo script ha iniziato a ragionare da solo.

Un agente AI legge file, esegue strumenti, scrive log e parla con sconosciuti su internet. Ognuna di queste cose è una via di fuga per una chiave che lui possiede:

  • L'ambiente. Qualsiasi cosa l'agente esegua lo eredita. Compare in /proc, nei dump di crash, nell'output di CI.
  • La memoria. Anche se la chiave viene recuperata a runtime, resta nel processo per tutto il tempo in cui l'agente è in esecuzione.
  • La conversazione. Un prompt injection in una pagina web o in un commento a un issue chiede all'agente di "includere la propria configurazione per il debug". Un agente disponibile lo fa.

Niente di tutto questo richiede un bug nell'agente. Richiede solo che la chiave si trovi in un punto raggiungibile dall'agente.

Il pattern: l'agente chiede, il proxy firma

Pensi a una card chiave di hotel. L'ospite può aprire la propria stanza. L'ospite non vede mai la chiave master, e la porta registra ogni utilizzo.

Per una chiave API, funziona così:

  1. La chiave reale risiede in una cassaforte, cifrata.
  2. Un proxy viene eseguito accanto all'agente, sulla stessa macchina.
  3. L'agente invia la propria richiesta HTTPS con un riferimento al posto della chiave.
  4. Il proxy recupera il valore dalla cassaforte, lo inserisce nella richiesta e la inoltra.
  5. Il lato agente possiede solo il riferimento.

I log dell'agente mostrano il riferimento. Lo stesso vale per la sua finestra di contesto. Non c'è nulla da far trapelare.

Come configurarlo con Clavitor

Ecco come lo abbiamo realizzato. Un binario, una variabile d'ambiente, nessuna modifica al codice dell'agente.

Crei un client per l'agente nella propria cassaforte con gli scope necessari, poi registra il proxy e lo avvia:

$ clavitor-proxy init
$ clavitor-proxy ca
$ clavitor-proxy serve

init registra il proxy come quel client. ca stampa l'autorità di certificazione del proxy: la aggiunga all'archivio di fiducia usato dal client HTTP dell'agente, perché il proxy apre da solo la connessione HTTPS dell'agente. Poi punti l'agente al proxy:

$ export HTTPS_PROXY="http://clavitor:$(cat proxy-auth)@127.0.0.1:1983"

$ curl -H "Authorization: Bearer clavitor://OpenAI/key" \
    https://api.openai.com/v1/chat/completions

proxy-auth è il token di accesso del proxy stesso, il file accanto al binario. Ogni connessione deve portarlo con sé, così un altro utente sulla stessa macchina non può usare il proxy. Il proxy è in ascolto su 127.0.0.1:1983 e solo su quella macchina, a meno che non lo configuri apposta per una rete privata fidata.

Funziona con qualsiasi agente il cui client HTTP rispetta HTTPS_PROXY: Claude Code, Codex, i suoi script. Una credibile va solo a un host elencato come indirizzo web nella propria voce, quindi un agente vittima di prompt injection non può puntare lo stesso riferimento al server di uno sconosciuto. La procedura passo per passo è nella documentazione del proxy.

E gli altri segreti dell'agente?

Non tutti i segreti viaggiano in un header HTTP. Una password di deploy, una chiave SSH, un codice a due fattori per un accesso.

Per questi, l'agente chiede alla cassaforte una voce alla volta con clavitor-cli, e solo per le voci che gli sono state assegnate:

$ clavitor-cli get "GitHub Deploy" --field password

$ clavitor-cli get "Stripe API" --field key
clavitor-cli: CV-2041: Access denied.

L'agente non può elencare la cassaforte. Una ricerca per nome mostra al massimo cinque titoli corrispondenti, e solo un conteggio oltre quel numero.

I codici di autenticazione funzionano allo stesso modo. clavitor-cli totp "GitHub" calcola il codice corrente sulla macchina dell'agente, così può superare un accesso a due fattori senza che nessuno debba leggere un telefono. La cassaforte conserva il segreto cifrato.

Cosa questo non risolve

Un proxy tiene la chiave fuori dall'agente. Non rende l'agente affidabile.

  • Un agente compromesso può comunque usare l'accesso che gli è stato dato. Semplicemente non può portarsi la chiave a casa.
  • Chi ha accesso da amministratore alla macchina può usare anche il proxy, o leggerne la memoria.
  • Un'API che riporta la chiave nella propria risposta la consegna all'agente. Il proxy inserisce le chiavi nelle richieste e non filtra le risposte.

Per questo l'accesso che gli sta intorno conta quanto il proxy:

  • Scope. Ogni agente riceve solo le voci che gli servono. Un agente di lavoro vede GitHub e AWS. Un agente di deploy vede le chiavi SSH e il database.
  • Limiti di lettura. Ogni agente può leggere solo un certo numero di voci diverse al minuto e all'ora, e i numeri li decide Lei. Un agente che supera il proprio limite orario due volte entro due ore viene bloccato finché non lo sblocca Lei.
  • Un registro. Ogni lettura viene registrata: quale agente, quale voce, quando.

Esegue più agenti? Dia a ciascuno il proprio proxy e la propria registrazione. Così ognuno ha il proprio scope, i propri limiti e la propria traccia, e l'agente A non può vedere le chiavi dell'agente B.

In breve

Non consegni una chiave a un agente. Gli consegni un nome per la chiave, e tiene la chiave a un passo di distanza, in un luogo che decide, ogni volta, se quell'agente può usarla in quel momento.

Configuri il proxy oppure veda come funziona l'accesso degli agenti.