llm-token-proxy

Un proxy trasparente di oscuramento PII per il traffico API LLM. Si posiziona tra la tua applicazione e il provider LLM, pseudonimizzando i dati sensibili in uscita e ripristinandoli in entrata.

Il tuo LLM non vede mai nomi reali, email, IP o domini — lavora esclusivamente con pseudonimi strutturati come [email protected]. La tua applicazione riceve i valori originali, in modo trasparente.

Perché

Quando si utilizzano LLM per operazioni di sicurezza, incident response o qualsiasi attività che coinvolga dati reali dei clienti, si rischia di inviare PII ad API di terze parti. Questo proxy risolve il problema:

Sostituendo le PII reali con pseudonimi deterministici e strutturati prima che raggiungano il LLM
Ripristinando i valori originali nella risposta prima che arrivi all'applicazione
Mantenendo la coerenza all'interno di una sessione (lo stesso input corrisponde sempre allo stesso pseudonimo)
Funzionando in modo trasparente — non sono necessarie modifiche al codice dell'applicazione

Avvio rapido

# 1. Crea il tuo file di configurazione
cp config.json.example config.json
# Modifica config.json con i tuoi domini interni, entità note, ecc.

# 2. Esegui con Docker
docker build -t llm-token-proxy .
docker run -p 8090:8080 -v ./config.json:/app/config.json llm-token-proxy

# 3. Punta la tua applicazione al proxy
export ANTHROPIC_BASE_URL=http://localhost:8090/session/my-session/

Tutto qui. Le tue chiamate all'API Anthropic passano ora attraverso il proxy con PII oscurate.

Come funziona

Flusso tipico del Token Proxy

Flusso tipico: Applicazione → Token Proxy (oscuramento PII) → API LLM (solo pseudonimi) → Token Proxy (ripristino originali) → Applicazione

Pipeline di rilevamento (3 passaggi)

Regex — email, indirizzi IP, domini e pattern basati sulla configurazione (persone note, organizzazioni, hostname)
NER — riconoscimento di entità nominate con spaCy cattura nomi di persone e organizzazioni che la regex non rileva
Estrazione username — parti locali delle email (es. admin da [email protected])

Formato degli pseudonimi

Tipo entità	Esempio interno	Esempio esterno
Email	`[email protected]`	`[email protected]`
Dominio	`domain-internal-001.com`	`domain-external-001.net`
IP	`10.99.99.1` (RFC1918)	IP donatore ASN-aware (vedi sotto)
Persona	`person_internal_001`	`person_external_001`
Org	`org_internal_001`	`org_external_001`
Hostname	`host_001`	`host_001`

Gli pseudonimi sono deterministici all'interno di una sessione — lo stesso valore reale corrisponde sempre allo stesso pseudonimo.

Pseudonimizzazione IP con preservazione del contesto

Quando un LLM analizza log di sicurezza, il provider di hosting e la geolocalizzazione di un indirizzo IP sono importanti — un login da un IP Hetzner in Germania racconta una storia diversa da uno di un ISP residenziale negli Stati Uniti. La sostituzione ingenua con IP di intervalli di documentazione (es. 198.51.100.x) distrugge questo contesto.

Con il database MaxMind GeoLite2-ASN opzionale, il proxy sostituisce gli IP reali con un IP diverso dello stesso ASN e sottorete. Il LLM vede un IP dall'aspetto reale che risolve allo stesso provider di hosting e alla stessa geografia approssimativa — ma non è l'indirizzo reale.

Un IP Hetzner viene sostituito con un IP Hetzner diverso dello stesso prefisso
Un IP Cloudflare rimane un IP Cloudflare
Gli IP interni/RFC1918 vengono sempre mappati a 10.99.99.x (nessun contesto ASN da preservare)
Senza il database GeoIP, gli IP esterni ricadono su 198.51.100.x (intervallo di documentazione)

