llm-token-proxy

LLM APIトラフィック用の透過的PII編集プロキシ。アプリケーションとLLMプロバイダの間に位置し、送信時に機密データを仮名化し、戻り時に復元します。

LLMは実際の名前、メール、IP、ドメインを一切認識せず、[email protected] のような構造化された仮名でのみ動作します。アプリケーションは、元の値を透過的に受け取ります。

なぜ必要か

セキュリティ運用、インシデント対応、または実際の顧客データを含むタスクでLLMを使用する場合、PIIをサードパーティAPIに送信するリスクがあります。このプロキシは次の方法でその問題を解決します。

• LLMに到達する前に、実際のPIIを決定論的で構造化された仮名に置き換える
• アプリケーションに届く前に、レスポンス内の元の値を復元する
• セッション内で一貫性を維持する（同じ入力は常に同じ仮名にマッピングされる）
• 透過的に動作する — アプリケーションのコード変更は不要

クイックスタート

# 1. Create your config
cp config.json.example config.json
# Edit config.json with your internal domains, known entities, etc.

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

# 3. Point your application at the proxy
export ANTHROPIC_BASE_URL=http://localhost:8090/session/my-session/

これだけです。Anthropic APIの呼び出しがPIIを編集した状態でプロキシを通るようになります。

仕組み

通常のフロー: アプリケーション → トークンプロキシ（PII編集） → LLM API（仮名のみ） → トークンプロキシ（元の値を復元） → アプリケーション

検出パイプライン（3パス）

1. 正規表現 — メールアドレス、IPアドレス、ドメイン、および設定で定義されたパターン（既知の個人、組織、ホスト名）
2. NER — spaCyの固有表現抽出が、正規表現では見逃す人物名や組織名をキャッチ
3. ユーザー名抽出 — ベアのメールローカルパート（例： [email protected] から admin）

仮名形式

仮名はセッション内で決定論的です。同じ実際の値は常に同じ仮名にマッピングされます。

コンテキストを保持するIP仮名化

LLMがセキュリティログを分析する際、IPアドレスのホスティングプロバイダや地理位置情報は重要です。HetznerのドイツIPからのログインと、米国の住宅用ISPからのログインでは異なる意味を持ちます。ドキュメンテーション範囲のIP（例： 198.51.100.x）への単純な置換では、このコンテキストが失われます。

オプションの MaxMind GeoLite2-ASN データベースを使用すると、プロキシは実際のIPを 同じASNおよびサブネット内の別のIP に置き換えます。LLMは、実際のアドレスではありませんが、同じホスティングプロバイダとおおよその地理情報に解決される、実際に見えるIPを受け取ります。

• Hetzner IPは、同じプレフィックス内の別のHetzner IPに置き換えられる
• Cloudflare IPはCloudflare IPのまま
• 内部/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を使用したセキュリティ運用（8,000以上の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 — 内部IP分類のためのCIDR範囲
• known_persons/orgs/hostnames — 正規表現で照合されるエンティティ（確実に検出）
• ner_enabled — spaCy NERの有効/無効（spacy + en_core_web_sm が必要）
• ner_skiplist — NERモデルが無視する用語（誤検出を減らす）
• redaction_enabled — マスタースイッチ。false の場合、プロキシは完全なパススルーになる
• pseudonymize_domains — false の場合、ドメインは変更されずに通過（メール、IP、名前は引き続き編集される）。LLMが重要なコンテキスト（例： outlook.com と protonmail.com の区別）を持ち、機密と見なされない場合に便利。

環境変数

ランタイム設定API

再起動せずにホワイトリストを管理し、編集を切り替える：

# View all whitelists
curl http://localhost:8090/token-proxy/config/whitelist

# Add terms to NER skiplist (reduces false positives)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "ner_skiplist", "values": ["EvoSTS", "Hetzner"]}'

# Add domains to allowlist (never pseudonymize these)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "domain_allowlist", "values": ["github.com"]}'

# Disable redaction (pass-through mode)
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

プロキシがリアルタイムで何をしているかを検査：

# List active sessions
curl http://localhost:8090/token-proxy/sessions

# View pseudonym mappings for a session
curl http://localhost:8090/token-proxy/sessions/{session_id}/mappings

# View redaction activity log
curl http://localhost:8090/token-proxy/sessions/{session_id}/log

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

# View captured payloads (what the LLM actually saw)
curl http://localhost:8090/token-proxy/sessions/{session_id}/payloads

# Token usage for a session (input/output tokens across all requests)
curl http://localhost:8090/token-proxy/sessions/{session_id}/usage

# Global statistics (includes total_tokens across all sessions)
curl http://localhost:8090/token-proxy/stats

トークン使用量追跡

プロキシは、転送するすべてのリクエストの input_tokens と output_tokens を記録します。ノンストリーミング（レスポンスの usage オブジェクトから読み取り）とストリーミング（message_start および message_delta SSEイベントから解析）の両方に対応しています。プロキシはアプリケーションと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)

他のプロバイダ（OpenAI、Google Geminiなど）のサポートを追加する方法については、CONTRIBUTING.md を参照してください。

制限事項

• テキストのみ — プロキシはAPIリクエスト/レスポンス内のJSONテキストフィールドをスキャンします。画像、PDF、その他のバイナリコンテンツ（例：ビジョンリクエストのbase64エンコードされた添付ファイル）は編集されずに通過します。PIIを含むスクリーンショットやドキュメントを送信するワークフローの場合、それらは変更されずにLLMに到達します。
• NERは英語のみ — spaCyモデル（en_core_web_sm）は英語の個人名/組織名を検出します。他の言語の名前は、設定の known_persons / known_orgs に追加されない限り見逃される可能性があります。
• 正規表現には盲点がある — 特殊な形式のPII（例： admin [at] acme.com のような難読化されたメール、電話番号、住所）はキャッチされません。検出パイプラインは構造化されたIT/セキュリティデータ向けに調整されています。
• インメモリセッション — セッションマッピングはメモリに保存され、再起動すると失われます。永続ストレージはありません。セッションは2時間後に自動的に削除されます。
• Anthropicのみ — 現在はAnthropic Messages APIアダプタが同梱されています。他のプロバイダ（OpenAI、Google Gemini）では、プロバイダアダプタを作成する必要があります（CONTRIBUTING.md 参照）。
• 管理APIに認証なし — /token-proxy/config/* および /token-proxy/sessions/* エンドポイントには認証がありません。プロキシは信頼できる内部ネットワーク向けに設計されています。これらのエンドポイントを信頼できないネットワークに公開しないでください。

開発

# Install dev dependencies
pip install -e ".[dev,ner]"
python -m spacy download en_core_web_sm

# Run tests
pytest

# Lint
ruff check token_proxy/ tests/

ライセンス

Apache 2.0 — LICENSE を参照。