llm-token-proxy

Un proxy transparente de redacción de PII para tráfico de API de LLM. Se sitúa entre tu aplicación y el proveedor de LLM, seudonimizando datos sensibles a la salida y restaurándolos a la vuelta.

Tu LLM nunca ve nombres reales, correos electrónicos, IPs o dominios — trabaja enteramente con seudónimos estructurados como [email protected]. Tu aplicación recibe los valores originales, de forma transparente.

Por qué

Al usar LLMs para operaciones de seguridad, respuesta a incidentes, o cualquier tarea que involucre datos reales de clientes, corres el riesgo de enviar PII a APIs de terceros. Este proxy soluciona eso:

• Reemplazando PII real con seudónimos deterministas y estructurados antes de que llegue al LLM
• Restaurando los valores originales en la respuesta antes de que llegue a tu aplicación
• Manteniendo consistencia dentro de una sesión (una misma entrada siempre se asigna al mismo seudónimo)
• Funcionando de forma transparente — no se necesitan cambios de código en tu aplicación

Inicio rápido

# 1. Crea tu configuración
cp config.json.example config.json
# Edita config.json con tus dominios internos, entidades conocidas, etc.

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

# 3. Apunta tu aplicación al proxy
export ANTHROPIC_BASE_URL=http://localhost:8090/session/my-session/

Eso es todo. Tus llamadas a la API de Anthropic ahora pasan a través del proxy con la PII redactada.

Cómo funciona

Flujo típico: Aplicación → Token Proxy (redacción de PII) → API LLM (solo seudónimos) → Token Proxy (restaurar originales) → Aplicación

Pipeline de detección (3 pasadas)

1. Regex — correos electrónicos, direcciones IP, dominios y patrones impulsados por configuración (personas conocidas, organizaciones, nombres de host)
2. NER — reconocimiento de entidades nombradas con spaCy detecta nombres de personas y organizaciones que el regex pasa por alto
3. Extracción de nombres de usuario — partes locales de correos electrónicos sin dominio (ej., admin de [email protected])

Formato de seudónimo

Los seudónimos son deterministas dentro de una sesión — el mismo valor real siempre se asigna al mismo seudónimo.

Seudonimización de IP con preservación de contexto

Cuando un LLM analiza registros de seguridad, el proveedor de alojamiento y la geolocalización de una dirección IP importan — un inicio de sesión desde una IP de Hetzner en Alemania cuenta una historia diferente a uno desde un ISP residencial en EE. UU. El reemplazo ingenuo con IPs de rango de documentación (ej., 198.51.100.x) destruye este contexto.

Con la base de datos MaxMind GeoLite2-ASN opcional, el proxy reemplaza las IPs reales con una IP diferente del mismo ASN y subred. El LLM ve una IP de aspecto real que se resuelve al mismo proveedor de alojamiento y geografía aproximada — pero no es la dirección real.

• Una IP de Hetzner se reemplaza con una IP diferente de Hetzner del mismo prefijo
• Una IP de Cloudflare sigue siendo una IP de Cloudflare
• Las IPs internas/RFC1918 siempre se asignan a 10.99.99.x (sin contexto ASN que preservar)
• Sin la base de datos GeoIP, las IPs externas caen en 198.51.100.x (rango de documentación)

La IP donante se elige de forma determinista mediante HMAC con una sal por sesión, por lo que la misma IP real siempre se asigna al mismo donante dentro de una sesión, pero diferentes sesiones producen asignaciones diferentes.

Configuración

El proxy se envía con un config.json vacío — sin listas de palabras incorporadas ni suposiciones específicas de dominio. El config.json.example incluido está ajustado para operaciones de seguridad con Microsoft Sentinel y Entra ID (más de 8,000 nombres de tablas/columnas de KQL, términos de permisos de Graph API, dominios de referencia de seguridad). Si eso coincide con tu caso de uso, copia lo que necesites de él. Si usas el proxy para un dominio diferente (salud, legal, finanzas, etc.), comienza desde la configuración vacía y crea tus propias 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 — dominios clasificados como "internos" (obtienen seudónimos _internal_)
• partner_domains — dominios clasificados como "socio"
• internal_ip_ranges — rangos CIDR para clasificación de IP internas
• known_persons/orgs/hostnames — entidades detectadas por regex (detección garantizada)
• ner_enabled — activar/desactivar NER de spaCy (requiere spacy + en_core_web_sm)
• ner_skiplist — términos que el modelo NER debe ignorar (reduce falsos positivos)
• redaction_enabled — interruptor maestro; cuando es false, el proxy se convierte en paso directo puro
• pseudonymize_domains — cuando es false, los dominios pasan sin modificar (los correos electrónicos, IPs, nombres aún se redactan). Útil cuando los nombres de dominio llevan contexto importante para el LLM (ej., distinguir outlook.com de protonmail.com) y no se consideran sensibles.

