llm-token-proxy

Прозрачный прокси для редактирования PII в трафике LLM. Располагается между вашим приложением и провайдером LLM, псевдонимизируя конфиденциальные данные на пути к LLM и восстанавливая их на обратном пути.

Ваша LLM никогда не видит реальных имён, адресов электронной почты, IP-адресов или доменов — она работает исключительно со структурированными псевдонимами, такими как [email protected]. Ваше приложение получает обратно исходные значения прозрачным образом.

Зачем

При использовании LLM для задач безопасности, реагирования на инциденты или любых других задач, связанных с реальными данными клиентов, вы рискуете отправить PII сторонним API. Этот прокси решает проблему следующим образом:

• Заменяет реальные PII на детерминированные, структурированные псевдонимы до того, как они достигнут LLM
• Восстанавливает исходные значения в ответе до того, как он достигнет вашего приложения
• Обеспечивает согласованность в рамках сессии (одно и то же входное значение всегда сопоставляется с одним и тем же псевдонимом)
• Работает прозрачно — не требует изменений кода в вашем приложении

Быстрый старт

# 1. Создайте свой конфигурационный файл
cp config.json.example config.json
# Отредактируйте config.json: укажите внутренние домены, известные сущности и т.д.

# 2. Запустите с Docker
docker build -t llm-token-proxy .
docker run -p 8090:8080 -v ./config.json:/app/config.json llm-token-proxy

# 3. Направьте ваше приложение на прокси
export ANTHROPIC_BASE_URL=http://localhost:8090/session/my-session/

Всё. Теперь вызовы Anthropic API проходят через прокси с отредактированными PII.

Как это работает

Типичный поток: Приложение → Token Proxy (редактирование PII) → LLM API (только псевдонимы) → Token Proxy (восстановление оригиналов) → Приложение

Конвейер обнаружения (3 прохода)

1. Регулярные выражения — адреса электронной почты, IP-адреса, домены и шаблоны из конфигурации (известные лица, организации, имена хостов)
2. NER — распознавание именованных сущностей spaCy перехватывает имена лиц и организаций, которые пропускают регулярные выражения
3. Извлечение имени пользователя — локальные части email без домена (например, admin из [email protected])

Формат псевдонимов

Псевдонимы являются детерминированными в рамках сессии — одно и то же реальное значение всегда сопоставляется с одним и тем же псевдонимом.

Сохраняющая контекст псевдонимизация IP

Когда LLM анализирует журналы безопасности, провайдер хостинга и геолокация IP-адреса имеют значение — вход с IP Hetzner в Германии говорит об ином, чем вход с домашнего провайдера в США. Наивная замена на IP из документационных диапазонов (например, 198.51.100.x) уничтожает этот контекст.

С опциональной базой MaxMind GeoLite2-ASN прокси заменяет реальные IP на другой IP из той же ASN и подсети. LLM видит реально выглядящий IP, который относится к тому же провайдеру хостинга и примерной географии — но это не настоящий адрес.

• IP Hetzner заменяется на другой IP Hetzner из того же префикса
• IP Cloudflare остаётся IP Cloudflare
• Внутренние/RFC1918 IP всегда сопоставляются с 10.99.99.x (контекст ASN отсутствует)
• Без базы GeoIP внешние IP заменяются на 198.51.100.x (диапазон документации)

Донорский IP выбирается детерминированно через HMAC с солью сессии, поэтому один и тот же реальный IP всегда сопоставляется с одним и тем же донором в рамках сессии, но разные сессии дают разные сопоставления.

Конфигурация

Прокси поставляется с пустым config.json — никаких встроенных списков слов или доменных предположений. Прилагаемый config.json.example настроен для задач безопасности с Microsoft Sentinel и Entra ID (более 8000 имён таблиц/столбцов KQL, терминов разрешений Graph API, эталонных доменов безопасности). Если это соответствует вашему варианту использования, скопируйте нужное из него. Если вы используете прокси для другой области (здравоохранение, юриспруденция, финансы и т.д.), начните с пустого конфига и создайте свои собственные списки.

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 — домены, классифицируемые как «внутренние» (получают псевдонимы _internal_)
• partner_domains — домены, классифицируемые как «партнёрские»
• internal_ip_ranges — диапазоны CIDR для классификации внутренних IP
• known_persons/orgs/hostnames — сущности, сопоставляемые по регулярным выражениям (гарантированное обнаружение)
• ner_enabled — включение spaCy NER (требуется spacy + en_core_web_sm)
• ner_skiplist — термины, которые модель NER должна игнорировать (уменьшает ложные срабатывания)
• redaction_enabled — главный переключатель; при false прокси становится чистым сквозным каналом
• pseudonymize_domains — при false домены проходят без изменений (email, IP, имена всё равно редактируются). Полезно, когда имена доменов несут важный контекст для LLM (например, различие outlook.com и protonmail.com) и не считаются конфиденциальными.

