Heimdall — Mcp Security Scanner

Heimdall

守护 Agent 大门的卫士。

面向 Model Context Protocol (MCP) 服务的本地预检安全扫描器——在 Agent 信任某个服务之前，先审查该服务或整份 Agent 配置。无需账户或后端，且默认绝不运行服务。

MCP 服务是未经审查的代码，具有自然语言攻击面：它们的工具描述会直接发送给你的模型，而服务则以你机器上的权限运行。Heimdall 会评估服务实际能做什么，而不是它声称能做什么，并引用确切证据。它完全在你的机器上运行，无需账户，且默认绝不执行服务，因此你可以在安装软件包之前先进行审查，并在 CI 中设置门禁。

快速开始

npx mcp-heimdall-scan firecrawl-mcp                   # scan a published server
npx mcp-heimdall-scan ./claude_desktop_config.json    # audit your whole agent config
npx mcp-heimdall-scan firecrawl-mcp --online          # + check its deps for known CVEs (OSV.dev)
npx mcp-heimdall-scan ./my-server --policy strict     # gate it in CI

无需安装，在本地运行，任何内容都不会离开你的机器。

也可在浏览器中试用： caglarbozkurt.github.io/mcp-heimdall ——完整扫描器完全在客户端运行（通过 jsDelivr 获取 npm 软件包；也可粘贴 tools.json / MCP 配置）。无需后端，不会上传任何内容。本地路径和 --handshake 需使用 CLI。

检查内容

每项发现都会引用 file:line 或 tool:name。能力 ≠ 风险：原始能力仅作为信息性概况展示，不会导致扫描失败——只有硬性门禁和真实异常才会导致失败。

差异所在

• 本地运行，且不会运行服务。 默认情况下，所有内容都是静态的并且离线运行——无需账户、无需后端、不会上传任何内容——除非你选择启用 --handshake（仅针对一次性 VM 提供文档说明），否则绝不会执行不受信任的代码。安装前先审核软件包。
• 证明数据流路径。 污点/数据流分析将“读取文件 AND 访问网络 = 失败”转化为具体且有定位的流向——因此不会因为读取配置和无关的 API 调用就误报。
• 审查完整的关卡。 它会跨你配置的所有服务进行分析——单个服务都看不到的跨服务数据外泄路径，它也能发现。大多数扫描器一次只看一个服务。
• 由你掌控的关卡。 检测器会输出事实；由你定义的策略将其转化为通过 / 警告 / 失败。拒绝某些能力、要求来源证明、添加经过审计的豁免、设置 CI 关卡。

用法

heimdall <target> [options]

--tools <file>     supplement analysis with a tools/list (or {tools,resources,prompts}) dump
--policy <p>       "default", "strict", or a JSON policy file
--baseline <file>  diff against a prior --json report (drift / rug-pull detection)
--handshake        RUN the server(s) for the live tool list (untrusted code — VM/container only)
--online           check declared deps against OSV.dev for known CVEs (sends dep names, not source)
--json             machine-readable report
--sarif            SARIF 2.1.0 (GitHub code-scanning / CI)
--no-fail          always exit 0

Exit codes: 0 pass/warn · 1 fail · 2 error

策略

检测器会输出事实；策略会据此给出判定。使用默认策略、选择 strict，或编写自己的采购/安全标准：

{
  "name": "acme-procurement",
  "denyCapabilities": ["exec", "dynamic-eval", "secret-access"],
  "require": ["has_repository", "has_license"],
  "failOnSeverity": "high",
  "warnOnSeverity": "low",
  "allow": [{ "id": "capability/scope-mismatch", "reason": "reviewed", "expires": "2026-12-31" }]
}

库

import { scan } from "mcp-heimdall-scan";

const report = await scan("some-mcp-server", { policy: "strict" });
if (report.verdict === "fail") throw new Error(report.reasons.join("; "));

还提供 Claude Code 技能（skill/）——在对话中安装前审核服务。

将其用作 MCP 服务

为你的 Agent 提供一个 scan_mcp_server 工具，让它在连接服务之前先行审核——“添加之前先扫描”。将 Heimdall 添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "heimdall": {
      "command": "npx",
      "args": ["-y", "--package", "mcp-heimdall-scan", "heimdall-mcp"]
    }
  }
}

该工具接受 target（npm 软件包、pypi:<name>、路径、GitHub URL、tools.json 或客户端 配置），以及可选的 policy 和 online。它仅执行静态分析——会下载服务，但绝不执行服务；代码执行模式（--handshake、validate）也特意不向 Agent 开放。

