<div align="center"> <img src="https://raw.githubusercontent.com/adamsjack711-ux/pkgxray/main/docs/banner.png" alt="pkgxray — 在安装前分析软件包" width="820"> # pkgxray —— npm 包、MCP 服务器和 AI 代理的安装前安全检测 在安装或连接 npm 包、MCP 服务器**之前**检查它们，并获得 基于证据的确定性 `SAFE`、`REVIEW` 或 `BLOCK` 判定。 本地、零依赖的静态分析 —— 常规扫描从不执行包代码。 [](https://www.npmjs.com/package/pkgxray) [](https://www.npmjs.com/package/pkgxray) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-test.yml) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-benchmark.yml) [](LICENSE) [**网站**](https://pkgxray.ca) · [**文档**](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md) · [**校准**](https://pkgxray.ca/stats) · [**报告问题**](https://github.com/adamsjack711-ux/pkgxray/issues) <img src="https://assets.kitploit.com/production/public/readmes/43061/49ce4b9fed6753583cc0f87fd2c64c556d14806d31791844eaeefc14f7c4749e.gif" alt="pkgxray guard 以 SAFE A+ 判定放行 [email protected]，然后以 BLOCK F 判定和高危凭据获取发现阻止一个投毒的示例包" width="820"> <sub>真实运行：<code>guard</code> 放行 <code>[email protected]</code>，随后阻止一个模拟 2024 年 <code>@solana/web3.js</code> 事件的示例包。</sub> </div> ## 亮点 - **零运行时依赖** —— 纯 Node，完全在你的机器上运行（静态扫描约 25 ms）。 - **常规扫描从不执行包代码** —— tarball 在隔离区中以字节流方式读取。 - **确定性、带引用的判定** —— 每项发现都会指明文件和证据；判定路径中不涉及 LLM，因此注入的文本无法左右结果。 - **为代理时代而生** —— 在连接前审查 MCP 服务器，为代理执行的安装把关，并重新审查实时的 MCP 流量。 - **经过校准并有回归门禁** —— 在下载量最高的前 1000 个包上零启发式误拦截，由 CI 强制执行。 > **[1. 快速开始](#quick-start)** · [2. 扫描与检测内容](#what-it-scans--detects) · [3. 判定](#verdicts) · [4. 用法](#usage) · [5. 集成](#integrations) · [6. 对比](#how-it-compares) · [7. 文档](#documentation) ## 为什么 AI 编码助手以机器速度安装软件包并连接 MCP 服务器，通常没有人类阅读代码。Sonatype 在 2025 年识别出**受监控生态系统中超过 454,600 个新增恶意开源软件包**，其中超过 99% 位于 npm （[Sonatype](https://www.sonatype.com/state-of-the-software-supply-chain/2026/open-source-malware)）。 `npm audit` 回答的是*“是否存在已知 CVE？”*；pkgxray 还会在安装前回答*“这段代码实际上做了什么”*。 ## 快速开始 **1. 扫描一个已知良性的包**（无需安装 pkgxray）： ```bash npx --yes [email protected] guard npm:[email protected] ``` 它会在隔离区中暂存 tarball 并运行静态和供应链检查 —— 不执行 `npm install`、不运行生命周期脚本、不执行任何包代码。 <details> <summary>示例输出</summary> ```text 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) ``` </details> **2. 阅读判定：** | 判定 | 退出码 | 含义 | |---|---:|---| | `SAFE` | `0` | 无高危或中危指标；默认策略允许放行。 | | `REVIEW` | `3` | 证据不完整，或特权能力需要人工审查。 | | `BLOCK` | `2` | 存在高严重性且带引用的证据 —— 拒绝或调查。 | `SAFE` 并不证明某个包无害；静态分析无法看到仅在运行时下载的有效载荷。参见[威胁模型](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md)。 **3. 在随附的惰性测试样本上查看 BLOCK：** ```bash npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown ``` 该测试样本是模拟拆分字符串 SSH 密钥读取和外传的惰性源码文本 —— **它永远不会被执行**。它返回 `BLOCK`（退出码 `2`）并附上引用的文件和证据。 **4. 将其加入你的工作流** —— [复查与 CI](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck)、 [MCP](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#the-pkgxray-mcp-server)、[Hookshot 安装门禁](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot)。 > **两种执行模型。** 默认的 `guard` 和 `audit` 扫描是**静态**的 —— > 从不执行包代码。枚举 MCP 服务器可能会启动它，`mcp-proxy` 会在门禁后运行它；可选的 > [`canary`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) 是唯一有意**执行**包的例外， > 它会在沙箱中运行以确认行为 —— 它能确认恶意，但永远无法证明某个包是安全的。完整边界：[SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md#scope)。 ## 扫描与检测内容 **扫描** —— `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 能力面滥用。 完整的覆盖矩阵 —— 以及已知的“后续下载”盲区 —— 见[威胁模型](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md)；并排对比表见[网站](https://pkgxray.ca/#catches)。 ## 判定 | 判定 | 你应该 | |---|---| | `SAFE` | 安装。默认只有 `safe` 能从隔离区放行。 | | `REVIEW` | 在放行前检查隔离区中的副本。 | | `BLOCK` | 不要安装。每项发现都会指明文件和证据。 | 退出码稳定且适合 CI：**`0`** 安全/允许 · **`2`** 阻止 · **`3`** 复查。 ## 用法 ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [`.pkgxray.example.json`](https://github.com/adamsjack711-ux/pkgxray/blob/main/.pkgxray.example.json)。 ## 集成 每个入口背后都是同一个引擎。“Works with”表示有文档化的设置指南，而非厂商背书的集成。 | 位置 | 功能 | 指南 | |---|---|---| | 编码代理 —— Codex、Claude Code、Cursor、Windsurf | 为安装把关，并向代理开放审计工具 | [coding-agents.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/coding-agents.md) | | MCP 客户端 | 在连接前审查服务器；也可将 pkgxray 本身作为 MCP 服务器运行 | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) | | GitHub Actions / CI | 当依赖越过策略时让构建失败 | [github-actions.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/github-actions.md) | | 安装门禁 —— Hookshot | 对代理尝试安装的每个包运行 `guard` | [examples/hookshot/](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot) | | 运行时 MCP 门禁 | 代理一个实时 MCP 服务器，并为每次工具调用把关 | [`mcp-proxy`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) | | 依赖监控 | 定时重新审查已安装的依赖，并在升级前预先审查 | [`recheck`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck) | ## 对比 请将 pkgxray 与 `npm audit` / OSV-Scanner **并行**使用，而不是替代它们 —— 它们回答的是*“已知 CVE？”*。与同类工具（行为型供应链审查 —— Socket.dev、OpenSSF Package Analysis、Cisco MCP Scanner）的完整能力对比见 [docs/comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) 和[网站](https://pkgxray.ca/#comparison)。 ## 证据 **在下载量最高的前 1000 个包上的零启发式误拦截校准**由 CI 进行回归门禁（[范围与方法](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md)），已发布的运行结果位于 [pkgxray.ca/stats](https://pkgxray.ca/stats)。该声明仅限于被安装最多的集合 —— 并非声称所有包都零误拦截。 ## 文档 | 文档 | 内容 | |---|---| | [architecture.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/architecture.md) · [design.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design.md) | 流水线、入口、原则 | | [threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) | 范围、盲区、提示注入立场 | | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) · [mcp-registry.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp-registry.md) | MCP 审查、运行时代理、注册表条目 | | [canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) | 可选的行为型 canary | | [configuration.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [reference.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md) | `.pkgxray.json`、严重性策略、`recheck`、缓存服务器 | | [benchmark.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md) · [comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) | 校准与对比 | | [compatibility.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/compatibility.md) · [json-schema.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/json-schema.md) | 1.0 契约、`--format json` 模式 | 从[文档索引](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md)开始。 ## 贡献 ```bash npm test # 零依赖 node --test 套件 npm run benchmark # 校准语料库：精确率/召回率 + 零误拦截门禁 npm run validate:website # 重新生成并校验校准页面 ``` 欢迎提交 Pull Request —— 请阅读 [CONTRIBUTING.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/CONTRIBUTING.md) 和 [行为准则](https://github.com/adamsjack711-ux/pkgxray/blob/main/CODE_OF_CONDUCT.md)。按 [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md) 的规定私下报告漏洞。发布版以带出处（SLSA 证明）的形式发布到 npm，并以测试、校准基准和 pkgxray 自身的供应链守卫作为门禁。 <div align="center"> <sub>由 <a href="https://github.com/adamsjack711-ux">Jack Adams-Lovell</a> 构建 · <a href="https://github.com/adamsjack711-ux/pkgxray/blob/main/LICENSE">MIT</a> · <a href="https://pkgxray.ca">pkgxray.ca</a></sub> </div>
