pkgxray —— npm 包、MCP 服务器和 AI 代理的安装前安全检测

在安装或连接 npm 包、MCP 服务器之前检查它们，并获得 基于证据的确定性 SAFE、REVIEW 或 BLOCK 判定。 本地、零依赖的静态分析 —— 常规扫描从不执行包代码。

网站 · 文档 · 校准 · 报告问题

_{真实运行：guard 放行 [email protected]，随后阻止一个模拟 2024 年 @solana/web3.js 事件的示例包。}

亮点

• 零运行时依赖 —— 纯 Node，完全在你的机器上运行（静态扫描约 25 ms）。
• 常规扫描从不执行包代码 —— tarball 在隔离区中以字节流方式读取。
• 确定性、带引用的判定 —— 每项发现都会指明文件和证据；判定路径中不涉及 LLM，因此注入的文本无法左右结果。
• 为代理时代而生 —— 在连接前审查 MCP 服务器，为代理执行的安装把关，并重新审查实时的 MCP 流量。
• 经过校准并有回归门禁 —— 在下载量最高的前 1000 个包上零启发式误拦截，由 CI 强制执行。

1. 快速开始 · 2. 扫描与检测内容 · 3. 判定 · 4. 用法 · 5. 集成 · 6. 对比 · 7. 文档

为什么

AI 编码助手以机器速度安装软件包并连接 MCP 服务器，通常没有人类阅读代码。Sonatype 在 2025 年识别出受监控生态系统中超过 454,600 个新增恶意开源软件包，其中超过 99% 位于 npm （Sonatype）。 npm audit 回答的是*“是否存在已知 CVE？”；pkgxray 还会在安装前回答“这段代码实际上做了什么”*。

快速开始

1. 扫描一个已知良性的包（无需安装 pkgxray）：

npx --yes [email protected] guard npm:[email protected]

它会在隔离区中暂存 tarball 并运行静态和供应链检查 —— 不执行 npm install、不运行生命周期脚本、不执行任何包代码。

Decision: SAFE   Grade: A+ (99/100)
No high- or medium-risk indicators were found in the provided evidence.

Notes:
- INFO npm-vs-github-clean — npm tarball matches the linked GitHub repo at the
  published version. (15/16 files match GitHub @4.21.0)

2. 阅读判定：

SAFE 并不证明某个包无害；静态分析无法看到仅在运行时下载的有效载荷。参见威胁模型。

3. 在随附的惰性测试样本上查看 BLOCK：

npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown

该测试样本是模拟拆分字符串 SSH 密钥读取和外传的惰性源码文本 —— 它永远不会被执行。它返回 BLOCK（退出码 2）并附上引用的文件和证据。

4. 将其加入你的工作流 —— 复查与 CI、 MCP、Hookshot 安装门禁。

两种执行模型。 默认的 guard 和 audit 扫描是静态的 —— 从不执行包代码。枚举 MCP 服务器可能会启动它，mcp-proxy 会在门禁后运行它；可选的 canary 是唯一有意执行包的例外， 它会在沙箱中运行以确认行为 —— 它能确认恶意，但永远无法证明某个包是安全的。完整边界：SECURITY.md。

扫描与检测内容

扫描 —— pkgxray guard npm:name@version、github:owner/repo、本地目录、整个锁文件（npm、yarn、pnpm）、MCP 服务器和 AI 代理扩展。

检测 —— 凭据窃取（包括拆分片段路径）、云实例元数据与密钥存储收集、提示注入、Unicode 走私、base64 载荷与阶段二加载器、外传、持久化（shell 配置文件、操作系统调度器和被注入的 CI/CD 工作流）、自删除投放器、注册表蠕虫式复制（安装时执行 npm publish）、混淆的计算参数执行、已知 CVE（通过 OSV，在下载前）、npm↔GitHub 产物不一致、被投毒的更新（recheck）以及 MCP 能力面滥用。

完整的覆盖矩阵 —— 以及已知的“后续下载”盲区 —— 见威胁模型；并排对比表见网站。

判定

退出码稳定且适合 CI：0 安全/允许 · 2 阻止 · 3 复查。

用法

pkgxray guard npm:[email protected] [--format json]   # 安装前审查软件包
pkgxray mcp --package npm:[email protected] npx some-mcp-server   # 审查 MCP 服务器；--recheck 可捕捉“rug-pull”变脸攻击
pkgxray audit package-lock.json [--deep]               # 也支持：yarn.lock、pnpm-lock.yaml、package.json
pkgxray recheck package-lock.json                      # 定时执行：仅在出现回归时返回非零

一个可选的 .pkgxray.json（所有入口都会读取）用于调整策略；零配置意味着最大严格度。CVE 永远无法被豁免，任何放宽都会打印出来，扫描出错时会安全失败，判定为 review。模式与不变量： configuration.md · .pkgxray.example.json。

集成

每个入口背后都是同一个引擎。“Works with”表示有文档化的设置指南，而非厂商背书的集成。

对比

请将 pkgxray 与 npm audit / OSV-Scanner 并行使用，而不是替代它们 —— 它们回答的是*“已知 CVE？”*。与同类工具（行为型供应链审查 —— Socket.dev、OpenSSF Package Analysis、Cisco MCP Scanner）的完整能力对比见 docs/comparison.md 和网站。

证据

在下载量最高的前 1000 个包上的零启发式误拦截校准由 CI 进行回归门禁（范围与方法），已发布的运行结果位于 pkgxray.ca/stats。该声明仅限于被安装最多的集合 —— 并非声称所有包都零误拦截。

文档

从文档索引开始。

贡献

npm test                 # 零依赖 node --test 套件
npm run benchmark        # 校准语料库：精确率/召回率 + 零误拦截门禁
npm run validate:website # 重新生成并校验校准页面

欢迎提交 Pull Request —— 请阅读 CONTRIBUTING.md 和 行为准则。按 SECURITY.md 的规定私下报告漏洞。发布版以带出处（SLSA 证明）的形式发布到 npm，并以测试、校准基准和 pkgxray 自身的供应链守卫作为门禁。