llm-token-proxy

Um proxy transparente de redação de PII para tráfego de API de LLM. Fica entre sua aplicação e o provedor de LLM, pseudonimizando dados sensíveis na ida e restaurando-os na volta.

Seu LLM nunca vê nomes reais, e-mails, IPs ou domínios — ele trabalha inteiramente com pseudônimos estruturados como [email protected]. Sua aplicação recebe de volta os valores originais, de forma transparente.

Por quê

Ao usar LLMs para operações de segurança, resposta a incidentes ou qualquer tarefa que envolva dados reais de clientes, você corre o risco de enviar PII para APIs de terceiros. Este proxy resolve isso ao:

• Substituir PII real por pseudônimos determinísticos e estruturados antes que chegue ao LLM
• Restaurar valores originais na resposta antes que chegue à sua aplicação
• Manter consistência dentro de uma sessão (a mesma entrada sempre mapeia para o mesmo pseudônimo)
• Funcionar de forma transparente — nenhuma alteração de código necessária em sua aplicação

Início rápido

# 1. Crie sua configuração
cp config.json.example config.json
# Edite config.json com seus domínios internos, entidades conhecidas, etc.

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

# 3. Aponte sua aplicação para o proxy
export ANTHROPIC_BASE_URL=http://localhost:8090/session/my-session/

Pronto. Suas chamadas de API Anthropic agora passam pelo proxy com PII redigida.

Como Funciona

Fluxo típico: Aplicação → Token Proxy (redação PII) → API LLM (apenas pseudônimos) → Token Proxy (restaurar originais) → Aplicação

Pipeline de Detecção (3 passagens)

1. Regex — e-mails, endereços IP, domínios e padrões baseados em configuração (pessoas conhecidas, organizações, hostnames)
2. NER — reconhecimento de entidades nomeadas do spaCy captura nomes de pessoas e organizações que o regex não pega
3. Extração de nome de usuário — partes locais de e-mail simples (ex.: admin de [email protected])

Formato do Pseudônimo

Pseudônimos são determinísticos dentro de uma sessão — o mesmo valor real sempre mapeia para o mesmo pseudônimo.

Pseudonimização de IP com preservação de contexto

Quando um LLM está analisando logs de segurança, o provedor de hospedagem e a geolocalização de um endereço IP importam — um login de um IP Hetzner na Alemanha conta uma história diferente de um de um ISP residencial nos EUA. A substituição ingênua por IPs de faixa de documentação (ex.: 198.51.100.x) destrói esse contexto.

Com o banco de dados opcional MaxMind GeoLite2-ASN, o proxy substitui IPs reais por um IP diferente do mesmo ASN e sub-rede. O LLM vê um IP com aparência real que resolve para o mesmo provedor de hospedagem e geografia aproximada — mas não é o endereço real.

• Um IP Hetzner é substituído por um IP Hetzner diferente do mesmo prefixo
• Um IP Cloudflare permanece um IP Cloudflare
• IPs internos/RFC1918 sempre mapeiam para 10.99.99.x (sem contexto de ASN a preservar)
• Sem o banco de dados GeoIP, IPs externos caem em 198.51.100.x (faixa de documentação)

O IP doador é escolhido deterministicamente via HMAC com um salt por sessão, de modo que o mesmo IP real sempre mapeia para o mesmo doador dentro de uma sessão, mas sessões diferentes produzem mapeamentos diferentes.

Configuração

O proxy acompanha um config.json vazio — sem listas de palavras ou suposições específicas de domínio. O config.json.example incluído é ajustado para operações de segurança com Microsoft Sentinel e Entra ID (mais de 8.000 nomes de tabelas/colunas KQL, termos de permissão da Graph API, domínios de referência de segurança). Se isso corresponde ao seu caso de uso, copie o que precisar dele. Se você estiver usando o proxy para um domínio diferente (saúde, jurídico, finanças, etc.), comece com o config vazio e construa suas próprias listas.

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 — domínios classificados como "internos" (recebem pseudônimos _internal_)
• partner_domains — domínios classificados como "parceiros"
• internal_ip_ranges — faixas CIDR para classificação de IP interno
• known_persons/orgs/hostnames — entidades correspondidas por regex (detecção garantida)
• ner_enabled — ativar/desativar NER do spaCy (requer spacy + en_core_web_sm)
• ner_skiplist — termos que o modelo NER deve ignorar (reduz falsos positivos)
• redaction_enabled — chave mestre; quando false, o proxy se torna um mero pass-through
• pseudonymize_domains — quando false, os domínios passam sem modificação (e-mails, IPs, nomes ainda são redigidos). Útil quando os nomes de domínio carregam contexto importante para o LLM (ex.: distinguir outlook.com de protonmail.com) e não são considerados sensíveis.

Variáveis de Ambiente

API de Configuração em Tempo de Execução

Gerencie listas de permissão e alterne a redação sem reiniciar:

