prompt-injection-scanner

@guardbee/mcp-prompt-injection-scanner

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

一个 MCP（Model Context Protocol）服务，用于扫描内容——RAG 片段、抓取的网页、文档——以查找间接提示词注入载荷。

ai-code-scanner 和 mcp-server-auditor 扫描代码；此软件包扫描数据。在经典提示词注入中，攻击者亲自编写恶意提示词；而在间接提示词注入中，攻击者完全不与模型交互，而是将指令嵌入文档、网页或工具结果中，供模型之后读取。当模型通过 RAG 检索或网页抓取将这些内容载入上下文时，嵌入的指令看起来就与用户自己的指令具有同等权限。

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

Web page/RAG document ──► prompt-injection-scanner ──► LLM context
              │
              ├─ Instruction override   ("ignore all previous instructions", "önceki talimatları yok say")
              ├─ Role spoofing          ("System:", <|im_start|>, [INST], <system>)
              ├─ Hidden text            (zero-width, Unicode tag and bidi characters, display:none + instruction, HTML comment)
              ├─ Direct address         ("Dear AI, ...")
              └─ Exfiltration           (system prompt extraction request, data → URL instruction, templated img beacon)

---

功能

• 17 种模式，5 个类别——指令覆盖、角色冒充、隐藏文本、直接寻址、数据外泄。支持英语和土耳其语表达
• 规则位于 @guardbee/guard-core 中，并与 @guardbee/mcp-security-proxy 共享，因此此扫描器报告的短语与代理在运行时拦截的短语相同
• 每条发现都包含风险原因及处理建议（recommendation），而不只是“发现了”
• SARIF 2.1.0 输出——集成 CI/CD（例如，每次 PR 时自动扫描知识库仓库）
• 支持通过 guardbee.yml 使用配置文件
• 45 个单元测试——每种模式都有一个正例和一个反例（误报）场景；专门测试了已知的误报来源，例如表情符号 ZWJ 序列和普通的 display:none 模态框

---

快速开始

Claude Desktop / MCP 客户端

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

CLI（CI/CD——例如，每次 PR 时扫描 RAG 知识库仓库）

npx @guardbee/mcp-prompt-injection-scanner scan ./knowledge-base --fail-on=high --format=sarif > results.sarif

---

MCP 工具

工具	描述
scan_text	扫描给定的文本/文档片段
scan_file	扫描单个文件
scan_directory	递归扫描目录（例如 RAG 知识库）（自动跳过 node_modules、.git、dist）
list_patterns	按类别列出所有受支持的模式

---

检测到的模式

类别	模式	严重程度	含义
指令覆盖	instruction_override_phrase	高	经典的覆盖短语，例如“忽略／无视／忘记之前的指令”
指令覆盖	instruction_override_tr	高	土耳其语形式：“önceki talimatları yok say / unut / görmezden gel”
指令覆盖	dan_mode	高	要求采用“DAN 模式”越狱角色
指令覆盖	bypass_safety	高	告诉模型绕过或禁用其安全措施／防护机制
角色伪装	system_role_spoof	中	内容中某行开头出现伪造的“System:”角色标签
角色伪装	chat_template_marker_injection	高	内容中出现原始聊天模板控制令牌（<|im_start|>、[INST]）
角色伪装	system_tag	高	试图将数据伪装成系统消息的 <system> 标签
隐藏文本	hidden_zero_width_chars	中	零宽空格／词连接符（U+200B/U+2060）——对人工审核者隐藏的文本
隐藏文本	unicode_tag_smuggling	严重	携带隐藏文本的不可见 Unicode 标签字符（U+E0000–E007F）；不包括旗帜表情，例如 🏴󠁧󠁢󠁥󠁮󠁧󠁿
隐藏文本	bidi_control_chars	中	双向文本覆盖／隔离字符，会导致文本显示顺序与阅读顺序不同
隐藏文本	css_hidden_text_with_instruction	高	包含指令式语言的 display:none／白底白字元素
隐藏文本	html_comment_instruction	高	包含指令式语言的 HTML 注释
直接指向	direct_address_to_ai	中	内容直接向“AI”／“助手”发话
数据外传	exfiltration_url_template_in_image	高	带有 {{...}}／${...} 模板的 Markdown 图片 URL——数据外传信标
数据外传	reveal_system_prompt_request	高	要求模型透露其系统提示词的句子
数据外传	reveal_system_prompt_tr	高	土耳其语形式：“sistem istemini göster”
数据外传	send_data_to_url_instruction	严重	明确指示模型将数据发送到外部 URL

这些是启发式发现——通过静态文本模式扫描得出，并非语义／意图分析。此设计旨在降低误报率（例如，明确排除表情符号的 ZWJ 序列和普通的 display:none 模态框），但仍应人工审核每项发现。

---

LLM 评审（可选）

这些模式能识别攻击短语；改写、间接表达或翻译后的指令可能绕过检测。--judge 还会让模型分块读取每个文件，并将针对 Agent 的指令报告为 judge_semantic_injection（高）。发现结果会附带 judge: { model, version, confidence }，也会记录在 SARIF properties 中。评审器只会添加发现结果。

GUARDBEE_JUDGE_URL=http://127.0.0.1:11434/v1 GUARDBEE_JUDGE_MODEL=qwen2.5:7b \
  npx @guardbee/mcp-prompt-injection-scanner scan ./docs --judge

除非配置，否则该功能默认关闭。由于内容会发送到端点，使用非本地端点时需要 --judge-allow-remote 和 https。在 GuardBee 的评审基准测试中（包含 50 个英语和土耳其语样本），模式检测能捕捉 16% 的攻击，而 qwen2.5:7b 能捕捉全部攻击，且没有误报。

配置（guardbee.yml）

prompt-injection-scanner:
  fail-on: high       # any | critical | high | medium | low | none
  max-files: 5000
  exclude:
    - ".test.ts"
    - "fixtures/"

---

开发

npm run build
npm test             # 45 unit tests

---

许可证

MIT — GuardBee

反馈

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