pkgxray

pkgxray — 为 npm 软件包、MCP 服务和 AI Agent 提供安装前安全检查

在安装或连接 npm 软件包或 MCP 服务之前进行检查。 你将获得由固定规则判定、并有引用证据支持的 SAFE、REVIEW 或 BLOCK 结论。分析采用静态方式，在你的机器上运行，无需安装 npm 依赖。内置固定版本、采用 MIT 许可证的 Acorn 解析器。常规扫描绝不会执行软件包代码。

网站 · 文档 · 校准 · 报告 Bug

_{实际运行：guard 放行 [email protected]，随后拦截一个仿照 2024 年 @solana/web3.js 安全事件的样本。}

亮点

• 无需安装 npm 依赖 — 使用内置固定版本的 JavaScript 解析器进行本地 Node 分析。
• 安装经过批准的字节内容 — pkgxray install 扫描 npm 锁文件，在离线状态下禁用脚本并安装暂存的归档文件，然后验证生成的文件。
• 常规扫描绝不执行软件包代码 — tarball 在隔离区内按字节读取。
• 由固定规则给出的引用结论 — 每项发现都会标明文件和证据。结论不由模型判定，因此植入软件包的文本无法左右结论。
• 为 Agent 时代打造 — 在连接 MCP 服务前进行检查、拦截 Agent 发起的安装，并重新审计实时 MCP 流量。
• 公开跟踪对抗性漏洞 — 另外 200 个合成案例用于跟踪已检测到的攻击及其无害对照；这是内部测试，并非独立审计。
• 回归门禁 — 校准和对抗性语料库在 CI 中运行；历史前 1000 名的结果仍可用于比较。

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

为什么需要 pkgxray

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 会在沙箱中执行软件包，以确认其行为。Canary 可以确认软件包是否恶意，但永远无法证明软件包是安全的。完整边界：SECURITY.md。

扫描与检测内容

扫描 — pkgxray guard npm:name@version 或 pypi:name@version、 github:owner/repo、本地目录、跨两个生态系统的完整锁文件（npm：package-lock.json、yarn.lock、pnpm-lock.yaml、package.json；PyPI： requirements.txt、poetry.lock、Pipfile.lock、pyproject.toml）、MCP 服务和 AI Agent 扩展。

检测 — 凭据窃取（包括拆分片段路径）、云实例元数据和密钥存储窃取、提示词注入、Unicode 隐写、Base64 有效载荷和二阶段加载器、数据外传、持久化（Shell 配置文件、操作系统调度程序和注入的 CI/CD 工作流）、自删除投放器、注册表蠕虫传播（安装时执行 npm publish）、npm 安装钩子和 PyPI setup.py 安装时执行、混淆的计算参数执行、臆造或 slopsquat 名称（锁文件中固定了注册表从未发布的软件包）、已知 CVE（下载前通过 OSV 检查）、npm↔GitHub 工件不一致、被植入木马的更新（recheck），以及 MCP 能力面滥用。

完整的覆盖范围矩阵见威胁模型，其中也说明了已知盲点：之后才下载有效载荷的软件包。请访问网站查看并排对比表。

判定结果

退出码稳定，适用于 CI：0 安全/允许 · 2 阻止 · 3 复核。

用法

pkgxray guard npm:[email protected] [--format json]   # vet a package before install
pkgxray guard pypi:[email protected]                  # same, for a PyPI package (sdist staged + scanned)
pkgxray mcp --package npm:[email protected] npx some-mcp-server   # vet an MCP server; --recheck catches the rug-pull
pkgxray audit package-lock.json [--deep-all]               # also: yarn.lock, pnpm-lock.yaml, package.json
pkgxray audit requirements.txt [--deep]                # PyPI: also poetry.lock, Pipfile.lock, pyproject.toml
pkgxray recheck package-lock.json                      # scheduled: non-zero only on a regression

audit 会根据 OSV 检查已解析的依赖项。--deep 会为被阻止的依赖项添加源代码扫描；--deep-all 会请求扫描所有已解析依赖项的源代码。深度扫描失败或源代码收集不完整时，结果为 REVIEW，除非结果已是 BLOCK。guard --deps 会将直接依赖项的发现纳入判定；仅检查精确固定的版本，范围版本和其他未解析的来源会保持 REVIEW。Guard 输出会列出已完成、部分完成、已禁用和失败的检查，因此通过判定并不意味着未运行的检查也已通过。 PyPI 扫描涵盖源代码分发包清单、漏洞元数据和文本级注入检查；不提供完整的 Python 模块行为分析或 wheel 检查。Python 源代码会新增 unsupported-behavior REVIEW 发现。行为覆盖缺口无法通过 allow-review 屏蔽或升级；对固定构件的批准仍属于操作员的明确覆盖。包含链接或特殊文件的归档会被拒绝。

一个可选的 .pkgxray.json 可调整基于 Node 的界面上的策略。浏览器扩展会使用引擎默认设置扫描提供的证据，且无法读取项目配置。不提供配置时，将采用最严格的设置。配置绝不会允许忽略 CVE，每次放宽都会打印出来，扫描出错时会以 review 结果失败关闭。架构和规则见： configuration.md · .pkgxray.example.json。

集成

每个入口点背后都使用同一引擎。“适用于”表示提供了文档化的设置指南，并不代表获得供应商背书。

对比

npm audit 和 OSV-Scanner 会检查已发布的 CVE，pkgxray 并不能取代它们。请将其与这些工具一同运行。同类工具包括 Socket.dev、OpenSSF Package Analysis 和 Cisco MCP Scanner，它们也会分析包代码的行为。完整的功能对比见 docs/comparison.md 和 网站。

证据

历史性的前 1000 个包运行结果及其范围和方法 仍可在 pkgxray.ca/stats 查看。这些结果早于基于解析器的流程引擎，且此次变更后尚未重新运行。 当前引擎通过了全部 270 个内部合成校准／挑战测试样例，没有将恶意样例判为 SAFE，也没有将良性样例判为 BLOCK；许多恶意样例会产生 REVIEW。这是回归测试证据，并非真实世界检测率估算。

文档

从文档索引开始。

贡献

npm test                 # zero-dep node --test suite
npm run benchmark        # calibration corpus: precision/recall + 0-false-block gate
npm run validate:website # regenerate + validate the calibration pages

欢迎提交拉取请求。请先阅读 CONTRIBUTING.md 和 行为准则。请按照 SECURITY.md 中的说明， 私下报告漏洞。版本发布时会通过来源证明（SLSA 证明）发布到 npm， 且每次发布都必须通过测试、校准基准测试以及 pkgxray 自身的供应链防护。