prompt-leak-scanner

@guardbee/mcp-prompt-leak-scanner

🇬🇧 英语 | 🇹🇷 土耳其语 | 🇨🇳 中文 | 🇯🇵 日语 | 🇰🇷 韩语 | 🇧🇷 葡萄牙语 | 🇪🇸 西班牙语 | 🇩🇪 德语

一个 MCP（Model Context Protocol）服务，也可作为独立反向代理，用于在凭据和个人身份信息（PII）泄露出你的应用之前，检测出站大模型提示词中的泄露内容。

secret-scanner 可以在你的代码库中查找秘密信息。这个软件包则用于查找进入运行时提示词的秘密信息和 PII：例如，支持 Agent 将客户工单（电子邮件、卡号）直接粘贴到系统提示词中；有人在调试会话中把 API 密钥粘贴到聊天里；或者内部工具将未经检查的原始用户输入转发给大模型。这发生在流程中的另一个环节，故障模式也不同于 .env 文件泄露。

默认情况下，遥测功能处于关闭状态。启用 GUARDBEE_TELEMETRY=1 后，它会发送服务、工具、成功状态、耗时和简短的参数值（例如文件路径）；较长的字符串以及 content、token 或 password 等字段会替换为占位符。请参阅 @guardbee/mcp-telemetry。

Your app ──► prompt-leak-scanner (proxy) ──► Real LLM API (OpenAI/Anthropic/...)
                    │
                    ├─ monitor: forward unchanged, log findings
                    ├─ redact:  forward with matches replaced by [REDACTED:<id>]
                    └─ block:   reject the request before it ever reaches the model

---

两种使用方式

1. 按需扫描（MCP 工具） — scan_text/scan_messages/scan_file/scan_directory。在发布任何基于用户输入构建提示词的内容之前，让 Claude 检查提示词、聊天请求正文样本文件或提示词日志目录。

2. 实时反向代理（proxy CLI 命令） — 在你的应用和实际的大模型 API 之间运行。它会缓冲并检查出站请求正文（消息/系统文本），然后不做修改，直接将上游响应流式传回——因此 SSE/流式补全会原样通过；只有发出的提示词会被解析。将应用的 baseURL 指向代理，而不是实际的 API，这样集成中的其他内容都不需要更改。

guardbee-prompt-leak-scanner proxy --upstream=https://api.openai.com --port=8788 --mode=redact
# your app: baseURL = http://localhost:8788 instead of https://api.openai.com

---

检测质量：校验和，而不只是正则表达式

仅用“11 位数字”或“16 位数字”的正则表达式，会不断误报订单号、电话分机号和时间戳。所有具有真实校验和算法的 PII 模式都会使用该算法：

• TC Kimlik No — 实际的 11 位土耳其国民身份证校验和算法（而不只是统计位数的正则表达式）
• 信用卡号 — Luhn 校验和
• IBAN — ISO 7064 MOD97-10 校验和

随机的 11 位数字大约有 1/10 的概率碰巧通过 TC Kimlik 校验；只用正则表达式会产生多得多的误报。凭据模式（API 密钥、JWT、私钥）会根据真实的提供商专属前缀或结构进行匹配（sk-、AKIA、ghp_、-----BEGIN...PRIVATE KEY-----、JWT 的三段式 base64url 格式），采用与 secret-scanner 相同的低误报方法。校验和验证器来自 @guardbee/guard-core，并与 @guardbee/mcp-security-proxy 共享。

检测结果绝不会回显真实值。 检测结果中的 maskedMatch 只显示前 3 个和后 2 个字符（sk-…wx）——记录或显示刚刚捕获的内容本身会适得其反。代理的审计事件更进一步：只记录触发了哪种模式以及位置，绝不记录匹配到的文本。

---

功能

• 13 种模式，4 个类别：凭据（9 种）、财务 PII（2 种，经校验和验证）、国民身份证件（1 种，经校验和验证）、联系信息 PII（2 种）
• 识别聊天正文——可解析 OpenAI/Anthropic 风格的 messages[].content（字符串或内容块数组）和 system 字段，而不仅限于纯文本
• 实时反向代理模式，支持监控/脱敏/拦截策略——仅检查请求，响应则原样流式传递
• 脱敏的检测结果和不含凭据的审计事件——该工具不会成为泄漏内容的第二份副本
• SARIF 2.1.0 输出——用于 CI/CD 集成（GitHub Code Scanning 等）
• 支持通过 guardbee.yml 配置文件进行配置
• 29 项单元测试——校验和验证器使用已知正确/错误的测试向量进行验证；代理在三种模式下均通过真实的本地 HTTP 客户端/服务往返测试（而非仅使用进程内模拟）

---

快速开始

Claude Desktop / MCP 客户端

{
  "mcpServers": {
    "guardbee-prompt-leak-scanner": {
      "command": "npx",
      "args": ["-y", "@guardbee/mcp-prompt-leak-scanner"]
    }
  }
}

CLI（CI/CD）

npx @guardbee/mcp-prompt-leak-scanner scan ./prompt-fixtures --fail-on=high --format=sarif > results.sarif

CLI（实时代理）

npx @guardbee/mcp-prompt-leak-scanner proxy --upstream=https://api.openai.com --mode=block --fail-on-severity=critical

---

MCP 工具

工具	描述
scan_text	扫描原始文本字符串
scan_messages	扫描 OpenAI/Anthropic 风格的聊天请求正文对象
scan_file	扫描单个文件（纯文本或 JSON 请求正文测试文件——自动检测）
scan_directory	递归扫描包含提示词日志/测试文件的目录
list_patterns	按类别列出所有支持的模式

---

检测到的模式

类别	模式	严重程度
凭据	OpenAI / Anthropic / Google / Stripe API 密钥、AWS 访问密钥 ID、GitHub PAT、Slack 令牌、PEM 私钥块	严重
凭据	JWT	高
财务 PII	信用卡号（经 Luhn 校验）	高
财务 PII	IBAN（经 mod-97 校验）	高
国民身份证件	TC Kimlik No（经校验和验证）	高
联系信息 PII	电子邮件地址	中
联系信息 PII	土耳其电话号码	中

---

配置（guardbee.yml）

prompt-leak-scanner:
  fail-on: high       # any | critical | high | medium | low | none
  max-files: 5000
  exclude:
    - "fixtures/known-safe/"

---

限制（有意为之）

• 代理只检查请求正文；不会解析或修改流式 SSE 响应，而是将其原样传递。
• 聊天正文中只提取 messages[].content（字符串或 {type:"text"} 内容块）和顶层 system；不扫描此结构之外的提供商专属字段。
• 这是基于模式/校验和的检测，而非通用 NER/PII 模型——无法检测不符合已知结构模式的 PII（例如自由文本中的姓名或街道地址）。

---

开发

npm run build
npm test             # 29 unit tests

---

许可证

MIT — GuardBee

反馈

有问题、想法或遇到误报？请在 GitHub 讨论区中发起讨论，或提交问题。如果 GuardBee 对你有帮助，可以在代码仓库点个 ⭐，帮助其他人找到它。