# Visualizar todas as listas de permissão
curl http://localhost:8090/token-proxy/config/whitelist

# Adicionar termos à ner_skiplist (reduz falsos positivos)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "ner_skiplist", "values": ["EvoSTS", "Hetzner"]}'

# Adicionar domínios à lista de permissão (nunca pseudonimizar estes)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "domain_allowlist", "values": ["github.com"]}'

# Desabilitar redação (modo pass-through)
curl -X POST http://localhost:8090/token-proxy/config/status \
  -H "Content-Type: application/json" \
  -d '{"redaction_enabled": false}'

Categorias de whitelist: ner_skiplist, domain_allowlist, known_persons, known_orgs, known_hostnames

API de Auditoria e Inspeção

Inspecione o que o proxy está fazendo em tempo real:

# Listar sessões ativas
curl http://localhost:8090/token-proxy/sessions

# Visualizar mapeamentos de pseudônimos de uma sessão
curl http://localhost:8090/token-proxy/sessions/{session_id}/mappings

# Visualizar registro de atividade de redação
curl http://localhost:8090/token-proxy/sessions/{session_id}/log

# Pesquisar mapeamentos
curl http://localhost:8090/token-proxy/sessions/{session_id}/search?q=admin

# Visualizar payloads capturados (o que o LLM realmente viu)
curl http://localhost:8090/token-proxy/sessions/{session_id}/payloads

# Uso de tokens de uma sessão (tokens de entrada/saída em todas as requisições)
curl http://localhost:8090/token-proxy/sessions/{session_id}/usage

# Estatísticas globais (inclui total_tokens em todas as sessões)
curl http://localhost:8090/token-proxy/stats

Rastreamento de Uso de Tokens

O proxy registra input_tokens e output_tokens para cada requisição que encaminha — tanto não-streaming (lido do objeto usage da resposta) quanto streaming (analisado de eventos SSE message_start e message_delta). Como o proxy fica entre sua aplicação e o LLM, você obtém um único ponto de controle para medir o consumo de todos os clientes que o compartilham, sem instrumentar cada um.

curl http://localhost:8090/token-proxy/sessions/my-session/usage
# {
#   "session_id": "my-session",
#   "request_count": 3,
#   "input_tokens": 1240,
#   "output_tokens": 587
# }

curl http://localhost:8090/token-proxy/stats | jq .total_tokens
# { "input_tokens": 48213, "output_tokens": 19044 }

O uso por requisição também está incluído em /token-proxy/sessions/{session_id}/log sob usage_counts. Apenas contagens brutas de tokens são rastreadas — o preço é deixado a cargo do chamador.

Suporte a Streaming

O proxy suporta streaming SSE (stream: true). Pseudônimos são restaurados em tempo real usando uma abordagem de buffer de cauda que lida com pseudônimos divididos entre chunks SSE.

Adicionando Suporte a Provedores

O proxy usa um padrão de adaptador de provedor. Atualmente suporta:

• Anthropic Messages API (/v1/messages)

Veja CONTRIBUTING.md para como adicionar suporte a outros provedores (OpenAI, Google Gemini, etc.).

Limitações

• Apenas texto — o proxy escaneia campos de texto JSON na requisição/resposta da API. Imagens, PDFs e outros conteúdos binários (ex.: anexos codificados em base64 em requisições de visão) passam sem redação. Se seu fluxo de trabalho enviar capturas de tela ou documentos contendo PII, estes chegarão ao LLM inalterados.
• NER é apenas em inglês — o modelo spaCy (en_core_web_sm) detecta nomes de pessoas/organizações em inglês. Nomes em outros idiomas podem ser perdidos, a menos que sejam adicionados a known_persons/known_orgs na configuração.
• Regex tem pontos cegos — PII em formatos incomuns (ex.: e-mails ofuscados como admin [at] acme.com, números de telefone, endereços físicos) não serão capturados. O pipeline de detecção é ajustado para dados estruturados de TI/segurança.
• Sessões em memória — os mapeamentos de sessão ficam em memória e são perdidos na reinicialização. Não há armazenamento persistente. Sessões são removidas automaticamente após 2 horas.
• Apenas Anthropic — atualmente acompanha um adaptador da API Anthropic Messages. Outros provedores (OpenAI, Google Gemini) exigem a escrita de um adaptador de provedor (veja CONTRIBUTING.md).
• Sem autenticação nas APIs de gerenciamento — os endpoints /token-proxy/config/* e /token-proxy/sessions/* não possuem autenticação. O proxy foi projetado para redes confiáveis/internas — não exponha esses endpoints a redes não confiáveis.

Desenvolvimento

# Instalar dependências de desenvolvimento
pip install -e ".[dev,ner]"
python -m spacy download en_core_web_sm

# Executar testes
pytest

# Lint
ruff check token_proxy/ tests/

Licença

Apache 2.0 — veja LICENSE.