L'IP donatore viene scelto deterministicamente tramite HMAC con un sale per sessione, quindi lo stesso IP reale viene sempre mappato allo stesso donatore all'interno di una sessione, ma sessioni diverse producono mappature diverse.

Configurazione

Il proxy viene fornito con un config.json vuoto — nessuna lista di parole predefinita o ipotesi specifiche del dominio. Il config.json.example incluso è ottimizzato per operazioni di sicurezza con Microsoft Sentinel e Entra ID (oltre 8.000 nomi di tabelle/colonne KQL, termini delle API Graph, domini di riferimento di sicurezza). Se questo corrisponde al tuo caso d'uso, copia ciò di cui hai bisogno. Se utilizzi il proxy per un dominio diverso (sanità, legale, finanza, ecc.), parti dal config vuoto e costruisci le tue liste.

`config.json`

{
  "internal_domains": ["yourcompany.com"],
  "partner_domains": ["partnercorp.com"],
  "internal_ip_ranges": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
  "known_persons": ["John Smith"],
  "known_orgs": ["YourCompany"],
  "known_hostnames": ["DC01", "FS01"],
  "ner_enabled": true,
  "ner_skiplist": [],
  "redaction_enabled": true
}

internal_domains — domini classificati come "interni" (ottengono pseudonimi _internal_)
partner_domains — domini classificati come "partner"
internal_ip_ranges — intervalli CIDR per la classificazione degli IP interni
known_persons/orgs/hostnames — entità abbinate tramite regex (rilevamento garantito)
ner_enabled — attiva/disattiva spaCy NER (richiede spacy + en_core_web_sm)
ner_skiplist — termini che il modello NER deve ignorare (riduce i falsi positivi)
redaction_enabled — interruttore principale; quando false, il proxy diventa un semplice pass-through
pseudonymize_domains — quando false, i domini passano senza modifiche (email, IP, nomi sono ancora oscurati). Utile quando i nomi di dominio portano contesto importante per il LLM (es. distinguere outlook.com da protonmail.com) e non sono considerati sensibili.

Variabili d'ambiente

Variabile	Default	Scopo
`ANTHROPIC_API_BASE`	`https://api.anthropic.com`	URL dell'API Anthropic upstream
`TOKEN_PROXY_CONFIG_PATH`	`/app/config.json`	Percorso del file di configurazione
`LOG_LEVEL`	`info`	Livello di logging
`GEOIP_ASN_DB_PATH`	`/app/data/GeoLite2-ASN.mmdb`	Database MaxMind GeoLite2-ASN (opzionale)

API di configurazione runtime

Gestisci le whitelist e attiva/disattiva l'oscuramento senza riavviare:

# Visualizza tutte le whitelist
curl http://localhost:8090/token-proxy/config/whitelist

# Aggiungi termini alla skiplist NER (riduce i falsi positivi)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "ner_skiplist", "values": ["EvoSTS", "Hetzner"]}'

# Aggiungi domini alla allowlist (mai pseudonimizzare questi)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "domain_allowlist", "values": ["github.com"]}'

# Disabilita l'oscuramento (modalità pass-through)
curl -X POST http://localhost:8090/token-proxy/config/status \
  -H "Content-Type: application/json" \
  -d '{"redaction_enabled": false}'

Categorie delle whitelist: ner_skiplist, domain_allowlist, known_persons, known_orgs, known_hostnames

API di audit e ispezione

Ispeziona cosa sta facendo il proxy in tempo reale:

# Elenca le sessioni attive
curl http://localhost:8090/token-proxy/sessions

# Visualizza le mappature degli pseudonimi per una sessione
curl http://localhost:8090/token-proxy/sessions/{session_id}/mappings

# Visualizza il log delle attività di oscuramento
curl http://localhost:8090/token-proxy/sessions/{session_id}/log

# Cerca nelle mappature
curl http://localhost:8090/token-proxy/sessions/{session_id}/search?q=admin

token-proxy

Più Popolari