llm-token-proxy

一个用于 LLM API 流量的透明 PII 脱敏代理。位于你的应用与 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 典型流程

典型流程：应用 → Token 代理（PII 脱敏）→ LLM API（仅假名）→ Token 代理（恢复原始数据）→ 应用

检测管道（3 次扫描）

正则表达式 — 电子邮件、IP 地址、域名以及配置驱动的模式（已知人员、组织、主机名）
命名实体识别（NER） — spaCy 命名实体识别捕获正则表达式遗漏的人员和组织名称
用户名提取 — 裸邮箱本地部分（例如，从 [email protected] 中提取 admin）

假名格式

实体类型	内部示例	外部示例
电子邮件	`[email protected]`	`[email protected]`
域名	`domain-internal-001.com`	`domain-external-001.net`
IP	`10.99.99.1`（RFC1918）	感知 ASN 的捐赠 IP（见下文）
人员	`person_internal_001`	`person_external_001`
组织	`org_internal_001`	`org_external_001`
主机名	`host_001`	`host_001`

假名在会话内是确定性的——相同的真实值始终映射到相同的假名。

保留上下文的 IP 假名化

当 LLM 分析安全日志时，IP 地址的主机提供商和地理位置很重要——来自德国 Hetzner 的登录与来自美国住宅 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 在同一个会话内始终映射到相同的捐赠 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 — 用于内部 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）且不被视为敏感信息时，此选项非常有用。

环境变量

变量	默认值	用途
`ANTHROPIC_API_BASE`	`https://api.anthropic.com`	上游 Anthropic API 的 URL
`TOKEN_PROXY_CONFIG_PATH`	`/app/config.json`	配置文件路径
`LOG_LEVEL`	`info`	日志级别
`GEOIP_ASN_DB_PATH`	`/app/data/GeoLite2-ASN.mmdb`	MaxMind GeoLite2-ASN 数据库（可选）

运行时配置 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 对象读取）和流式（从 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）

请参阅 CONTRIBUTING.md 了解如何添加对其他提供商（OpenAI、Google Gemini 等）的支持。

局限性

仅文本 — 代理扫描 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/* 端点没有身份验证。代理设计用于可信/内部网络——不要将这些端点暴露给不受信任的网络。

开发

# 安装开发依赖
pip install -e ".[dev,ner]"
python -m spacy download en_core_web_sm

# 运行测试
pytest

# 检查代码
ruff check token_proxy/ tests/

许可证

Apache 2.0 — 参见 LICENSE。

token-proxy

最受欢迎