memory-poisoning-scanner

@guardbee/mcp-memory-poisoning-scanner

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

一个 MCP（Model Context Protocol）服务，用于扫描 Agent 代码中的记忆投毒——将不可信输入写入 Agent 的持久化、跨会话记忆中，之后再被检索出来，并作为可信上下文反馈给模型，甚至可能发生在完全不相关的未来会话中。

prompt-injection-scanner 会捕获模型一次性读取的内容（文档、抓取的网页）中潜藏的注入载荷。本软件包捕获的是结构上截然不同的问题：让注入载荷成为模型视为自身长期知识一部分的代码模式——这就像反射型 XSS 与存储型 XSS 之间的差别，只不过这里的目标是 Agent 的记忆，而不是浏览器的 DOM。

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

Claude ──► memory-poisoning-scanner ──► Your agent's source
              │
              ├─ memory-write     (untrusted input persisted into archival/core memory or a vector KB)
              └─ memory-readback  (recalled memory fed into a system/assistant-role message or prompt)

---

为什么普通对话记忆不在检测范围内

使用 ConversationBufferMemory 保存原始聊天轮次，或简单地调用 chatHistory.push({role: "user", content: userInput})，都完全正常——这只是对话历史，并非漏洞。本软件包有意不会对此发出告警。

它针对的是范围更窄、风险更高的情况：写入持久化记忆，并使其在当前对话结束后仍然留存——例如 MemGPT 风格的归档记忆（在未来不相关的会话中也会被检索），以及核心记忆（按设计在每一轮都重新注入系统提示词）；或者将向量存储用作长期知识库，而非每轮对话的 RAG 上下文。如果不可信输入未经清理就进入其中，它影响的就不只是当前交流——它会成为 Agent 认定为事实的一部分，持续影响任何人，直到有人恰好发现为止。

风险的另一半与此相对应：记忆或向量检索结果直接流入 system / assistant 角色消息或提示词模板时，被投毒的记忆就会“兑现”为模型服从的指令，而不再只是模型读取的数据。

---

功能

• 5 种记忆写入模式：MemGPT archival_memory_insert/core_memory_append/core_memory_replace 接收原始输入，向量存储 add_texts/add_documents/upsert 接收原始输入，以及用于自定义命名的长期记忆／知识库存储的通用兜底模式
• 3 种记忆回读模式：归档／向量检索结果流入系统／助手角色消息，或直接插入提示词模板
• SARIF 2.1.0 输出 — CI/CD 集成（GitHub Code Scanning 等）
• 支持通过 guardbee.yml 配置文件进行配置
• 17 项单元测试 — 每种模式均包含一个正向场景和一个负向（误报）场景，并明确检查普通对话缓冲区的使用不会产生任何发现。通过真实植入漏洞的测试夹具进行了端到端验证（同时捕获了写入和回读），并对整个 guardbee-mcp monorepo 进行了验证（386 个文件，生产代码中零误报）

---

快速开始

Claude Desktop / MCP 客户端

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

CLI（CI/CD）

npx @guardbee/mcp-memory-poisoning-scanner scan ./src --fail-on=high --format=sarif > results.sarif

---

MCP 工具

工具	描述
scan_text	扫描代码片段
scan_file	扫描单个文件
scan_directory	递归扫描目录
list_patterns	按类别列出所有支持的模式

---

检测到的模式

类别	模式	严重性
memory-write	archival_memory_insert_raw_input	严重
memory-write	core_memory_write_raw_input（追加／替换）	严重
memory-write	vector_store_add_raw_input	高
memory-write	generic_named_memory_write_raw_input	中
memory-readback	archival_memory_feeds_trusted_role	严重
memory-readback	vector_retrieval_feeds_trusted_role	高
memory-readback	memory_retrieval_feeds_prompt_template	高

---

配置（guardbee.yml）

memory-poisoning-scanner:
  fail-on: high       # any | critical | high | medium | none
  max-files: 5000
  exclude:
    - ".test.ts"

---

限制（有意设计）

• 基于启发式，而非污点跟踪。 写入和回读检查各自只查看一个有限位置，并不验证从某次特定写入到之后某次特定读取的数据流路径。发现表示代码中存在这种风险模式，而非数学上确认的利用链。
• 模式覆盖基于 MemGPT 术语和通用 JS 命名。 使用完全不同的函数／变量名称构建的自定义长期记忆系统不会被识别，除非它恰好符合通用模式（采用 *memory*／*knowledge_base* 命名，或使用 vectorstore 风格的 API）。
• 此工具查找的是可导致记忆投毒的代码模式，而不是运行时实际遭到投毒的记忆存储 — 如果你能直接检查记忆内容，请搭配 prompt-injection-scanner（用于扫描实际存储的内容）。

---

开发

npm run build
npm test             # 17 unit tests

---

许可证

MIT — GuardBee

反馈

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