adamsjack711-ux/pkgxray 来源: https://github.com/adamsjack711-ux/pkgxray # pkgxray — npm 包、MCP 服务器和 AI 代理的安装前安全检测 pkgxray — npm 包、MCP 服务器和 AI 代理的安装前安全检测。 使用本地、零依赖的包静态分析，在安装或连接之前检查 npm 包和模型上下文协议 (MCP) 服务器。pkgxray 报告引用的 SAFE、REVIEW 或 BLOCK 证据，在正常扫描期间不执行包代码。 npm 版本 (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) 许可证: MIT 静态分析 · 供应链情报 · 提示注入检测 · MCP 安全 · SAFE / REVIEW / BLOCK 实际运行：guard 清除 [email protected]，然后阻止一个模拟 2024 年 @solana/web3.js 攻击的样本。 ▶ 60 秒快速演示 ## 快速开始 ### 1. 扫描已知安全的包而不安装 pkgxray bash npx --yes [email protected] guard npm:[email protected] 这会通过 npm 的临时 npx 缓存下载 pkgxray，将目标 tarball 放入隔离区，并执行静态和供应链检查。它不会全局安装 pkgxray、运行 npm install、执行生命周期脚本或执行包代码。 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) ... 实际输出，已精简。BLOCK 判决则会列出每个发现的文件及其证据。 ### 2. 读取判决 将其指向一个包，即可获得带引用证据的判决——在该包任何一行代码运行之前。guard 将包放入沙箱隔离区，审计隔离副本，仅当策略允许时才会提升。它从不运行 npm install、生命周期脚本、构建步骤或包代码。 | 判决 | 退出码 | 含义 | |—|—:|—| | SAFE | 0 | 未发现高或中风险指标；默认策略允许提升。 | | REVIEW | 3 | 证据不完整，或某项特权能力需要人工审查。 | | BLOCK | 2 | 高严重性引用证据要求拒绝或深入调查。 | SAFE 并非包无害的证明；静态分析无法看到仅在运行时下载的有效载荷。请参阅威胁模型。 ### 3. 查看提供的惰性夹具上的 BLOCK 从仓库检出： bash npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown 该夹具包含模拟分割字符串 SSH 密钥读取和网络外泄的惰性源文本。它永远不会被执行。命令返回 BLOCK（退出码 2）并引用匹配的文件和证据。 ### 4. 添加到你的工作流 - 扫描拉取请求并安排依赖重新检查。 - 向支持 MCP 的编码代理暴露 pkgxray 的工具。 - 评估实验性的 Hookshot 安装门。 ## 为什么用 pkgxray？ AI 编码助手以机器速度安装包并连接 MCP 服务器，通常人类从未阅读代码。Sonatype 报告称 2025 年在受监控生态系统中新识别出 454,648 个恶意开源包。其 Q4 报告统计当季为 394,877 个，并称 Q4 中 99.8% 的恶意软件源自 npm（年度数据 (https://www.infosecurity-magazine.com/news/454000-malicious-open-source/)；Q4 范围 (https://www.sonatype.com/blog/open-source-malware-index-q4-2025-automation-overwhelms-ecosystems)）。传统防病毒软件检查执行的内容；pkgxray 检查被安装的内容。 npm audit 和 OSV-Scanner 回答一个核心问题——这个包有已知 CVE 吗？——pkgxray 也会问这个问题（通过 OSV，在任何内容下载之前）。但一个刚被植入后门的包还没有 CVE，因此 pkgxray 还分析信任：代码实际做了什么，发布的 npm 制品是否与标记的 GitHub 源匹配，来源证明是否与声明的仓库一致，以及文档是否携带针对阅读它的代理的提示注入载荷。 它故意保守：判决来自确定性启发式（判决路径中无 LLM，因此注入的文本无法引导它们），仅报告可引用的证据，并且在最常下载的前 1000 个包上的零启发式误报校准已在 CI 中通过回归门控。该声明限定在安装量最大的集合——并非声称在所有包上零误报；较新的 MCP/代理工具生态系统存在过度阻止，正在逐案协调（详情）。 ## 它能捕获什么 | 威胁 | 覆盖范围 | pkgxray 如何发现 | |—|:-:|—| | 凭据窃取 | ✅ | 读取 .ssh / .aws / .npmrc / .env / 密钥链 / 钱包，包括分割片段路径（".s"+"sh"） | | 提示注入 | ✅ | 在文档、注释、元数据中的分层检测；确定性的判决路径无法被引导 | | Unicode 走私 | ✅ | 不可见的标签块字符 + Trojan Source 双向/零宽度 | | Base64 载荷 | ✅ | 文档/注释中的编码信封；解码后进入计算参数的 eval / new Function / child_process | | 外泄与加载器 | ✅ | 跨文件关联：阶段 2 加载器、curl | sh、process.env 在网络接收器附近收集、EtherHiding | | 持久化 | ✅ | 写入 shell rc 文件、cron、启动代理 | | 混淆 | ✅ | 打包 blob + 计算参数执行；有意不标记单纯的压缩 | | 已知 CVE | ✅ | 下载前批量 OSV 预检查；配置永远无法改变 | | 被植入后门的更新 / 维护者接管 | ✅ | recheck 判决漂移 + 版本漂移监控 | | 制品偏差 | ✅ | 发布的 npm tarball 与标记的 GitHub 源进行对比 | | MCP 能力滥用 | ✅ | 清单审计中的能力-表面不匹配（一个既做 get_weather 也接受 command 的接口） | | 运行时工具漂移 | ✅ | mcp-proxy 在 tools/list_changed 时重新审计；固定清单的漂移被拒绝 | | 序列级工具调用链 | ◑ | mcp-proxy 对每次调用进行门控并扫描结果；无跨调用流分析——诚实限制 | | 依赖混淆 / 拼写钓鱼 | ◑ | 回调信标、仓库不匹配和来源不匹配信号；无名相似度启发式 | ✅ 已检测 · ◑ 部分/间接 已知盲点： pkgxray 基于 tarball 中的字节进行推理。一个在安装后才下载实际载荷的包可以提供一个干净的树——当形状明确时，pkgxray 会标记该能力，但在该风险重要时，请搭配运行时沙箱一起使用。完整分析：docs/threat-model.md。 ## 超越检测 - 持续监控 — pkgxray recheck 将已安装的依赖与存储的判决基线进行差异比较，并预先审查更新版本 - MCP 审查 — pkgxray mcp 在连接前审计服务器的工具清单；--pin / --recheck 捕获 rug-pull；pkgxray-mcp 直接向任何代理提供审计工具 - 运行时门控 — pkgxray mcp-proxy 在线上包裹实时 MCP 服务器：拒绝的工具被剥离，每次调用判决约 0.05 μs，对工具结果进行注入扫描 - 安装门控 — 一个 hookshot (https://github.com/CorridorSecurity/hookshot) 钩子在代理尝试安装的每个包上运行 guard，覆盖 Claude Code、Cursor、Windsurf、Factory Droid 和 Codex（examples/hookshot/） - 策略引擎 — 一个 .pkgxray.json 被每个表面读取；可自由收紧，每次放松都会打印；CVE 永远不能被允许绕过；失败关闭 - 可选的行为金丝雀 — pkgxray canary 在操作系统沙箱中运行生命周期脚本，并带有诱饵凭据；它可以确认恶意性，但从不清除一个包 ## 判决 | 判决 | 含义 | 你应该 | |—|—|—| | 🟢 SAFE | 未发现高或中风险指标。 | 安装。默认只有 safe 能提升出隔离区。 | | 🟡 REVIEW | 证据不完整，或某项需要人工干预的特权能力。 | 检查隔离副本后再提升。 | | 🔴 BLOCK | 高严重性的引用证据。 | 不要安装。每个发现都注明文件和证据。 | 退出码稳定且 CI 友好：0 安全/允许 · 2 阻止 · 3 审查。完整的信号到严重性映射见严重性策略。 ## 使用 在安装前审查 npm 包 bash pkgxray guard npm:[email protected] [--format json] pkgxray guard ./ext --promote-to ./approved/ext # 本地目录，若策略允许则提升 在连接前审查 MCP 服务器 — 完整指南：docs/mcp.md bash pkgxray mcp --package npm:[email protected] npx some-mcp-server pkgxray mcp --recheck npx some-mcp-server # 捕获 rug-pull 在 CI/CD 中强制执行 bash pkgxray audit package-lock.json [--deep] # 同样支持：yarn.lock, pnpm-lock.yaml, package.json npx pkgxray recheck package-lock.json # 定时执行：仅当出现回归时非零退出 现成的 GitHub Actions 集成 和可自托管的缓存服务器（PKGXRAY_CACHE_URL）在参考中有文档说明。 保护 AI 编码代理 pkgxray 已在 MCP 注册表 (https://registry.modelcontextprotocol.io) 上以 io.github.adamsjack711-ux/pkgxray 发布。将其添加到任何 MCP 客户端——本地安装（pkgxray-mcp）或通过 npx 零安装： json { "mcpServers": { "pkgxray": { "command": "npx", "args": ["--yes", "--package", "[email protected]", "pkgxray-mcp"], "env": { "PKGXRAY_MCP_ALLOWED_ROOTS": "/absolute/path/to/project" } } } } MCP 指南解释了操作者拥有的文件系统边界。产品特定设置在编码代理集成指南中。通过 Hookshot 集成 门控安装，并使用 pkgxray mcp-proxy 包裹 MCP 服务器。 ## 配置 一个可选的 .pkgxray.json，被每个表面读取。零配置意味着最大严格程度。 jsonc { "policy": "safe-only", // 或 "allow-review"（一种放宽——会警告） "failOn": "review", // CI 退出阈值 "scanErrorPolicy": "fail-closed", // 扫描出错 → review，永远不会 safe "allow": [ { "pkg": "[email protected]", "sha256": "e0b0...", "reason": "reviewed 2026-07", "expires": "2026-10-01" } ] } 优先级、mute / mcp 块以及强制不变量的细节：docs/configuration.md · .pkgxray.example.json ## 演示 60 秒快速演示——SAFE 运行、阻止的木马及其退出码、然后是锁文件审计： https://github.com/user-attachments/assets/b5a323b1-a9ec-4676-9601-1b284df81b6b 所有捕获都是实际运行——复现步骤在 docs/screenshots/ 中，同时展示了 MCP 代理、hookshot 安装门和浏览器扩展的实际效果。 ## 比较 npm audit 和 OSV-Scanner (https://google.github.io/osv-scanner/) 将依赖与已知 CVE 匹配——这是一个不同的问题，回答得很好。pkgxray 设计为与其并行运行，而非替代（它自己查询 OSV，在下载任何内容之前）。有意义的比较是针对同一领域的工具——行为供应链审查： | 能力 | Socket.dev | OpenSSF Package Analysis | Cisco MCP Scanner | pkgxray | |—|:-:|:-:|:-:|:-:| | 完全本地、零依赖、无账户或云上传 | — ¹ | ◑ ² | ◑ ³ | ✅ | | 包代码的静态行为分析 | ✅ | ✅ | ✅ | ✅ | | 沙箱执行（动态分析） | — | ✅ ⁴ | ◑（可选 Docker） | ◑（可选 canary）⁴ | | npm ↔ GitHub 制品偏差 | 未知 | — | — | ✅ | | 确定性判决路径——注入无法引导的 LLM | — ⁵ | ✅ | ◑ ⁵ | ✅ | | 带隔离副本审查的安装前门 | ◑ ⁶ | — | — | ✅ | | 连接前的 MCP 服务器审查 | — ⁷ | — | ✅ | ✅ | | 实时 MCP 流量的每次调用运行时门控 | — | — | — ⁸ | ✅（mcp-proxy） | | 与存储基线对比的判决漂移监控 | ✅（云端） | — | — | ✅（本地 recheck） | 比较日期 2026-07-21，基于每个工具的公开文档；未知意味着未公开记录——未验证任何方向。 ¹ Socket 的分析在其云端运行；Socket Firewall 不需要账户，但每次安装都会咨询 Socket 托管的分析。 ² 开源且可自托管，但构建为注册表规模的分析流水线（Docker/gVisor），而非安装时的开发者门。 ³ YARA 分析器本地运行；LLM 作为法官和 Cisco AI Defense 分析器需要 API 密钥。 ⁴ 两者都在操作系统沙箱中引爆包。pkgxray 的可选 canary 运行两个阶段——安装时的生命周期脚本以及导入包入口点——带有诱饵凭据，因此触发并观察到恶意-on-first-require（flatmap-stream）形态，这正是 pkgxray 声明的盲点。出站现在在两个平台上都由内核限制：macOS 上的 sandbox-exec 以及 Linux 上使用 bubblewrap + iproute2 的私有网络命名空间（bwrap+netns），其中绕过代理的原始套接字拨号被内核拒绝（ENETUNREACH），同时代理的出站仍被捕获。该层级仅在环境中的运行时自测证明其有效后才启用（使用 node scripts/verify-netns-confinement.js 验证）；缺少该工具则回退为纯观察并给出提示。仍为 ◑——不是因为限制间隙，而是设计如此：canary 是可选且仅确认（它证明恶意性，从不清除一个包），并且在没有安装依赖的情况下引爆，而 OpenSSF Package Analysis 运行在注册表规模且默认开启。将它们作为互补——pkgxray 在安装前，完整的动态分析在该风险重要时。 ⁵ Socket 的基于 LLM 的代码检查是其标志性功能（“AI 检测的潜在恶意软件”，人工确认）；Cisco 的纯 YARA 模式是确定性的，其 LLM 分析器则不是。 ⁶ Socket Firewall 在安装时阻止风险包；它不提供用于人工审查的隔离副本。 ⁷ Socket 的 MCP 产品将其包评分 API 暴露给代理；它不在连接时审查任意 MCP 服务器。 ⁸ 根据其文档，Cisco MCP Scanner 仅用于分析——它不代理或门控实时 MCP 流量。 ## 架构 获取（OSV 预检查 → 获取）→ 沙箱隔离 → 静态分析 → 策略 → 判决。同一引擎支撑所有表面：CLI、MCP 服务器、运行时代理、安装钩子、浏览器扩展和 CI 缓存服务器。原则：永不执行不受信任的代码 · 仅可引用证据 · 最小化误报 · 失败关闭 · 零运行时依赖。 细节：docs/architecture.md · docs/design.md ## 性能 - 本地静态分析：约 25 毫秒 — 完整 guard express 冷缓存约 1.3–1.5 秒，几乎全是网络往返（Apple M1，Node 26） - 已知漏洞包在下载前的 OSV 预检查中阻断 - 校准（精确率、召回率、前 1000 个最常下载包的零启发式误报门——范围）通过承诺的基准测试语料库进行测量，该语料库失败