Переменные окружения

API управления конфигурацией во время выполнения

Управляйте белыми списками и переключайте редактирование без перезапуска:

# Просмотр всех белых списков
curl http://localhost:8090/token-proxy/config/whitelist

# Добавление терминов в списки игнорирования NER (уменьшает ложные срабатывания)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "ner_skiplist", "values": ["EvoSTS", "Hetzner"]}'

# Добавление доменов в разрешённый список (никогда не псевдонимизировать)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "domain_allowlist", "values": ["github.com"]}'

# Отключение редактирования (режим сквозной передачи)
curl -X POST http://localhost:8090/token-proxy/config/status \
  -H "Content-Type: application/json" \
  -d '{"redaction_enabled": false}'

Категории белых списков: ner_skiplist, domain_allowlist, known_persons, known_orgs, known_hostnames

API аудита и инспекции

Просматривайте, что делает прокси в реальном времени:

# Список активных сессий
curl http://localhost:8090/token-proxy/sessions

# Просмотр сопоставлений псевдонимов для сессии
curl http://localhost:8090/token-proxy/sessions/{session_id}/mappings

# Просмотр журнала активности редактирования
curl http://localhost:8090/token-proxy/sessions/{session_id}/log

# Поиск сопоставлений
curl http://localhost:8090/token-proxy/sessions/{session_id}/search?q=admin

# Просмотр захваченных полезных нагрузок (что на самом деле видела LLM)
curl http://localhost:8090/token-proxy/sessions/{session_id}/payloads

# Использование токенов для сессии (входные/выходные токены по всем запросам)
curl http://localhost:8090/token-proxy/sessions/{session_id}/usage

# Глобальная статистика (включая total_tokens по всем сессиям)
curl http://localhost:8090/token-proxy/stats

Отслеживание использования токенов

Прокси записывает input_tokens и output_tokens для каждого пересылаемого запроса — как для непотокового (читает из объекта usage ответа), так и для потокового (парсит из событий SSE message_start и message_delta). Поскольку прокси находится между вашим приложением и LLM, вы получаете единую точку контроля для измерения потребления всеми клиентами, использующими его, без необходимости инструментировать каждого.

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 }

Использование на каждый запрос также включается в /token-proxy/sessions/{session_id}/log под usage_counts. Отслеживаются только необработанные количества токенов — расчёт стоимости остаётся за вызывающей стороной.

Поддержка потоковой передачи

Прокси поддерживает потоковую передачу SSE (stream: true). Псевдонимы восстанавливаются в реальном времени с использованием подхода хвостового буфера, который обрабатывает псевдонимы, разделённые по фрагментам SSE.

Добавление поддержки провайдеров

Прокси использует шаблон адаптера провайдера. В настоящее время поддерживается:

• Anthropic Messages API (/v1/messages)

См. CONTRIBUTING.md инструкции по добавлению поддержки других провайдеров (OpenAI, Google Gemini и т.д.).

Ограничения

• Только текст — прокси сканирует текстовые поля JSON в запросах/ответах API. Изображения, PDF и другое бинарное содержимое (например, вложения в кодировке base64 в запросах vision) проходят без редактирования. Если ваш рабочий процесс включает скриншоты или документы, содержащие PII, они достигнут LLM без изменений.
• NER только на английском языке — модель spaCy (en_core_web_sm) обнаруживает английские имена лиц и организаций. Имена на других языках могут быть пропущены, если не добавлены в known_persons/known_orgs в конфиге.
• У регулярных выражений есть слепые зоны — PII в необычных форматах (например, обфусцированные email типа admin [at] acme.com, номера телефонов, физические адреса) не будут обнаружены. Конвейер обнаружения настроен на структурированные ИТ/данные безопасности.
• Сессии в памяти — сопоставления сессий хранятся в памяти и теряются при перезапуске. Постоянное хранилище отсутствует. Сессии автоматически удаляются через 2 часа.
• Только Anthropic — в настоящее время поставляется с адаптером Anthropic Messages API. Для других провайдеров (OpenAI, Google Gemini) требуется написание адаптера провайдера (см. CONTRIBUTING.md).
• Нет аутентификации на управляющих API — конечные точки /token-proxy/config/* и /token-proxy/sessions/* не имеют аутентификации. Прокси предназначен для доверенных/внутренних сетей — не открывайте эти конечные точки для недоверенных сетей.

Разработка

# Установка зависимостей для разработки
pip install -e ".[dev,ner]"
python -m spacy download en_core_web_sm

# Запуск тестов
pytest

# Линтинг
ruff check token_proxy/ tests/

Лицензия

Apache 2.0 — см. LICENSE.