Variables de Entorno

API de Configuración en Tiempo de Ejecución

Gestiona listas blancas y alterna la redacción sin reiniciar:

# Ver todas las listas blancas
curl http://localhost:8090/token-proxy/config/whitelist

# Agregar términos a la lista de omisión de NER (reduce falsos positivos)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "ner_skiplist", "values": ["EvoSTS", "Hetzner"]}'

# Agregar dominios a la lista de permitidos (nunca se seudonimizan)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "domain_allowlist", "values": ["github.com"]}'

# Deshabilitar redacción (modo paso directo)
curl -X POST http://localhost:8090/token-proxy/config/status \
  -H "Content-Type: application/json" \
  -d '{"redaction_enabled": false}'

Categorías de lista blanca: ner_skiplist, domain_allowlist, known_persons, known_orgs, known_hostnames

API de Auditoría e Inspección

Inspecciona lo que el proxy está haciendo en tiempo real:

# Listar sesiones activas
curl http://localhost:8090/token-proxy/sessions

# Ver asignaciones de seudónimos para una sesión
curl http://localhost:8090/token-proxy/sessions/{session_id}/mappings

# Ver registro de actividad de redacción
curl http://localhost:8090/token-proxy/sessions/{session_id}/log

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

# Ver cargas útiles capturadas (lo que realmente vio el LLM)
curl http://localhost:8090/token-proxy/sessions/{session_id}/payloads

# Uso de tokens para una sesión (tokens de entrada/salida en todas las solicitudes)
curl http://localhost:8090/token-proxy/sessions/{session_id}/usage

# Estadísticas globales (incluye total_tokens en todas las sesiones)
curl http://localhost:8090/token-proxy/stats

Seguimiento de Uso de Tokens

El proxy registra input_tokens y output_tokens para cada solicitud que reenvía — tanto no streaming (leídos del objeto usage de la respuesta) como streaming (analizados de los eventos SSE message_start y message_delta). Debido a que el proxy se sitúa entre tu aplicación y el LLM, obtienes un único punto de control para medir el consumo en todos los clientes que lo comparten, sin necesidad de instrumentar cada uno.

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 }

El uso por solicitud también se incluye en /token-proxy/sessions/{session_id}/log bajo usage_counts. Solo se registran recuentos de tokens brutos — el precio queda a cargo de quien llama.

Soporte de Streaming

El proxy soporta streaming SSE (stream: true). Los seudónimos se restauran en tiempo real mediante un enfoque de búfer de cola que maneja seudónimos divididos entre fragmentos SSE.

Añadir Soporte para Proveedores

El proxy utiliza un patrón de adaptador de proveedor. Actualmente soporta:

• API de Mensajes de Anthropic (/v1/messages)

Consulta CONTRIBUTING.md sobre cómo añadir soporte para proveedores adicionales (OpenAI, Google Gemini, etc.).

Limitaciones

• Solo texto — el proxy escanea campos de texto JSON en la solicitud/respuesta de la API. Imágenes, PDFs y otro contenido binario (ej., archivos adjuntos codificados en base64 en solicitudes de visión) pasan sin redacción. Si tu flujo de trabajo envía capturas de pantalla o documentos que contienen PII, esos llegarán al LLM sin modificar.
• NER solo en inglés — el modelo de spaCy (en_core_web_sm) detecta nombres de personas y organizaciones en inglés. Nombres en otros idiomas pueden no ser detectados a menos que se añadan a known_persons/known_orgs en la configuración.
• Regex tiene puntos ciegos — PII en formatos inusuales (ej., correos electrónicos ofuscados como admin [at] acme.com, números de teléfono, direcciones físicas) no serán capturados. El pipeline de detección está ajustado para datos estructurados de TI/seguridad.
• Sesiones en memoria — las asignaciones de sesión viven en memoria y se pierden al reiniciar. No hay almacenamiento persistente. Las sesiones se auto-expulsan después de 2 horas.
• Solo Anthropic — actualmente se envía con un adaptador de API de Mensajes de Anthropic. Otros proveedores (OpenAI, Google Gemini) requieren escribir un adaptador de proveedor (ver CONTRIBUTING.md).
• Sin autenticación en APIs de gestión — los endpoints /token-proxy/config/* y /token-proxy/sessions/* no tienen autenticación. El proxy está diseñado para redes internas/de confianza — no expongas estos endpoints a redes no confiables.

Desarrollo

# Instalar dependencias de desarrollo
pip install -e ".[dev,ner]"
python -m spacy download en_core_web_sm

# Ejecutar pruebas
pytest

# Lint
ruff check token_proxy/ tests/

Licencia

Apache 2.0 — ver LICENSE.