在 CI 中使用（GitHub Action）

为每个拉取请求设置关卡——扫描你的 MCP 配置（或某个服务），如果存在风险就让构建失败。将以下内容添加到 .github/workflows/：

- uses: caglarbozkurt/mcp-heimdall@v1
  with:
    target: ./claude_desktop_config.json   # a path, npm/pypi package, github URL, or tools.json
    policy: strict                          # "default", "strict", or a JSON policy file
    online: true                            # also check deps for known CVEs (OSV.dev)
    sarif: heimdall.sarif                   # optional: emit SARIF for code scanning

完全在你自己的 CI 运行器上运行——无需后端，且公开仓库可免费使用。

验证（行为交叉检查）

静态分析会告诉你服务能够做什么。heimdall validate 会检查这是否符合它实际的行为——它会预先加载一个能力记录器来运行服务（挂钩 fs / net / http(s) / child_process / vm / fetch / process.env），驱动每个工具， 并将观察到的运行时行为与静态标记进行对比：

heimdall validate ./my-server            # one server: confirmed / missed / not-exercised
heimdall validate --list servers.txt     # batch: a recall number over observed behavior

• 已确认 — 已标记且已观察到（静态判断得到验证）。
• 未触发 — 已标记，但使用简单参数时未触发（这只是一个下限，不能证明该标记有误）。
• 遗漏 — 已观察到，但未标记 → 这是需要审查的真实静态分析缺口（也可能是库的附带副作用）。

因此，它可以可靠地发现假阴性（静态分析遗漏）；但不能证明某个标记不成立。 每个服务都会在一次性 HOME 和工作目录中运行，不会继承任何密钥，但它仍会运行服务并调用其工具（可能产生网络／执行副作用）——请使用一次性 VM／容器。

对 200 个真实软件包进行行为测试（benchmarks/validate-run.md）： 55 个成功启动，34 个触发了可观察到的能力。在服务实际运行时触发的能力中，静态扫描标记了 80.9%（55/68）——首轮发现的遗漏被列入修复清单后，这一比例从 75.8% 上升至此（我们扩大了基于依赖项的网络检测范围，使网络遗漏大约减少了一半）。剩余遗漏属于结构性问题：能力在依赖项内部或子进程中触发，而静态分析从根本上无法看到这些情况——这正是 validate 作为后备检查存在的原因。真实报告召回率，公开呈现，并在每轮测试中持续改进。

大规模测试

在 npm 注册表中选取 2,500 个真实 MCP 软件包进行测试（benchmarks/）：约 5 分钟内扫描了 1,726 个，其中 0.7% 被标记——在混乱的真实代码中表现稳健。另在小型标注样例集上取得 100% 的得分（npm run eval，约 10 个良性／恶意样例，包括 Damn Vulnerable MCP 项目）——这是一项校准检查，并非广泛的真实世界准确率数据；上述实地扫描未经标注，仅用于评估稳健性。完整日志： benchmarks/field-run.md。

扫描结果揭示了你的 Agent 所信任的生态系统情况：

被标记的 0.7% 源于安装时的代码执行和提示词注入——其中包括一些真实服务，其工具描述中嵌入了隐藏的零宽字符。这类隐蔽的工具投毒很容易绕过关键词扫描器。

稳健性 + 分布测试并非准确率基准测试——这 2,500 个服务未经标注。标记意味着需要审查，并不代表已证实存在恶意行为。

安全与局限

Heimdall 是一种启发式预检工具，并非保证——PASS 并不能证明安全性。能力、来源和 CVE 分析涵盖 JS/TS 和 Python；注入检测与语言无关。经验证的污点／数据流分析仅支持 JS/TS——Python 则回退到能力共现判断（这是一种保守的门控，并非经验证的数据流分析）。 默认情况下，所有操作均离线进行；--online 是唯一的网络调用（它会将依赖项名称和版本发送至 OSV.dev，绝不会发送你的源代码），CVE 匹配依据的是声明的版本范围，而非锁文件。--handshake 会运行不可信代码，并非真正的沙箱。有关完整威胁模型以及如何报告漏洞，请参阅 SECURITY.md。

贡献

新增检测规则是最有价值的贡献——请参阅 CONTRIBUTING.md。参与即表示你同意遵守 行为准则。

许可证

MIT · 由 Çağlar Bozkurt 构建