LLM Privacy Guard

你的消息。你的机器。你的规则。
_{在敏感数据离开你的电脑之前将其脱敏 —— 而不是之后。}

## 它的功能 你发送给 ChatGPT、DeepSeek 或 Claude 的每一条消息都会经过 API 提供商的服务器。粘贴了一个 IP 地址、API key 或客户的电子邮件？它可能会最终出现在他们的日志、训练数据甚至更糟糕的地方。 **LLM Privacy Guard 是一个本地 HTTP 代理**，它位于你和所有 LLM API 之间，扫描外发消息并替换敏感数据 —— 所有操作均在本地完成： ``` ┌──────────────────────────────────────────────────────────┐ │ $ You type │ │ ssh root@203.0.113.1 -p 22, key=sk-abc123def4567890 │ │ Customer: zhangjie@company.com, ID: 110101199001011234 │ │ │ │ ↓ LLM Privacy Guard ↓ │ │ │ │ $ LLM receives │ │ ssh root@[IP] -p 22, key=[API_KEY] │ │ Customer: [EMAIL], ID: [ID_CARD] │ └──────────────────────────────────────────────────────────┘ ``` AI 永远看不到你的真实数据。 **一个代理即可覆盖你所有的工具** —— 无需为每个工具单独安装插件。 ## 设置指南 ### 新用户 —— 一次性设置（5 分钟） **步骤 1：安装** ``` pip install llm-privacy-guard ``` **步骤 2：全自动配置** ``` privacy-guard setup ``` 这条单一的命令会一步到位完成**所有这些**操作： - 在后台启动代理（带有 watchdog —— 崩溃时自动重启） - 扫描 `auth.json` 以查找你已连接的 LLM 提供商 - 配置 **opencode**、**Continue.dev**、**Cline / Roo Code** 和 **Codex** 通过代理进行路由 - 打印已配置的内容 预期输出： ``` LLM Privacy Guard — Auto Setup Proxy: http://127.0.0.1:19999 Upstream: auto-detect from request model [opencode] .../opencode.json: [deepseek] -> http://127.0.0.1:19999 .../opencode.json: [openai] -> http://127.0.0.1:19999 Configured 1 tool(s). Your LLM traffic is now filtered. ``` **步骤 3：验证过滤功能是否正常** ``` privacy-guard test ``` 输出应显示 ≥3 个匹配项： ``` Raw : ssh root@203.0.113.1 key=sk-abc123def456 ... Filtered : ssh root@[IP] key=sk-abc123def456 ... Matches : 3 [ipv4] 203.0.113.1 => [IP] [api_key] sk-abc123def456 => [API_KEY] [email] user@example.com => [EMAIL] ``` 如果少于 3 个匹配项：请检查 `config.yaml`。 **步骤 4：启用开机自启（推荐）** ``` privacy-guard setup --auto-start ``` 现在，每次你登录时代理都会自动启动。你再也不用为此操心了。 **完成。** 打开你的 AI 工具并像往常一样使用它们。每一条消息都会被静默过滤。 ### Codex：一次性设置，之后自动运行 如果你使用 Codex，预期的流程如下： ``` privacy-guard setup privacy-guard setup --auto-start ``` `setup` 会将你当前的 Codex 提供商重写为 `http://127.0.0.1:19999`，并在 `config.yaml` 中保留原始的 upstream。 `setup --auto-start` 是一个一次性的步骤，它让代理在你登录时自动启动，因此你**不需要**在每次 Codex 会话之前手动运行 `python cli.py setup` 或重启代理。 ### 你的流量真的经过代理了吗？ **只有使用你自己的 API key / 企业 endpoint 发送的消息才会被过滤。** 代理位于 `http://localhost:19999`。当你的工具向该地址发送请求时，代理会拦截它，过滤敏感数据，并转发给真实的 LLM API。这仅在以下情况有效： - 你的工具被配置为**使用你自己的 API endpoint**（base URL → `http://localhost:19999`） - 你选择的提供商具有你可以更改的 `baseURL` 字段 **未被过滤的情况：** | 模型类型 | 原因 | |------------|-----| | 工具本身提供的免费模型（opencode 免费版、Trae iCube、Cursor 免费版、Copilot 免费版） | 这些请求会经过工具供应商自己的后端 —— 完全不触碰你的代理 | | GitHub Copilot（任何版本） | 专有后端，不支持自定义 endpoint | | Trae 内置 AI（iCube） | Endpoint 被硬编码 | **在信任该过滤器之前** —— 发送一条包含虚假 IP（如 `1.2.3.4`）的测试消息，并询问 AI “我刚才发送的 IP 是什么？”。如果 AI 看到 `1.2.3.4`，说明你当前的聊天没有经过代理。请切换为使用你自己的 API key 的模型。 ### 日常使用 | 想要... | 命令 | |-----------|---------| | 检查代理是否存活 | `privacy-guard status` | | 临时停止代理 | `privacy-guard stop` | | 停止后重新启动 | `privacy-guard start` | | 代理被其他程序终止 | `privacy-guard start`（在大多数情况下，watchdog 会自动重启它） | | 查看过滤是否生效 | `privacy-guard test` | ### 故障排除 | 症状 | 原因 | 解决方法 | |---------|-------|-----| | AI 工具无法连接 | 代理未运行 | `privacy-guard start` | | `privacy-guard test` 显示少于 3 个匹配项 | 配置问题 | 检查 `config.yaml`，规则是否已启用？ | | 代理出现 502 错误 | 模型未识别，且无 fallback | 设置 `--upstream` 或检查模型名称 | | 端口 19999 已被占用 | 旧代理未完全停止 | `privacy-guard stop`，等待后重试 | | 代理持续崩溃 | 未知错误 | 运行 `privacy-guard start --watchdog` 查看实时日志 | | 敏感数据未被过滤 | 使用的是免费模型或工具提供的模型 | 切换为使用你自己的 API key 的提供商（参见[“你的流量真的经过代理了吗？”](#does-your-traffic-actually-go-through-the-proxy)) | | 代理意外消失 | 另一个脚本杀死了所有 Python 进程（例如，`Get-Process python \| Stop-Process`） | **切勿**编写会杀死所有 Python 进程的代码。运行 `privacy-guard start` 重启即可。 | ## 支持的工具 运行 `privacy-guard setup`，这些工具将会被**自动配置** —— 无需手动操作： | 工具 | 工作原理 | |------|-------------| | **opencode** | 从 auth.json 读取已连接的提供商，设置 `baseURL` | | **Continue.dev** | 更新 `~/.continue/config.json` → `apiBase` | | **Cline / Roo Code** | 更新 VS Code / Trae / Cursor 的 `settings.json` | | **Codex** | 更新 `~/.codex/config.toml` 中当前提供商的 `base_url`，并在 `config.yaml` 中保存原始的 upstream，以便基于模型的路由依然有效 | 这些工具需要**一次手动 URL 更改**（将 API endpoint 设置为 `http://localhost:19999`）： | 工具 | 在哪里更改 | |------|----------------| | **Cursor 内置 AI** | 不支持自定义 endpoint | | **Trae 内置 AI (iCube)** | Endpoint 已被硬编码，无法覆盖。请改用 Continue 或 Cline 插件 | | **GitHub Copilot** | 专有后端，不支持代理 | | **Dify** | 模型提供商 → OpenAI-API-compatible → API Base | | **LangChain** | `ChatOpenAI(openai_api_base="http://localhost:19999")` | | **任何 curl / SDK** | `base_url` / `--url` 参数 | ## CLI 参考 | 命令 | 描述 | |---------|-------------| | `privacy-guard setup` | 一步到位：启动代理 + 自动配置 opencode / Continue / Cline / Codex | | `privacy-guard setup --auto-start` | 注册登录时自启（Windows/Linux/macOS） | | `privacy-guard setup --remove-auto-start` | 移除自启注册 | | `privacy-guard start` | **默认：** 后台运行 + watchdog（崩溃时自动重启） | | `privacy-guard start --foreground` | 前台运行，无 watchdog（按 Ctrl+C 停止，用于调试） | | `privacy-guard start --watchdog` | 前台运行 watchdog 并显示可见日志（用于调试） | | `privacy-guard stop` | 停止所有进程（watchdog + 代理） | | `privacy-guard status` | 检查 watchdog 和代理是否正在运行 | | `privacy-guard test` | 验证过滤引擎是否正常工作 | ### 选项 | 选项 | 描述 | |--------|-------------| | `--port 12345` | 代理端口（默认：19999，或 `$PRIVACY_GUARD_PORT`） | | `--upstream https://...` | Fallback upstream URL（或 `$PRIVACY_GUARD_UPSTREAM`） | | `--foreground` | （仅限 start）在无 watchdog 的前台运行 | | `--watchdog` | （仅限 start）带有可见日志的前台 watchdog | | `--auto-start` / `--remove-auto-start` | （仅限 setup）注册/移除自启 | | `--dry-run` | （仅限 setup）预览配置更改而不实际应用 | ## Python 库 直接在你的代码中使用该引擎 —— 无需代理： ``` from privacy_engine import filter_text, scan_text # 脱敏 filter_text("ssh root@203.0.113.1, key=sk-abc123") # → "ssh root@[IP], key=[API_KEY]" # 审计（无修改） for m in scan_text("token=ghp_xJ3kL9mN2pQ5rS8"): print(f"{m['type']}: {m['value']} → {m['placeholder']}") ``` ## 检测规则 27 条内置规则： | 规则 | 目标 | 替换占位符 | |------|--------|-------------| | `ipv4` · `ipv4_hex` | IPv4（点分格式 / 十六进制 `0xC0A80101`） | `[IP]` | | `ipv6` · `ipv6_hyphen` | IPv6（压缩、括号、混合、连字符格式） | `[IP]` | | `uuid` · `uuid_hex` | UUID（带/不带连字符） | `[UUID]` | | `email` | 电子邮件地址 | `[EMAIL]` | | `phone_cn` · `phone_cn_sep` · `phone_intl` | 中国大陆及国际电话号码 | `[PHONE]` | | `id_card_cn` · `id_card_cn_sep` | 中国身份证号码 | `[ID_CARD]` | | `ssn_us` | 美国 SSN (`XXX-XX-XXXX`) | `[SSN]` | | `api_key_prefix` | 密钥：`sk-`、`pk-`、`Bearer`（不区分大小写） | `[API_KEY]` | | `aws_access_key` | AWS Access Key (`AKIA...`) | `[AWS_KEY]` | | `ssh_private_key` · `ssh_public_key` | SSH 密钥（PKCS#8、RSA、Ed25519、ECDSA） | `[SSH_KEY]` | | `sha_hash` | 64 位十六进制哈希值（如 SHA256 等） | `[HASH]` | | `github_token` | GitHub tokens (`ghp_`、`github_pat_` 等) | `[GITHUB_TOKEN]` | | `jwt` · `jwt_multiline` | JWT tokens（标准格式 + 换行符分隔） | `[JWT]` | | `db_connection_string` · `db_cli` | 数据库 URL 及 CLI 命令 | `[DB_URL]` · `[DB_CMD]` | | `credit_card` | 信用卡号（通过 Luhn 算法验证） | `[CARD]` | | `credential_value` · `url_query_credential` · `credential_inline` | 内联凭证 | `[CREDENTIAL]` | ## 功能 ### 深度检测 27 条内置规则，涵盖网络身份标识、PII、机密信息、基础设施及财务数据。 ### Entropy 引擎 捕捉正则表达式遗漏的内容 —— 极有可能是密钥或 token 的高熵字符串。 ### 对抗性防御 剔除零宽字符、URL/HTML 解码、Unicode NFKC 归一化 —— 防止绕过手段。 ### 默认安全 ReDoS 防护、100KB 输入上限、协议地址白名单、日志中不记录原始值。 ### 崩溃恢复 `privacy-guard start` 默认使用 watchdog 运行代理。如果发生崩溃，watchdog 会自动将其重启 —— 无需人工干预。 ### 自启动 `privacy-guard setup --auto-start` 将代理注册为登录时启动（Windows 启动文件夹、Linux autostart、macOS launchd）。重启后，无需进行任何操作代理即可运行。 ### 多提供商自动路由 从请求的 `model` 字段检测目标 API。没有供应商锁定。内置 14 多个提供商。 ### 一键设置 `privacy-guard setup` 可自动检测并配置 opencode、Continue、Codex 等 —— 无需手动编辑配置。 ## 架构 ``` Any LLM client (opencode / Continue / Cline / Codex / curl / SDK / …) │ │ baseURL = http://localhost:19999 ▼ ┌───────────────────┐ │ proxy_server.py │ ← HTTP proxy layer │ intercept · filter · forward │ └───────┬───────────┘ │ ┌───────▼───────────┐ │ privacy_engine/ │ ← Filter engine (pure Python, zero AI deps) │ │ │ preprocess → 27 regex │ │ → entropy │ │ → dedup │ │ → replace │ └───────┬───────────┘ │ ▼ Real LLM API (DeepSeek / OpenAI / Anthropic / …) ``` | 文件/目录 | 角色 | |----------|------| | `proxy_server.py` | HTTP 代理：拦截 → 过滤 → 转发 | | `cli.py` | CLI：`setup` / `start` / `stop` / `status` / `test` | | `setup_tools.py` | 自动配置：检测并配置 opencode、Continue、Codex 等 | | `privacy_engine/detector.py` | 协调调度：regex + entropy，重叠去重，替换 | | `privacy_engine/patterns.py` | 27 条带优先级的已编译 regex 规则 | | `privacy_engine/entropy.py` | 滑动窗口 Shannon entropy + 误报过滤器 | | `privacy_engine/whitelist.py` | 协议地址、RFC 域名、主机名 | | `privacy_engine/config.py` | YAML 配置加载器 | | `plugin.py` | QwenP 适配器（可选，出于兼容性维护） | ## 配置 将 `config.yaml` 放在你的项目或 `~/.config/llm-privacy-guard/` 目录中（可选 —— 开箱即用默认配置即可工作）： ``` # Proxy 设置 proxy: port: 19999 # Custom model → upstream mappings (checked before built-in map) upstream_map: my-provider: "https://api.my-provider.com" # Entropy 检测 entropy: enabled: true threshold: 5.0 # higher = stricter mode: "auto" # "auto" | "review" # 禁用不需要的规则 rules: email: false # 自定义规则 custom_rules: - name: "internal_srv" pattern: "srv-\\d{4}\\.internal\\.com" placeholder: "[INTERNAL]" # Whitelist（永不脱敏） whitelist: ips: ["8.8.8.8"] strings: ["public-value-123"] ``` ## 针对 QwenPaw 用户 `plugin.py` 仍在维护且可正常工作。通过以下方式安装： ``` qwenpaw plugin install https://github.com/lenychang520/llm-privacy-guard/archive/refs/heads/master.zip ``` 升级： ``` qwenpaw plugin install --force https://github.com/lenychang520/llm-privacy-guard/archive/refs/heads/master.zip ``` `/privacy test`、`/privacy scan`、`/privacy report`、`/privacy export` 和 `/privacy reset` 命令继续在 QwenPaw 内部可用。 ## 升级 ``` pip install --upgrade llm-privacy-guard ``` 如果代理正在运行，请停止并重启： ``` privacy-guard stop privacy-guard setup ``` ## 路线图 - [x] 具有透明拦截功能的 QwenPaw 插件 - [x] `/privacy` 斜杠命令（4 条命令） - [x] 27 条检测规则 + entropy 引擎 - [x] 对抗性绕过防御（预处理 pipeline） - [x] 安全加固（ReDoS、输入上限、速率金丝雀） - [x] 本地 HTTP 代理 —— 覆盖任何 LLM 客户端 - [x] CLI + 一键设置 —— `setup` / `start` / `stop` / `status` / `test` - [x] 多提供商自动路由 —— 基于模型，无供应商锁定 - [x] 崩溃恢复 —— watchdog 在故障时自动重启代理 - [x] 登录自启 —— `setup --auto-start` 适用于 Windows/Linux/macOS - [ ] 内置小型 LLM 以进行语义过滤 ## 许可证 Apache 2.0 © 2026 [lenychang](https://github.com/lenychang520)

标签：Dify, LangChain, LLM隐私保护, 数据脱敏, 本地代理, 轻量级, 逆向工具, 预处理管道