adamsjack711-ux/pkgxray

## 快速开始 ``` npm install -g pkgxray # or zero-install: npx pkgxray … pkgxray guard npm:express@4.21.0 ``` ``` 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` 判定，则会列出每一项发现 及其对应的文件和证据。} 将其指向一个包，在运行该包的任何代码之前，即可获得附带引证证据的判定结果。 `guard` 会将包暂存于沙箱隔离区中，对暂存的副本进行审计，仅在策略允许时 才将其放行。它绝不运行 `npm install`、生命周期脚本、构建步骤或包代码。 ## 为什么选择 pkgxray？ AI 编程助手以机器速度安装包并连接到 MCP 服务器，通常完全没有人阅读代码—— 而且它们拉取的注册表正遭受工业级规模的攻击：2025 年大约发布了 **455,000 个恶意 npm 包**，到第四季度大约每 20 秒就有一个 ([Sonatype](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 源码一致，来源证明 是否与声明的代码库一致，以及文档中是否带有针对正在阅读它们的 agent 的 提示注入 payload。 它是有意设计得保守的：判定结果来自确定性启发式算法 （判定路径中没有 LLM，因此注入的文本无法操纵它们），仅报告 可引证的证据，并且在下载量排名前 1000 的包上进行的**零启发式误拦截校准** 已[在 CI 中进行回归限制](docs/benchmark.md)。该声明的范围仅限于 安装量最大的包集——它*并不*保证在所有包上都零误拦截； 较新的 MCP/agent 工具生态系统存在过度拦截的情况，目前正在逐案 协调中（[详情](docs/benchmark.md#scope-of-the-claim-read-this-first)）。 ## 检测范围 | 威胁 | 覆盖范围 | pkgxray 的检测方式 | |---|:-:|---| | 凭证窃取 | ✅ | 读取 `.ssh` / `.aws` / `.npmrc` / `.env` / 钥匙串 / 钱包，包括分片路径（`".s"+"sh"`） | | 提示注入 | ✅ | 分层检测文档、注释、元数据；确定性判定路径无法被操纵 | | Unicode 走私 | ✅ | 不可见的标签块字符 + 特洛伊木马源码 bidi / 零宽字符 | | Base64 payload | ✅ | 文档/注释中的编码信封；解码为计算参数 `eval` / `new Function` / `child_process` 的 blob | | 数据窃取与加载器 | ✅ | 跨文件关联：第二阶段加载器、`curl \| sh`、网络接收端附近的 `process.env` 收集、EtherHiding | | 持久化 | ✅ | 写入 shell rc 文件、cron、launch agents | | 代码混淆 | ✅ | 打包的 blob + 计算参数执行；刻意*不*标记单纯的代码压缩 | | 已知 CVE | ✅ | 下载前的 OSV 批量预检；绝不因配置而改变 | | 木马化更新 / 维护者被接管 | ✅ | `recheck` 判定漂移 + 版本漂移监控 | | 产物差异 | ✅ | 对比发布的 npm tarball 与打标签的 GitHub 源码 | | MCP 能力滥用 | ✅ | 清单审计中的能力表面不匹配（例如，一个接受 `command` 参数的 `get_weather`） | | 运行时工具漂移 | ✅ | `mcp-proxy` 在 `tools/list_changed` 时重新审计；拒绝固定清单的漂移 | | 依赖混淆 / 域名抢注 | ◑ | 回调信标、代码库不匹配和来源不匹配信号；无名称相似性启发式算法 | _{✅ 已检测 · ◑ 部分 / 间接} **已知盲点：** pkgxray 分析的是 tarball 中的字节。如果一个包在安装 *之后*才下载其真正的 payload，它可能会发布一个干净的目录树—— 当该能力的特征明确时，pkgxray 会标记该能力，但如果这种风险很重要，请将其 与运行时沙箱结合使用。完整分析： [docs/threat-model.md](docs/threat-model.md)。 ## 超越检测 - **持续监控** —— [`pkgxray recheck`](docs/reference.md#monitoring-pkgxray-recheck) 将已安装的依赖项与存储的判定基准进行比对，并预先审查更新的版本 - **MCP 审查** —— `pkgxray mcp` 在您连接之前审计服务器的工具清单； `--pin` / `--recheck` 用于捕获“暗中替换”行为；`pkgxray-mcp` 直接为任何 agent 提供审计工具 - **运行时网关** —— [`pkgxray mcp-proxy`](docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) 在线上封装实时的 MCP 服务器：剥离被拒绝的工具，每次调用约 0.05 µs 的 判定，以及对工具结果进行注入扫描 - **安装网关** —— 一个 [hookshot](https://github.com/CorridorSecurity/hookshot) 钩子会对 agent 尝试安装的每一个包运行 `guard`，支持 Claude Code、Cursor、Windsurf、Factory Droid 和 Codex ([`examples/hookshot/`](examples/hookshot/)) - **策略引擎** —— 每个表面都会读取一个 `.pkgxray.json`；可自由 收紧，所有放宽的操作都会被打印出来；CVE 绝不能被忽略；失败即关闭 - **可选的行为沙盒** —— [`pkgxray canary`](docs/canary-threat-model.md) 在带有诱饵凭证的 OS 沙箱中运行生命周期脚本；它能够 *确认*恶意，但绝不*放行*包 ## 判定结果 | 判定结果 | 含义 | 建议操作 | |---|---|---| | 🟢 `SAFE` | 无高风险或中风险指标。 | 安装。默认情况下，只有 `safe` 会从隔离区放行。 | | 🟡 `REVIEW` | 证据不完整，或存在需要人工审查的特权能力。 | 在放行前检查隔离的副本。 | | 🔴 `BLOCK` | 高严重性，附带引证证据。 | 不要安装。每一项发现都会指明文件和证据。 | 退出代码稳定且对 CI 友好：**`0`** 安全/允许 · **`2`** 拦截 · **`3`** 审查。完整的信号到严重性映射请参见 [严重性策略](docs/reference.md#severity-policy-what-lands-in-block--review--info)。 ## 使用方法 **在安装前审查 npm 包** ``` pkgxray guard npm:some-package@1.2.3 [--format json] pkgxray guard ./ext --promote-to ./approved/ext # local dir, promote if policy allows ``` **在连接前审查 MCP 服务器** —— 完整指南：[docs/mcp.md](docs/mcp.md) ``` pkgxray mcp --package npm:some-mcp-server@1.4.2 npx some-mcp-server pkgxray mcp --recheck npx some-mcp-server # catch the rug-pull ``` **在 CI/CD 中强制执行** ``` pkgxray audit package-lock.json [--deep] # also: yarn.lock, pnpm-lock.yaml, package.json npx pkgxray recheck package-lock.json # scheduled: exits non-zero only on a regression ``` 一个现成的 GitHub Actions 工作流和可自托管的缓存服务器 （`PKGXRAY_CACHE_URL`）位于[参考文档](docs/reference.md#monitoring-pkgxray-recheck)中。 **守护 AI 编程 agent** ``` { "mcpServers": { "pkgxray": { "command": "pkgxray-mcp" } } } ``` 使用 [hookshot 集成](examples/hookshot/)拦截安装，并使用 [`pkgxray mcp-proxy`](docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy)封装 MCP 服务器。 ## 配置 一个可选的 `.pkgxray.json`，由每个表面读取。零配置意味着 最大严格度。 ``` { "policy": "safe-only", // or "allow-review" (a loosening — warns) "failOn": "review", // CI exit threshold "scanErrorPolicy": "fail-closed", // a scan that errors → review, never safe "allow": [ { "pkg": "left-pad@1.3.0", "sha256": "e0b0…", "reason": "reviewed 2026-07", "expires": "2026-10-01" } ] } ``` 优先级、`mute` / `mcp` 块以及强制不变量： [docs/configuration.md](docs/configuration.md) · [`.pkgxray.example.json`](.pkgxray.example.json) ## 演示 60 秒的演示 —— SAFE 运行、带有退出代码的被拦截木马， 以及 lockfile 审计： https://github.com/user-attachments/assets/b5a323b1-a9ec-4676-9601-1b284df81b6b _{所有截图均为真实运行 —— 重现步骤见 [`docs/screenshots/`](docs/screenshots/README.md)，其中还展示了 MCP 代理、hookshot 安装网关和浏览器扩展的运行情况。} ## 对比 旨在*与* `npm audit` 和 [OSV-Scanner](https://google.github.io/osv-scanner/) *协同*运行， 而不是取代它们——它们将依赖项与已知漏洞进行匹配；pkgxray 添加了 它们未涵盖的层级： | 功能 | npm audit | OSV-Scanner | pkgxray | |---|:-:|:-:|:-:| | 已知 CVE 查询 | ✅ | ✅ | ✅ (OSV，在下载前拦截) | | Lockfile / 项目扫描 | ✅ | ✅ | ✅ | | 注册表签名 / 来源验证 | ✅ (`npm audit signatures`) | — | ✅ (sigstore/SLSA + 代码库交叉检查) | | 包代码行为的静态分析 | — | — | ✅ | | 提示注入与 Unicode 走私检测 | — | — | ✅ | | npm ↔ GitHub 产物差异 | — | — | ✅ | | 安装前对单个包进行隔离 | — | — | ✅ | | 对照存储基准的判定漂移监控 | — | — | ✅ | | MCP 服务器审查与每次调用的运行时网关 | — | — | ✅ | _{根据各工具的公开文档，范围仅限于 npm 供应链审查。 OSV-Scanner 涵盖了 npm 之外的许多生态系统，这是 pkgxray 未做的。} ## 架构 获取（OSV 预检 → 抓取）→ 沙箱隔离 → 静态分析 → 策略 → 判定。相同的引擎支持所有表面：CLI、MCP 服务器、 运行时代理、安装钩子、浏览器扩展和 CI 缓存服务器。 原则：绝不执行不受信任的代码 · 仅限可引证的证据 · 最小化误报 · 失败即关闭 · 零运行时依赖。 详情：[docs/architecture.md](docs/architecture.md) · [docs/design.md](docs/design.md) ## 性能 - **本地静态分析：约 25 ms** —— 对 `express` 的完整 guard 在冷缓存下约为 1.3–1.5 秒， 几乎全是网络往返时间 (Apple M1, Node 26) - **已知存在漏洞的包会在下载前的 OSV 预检阶段被拦截** - **校准**（精确度、召回率、在下载量排名前 1000 的包上实现的 0 启发式误拦截的阈值 —— [范围](docs/benchmark.md#scope-of-the-claim-read-this-first)) 由一个已提交的[基准语料库](benchmark/)测量，如果发生回退则 CI 会失败 完整数据：[docs/reference.md#performance](docs/reference.md#performance) · 方法论：[docs/benchmark.md](docs/benchmark.md) ## 文档 | 文档 | 涵盖内容 | |---|---| | [architecture.md](docs/architecture.md) | 流水线、表面、代码库布局 | | [threat-model.md](docs/threat-model.md) | 范围、盲点、提示注入立场 | | [mcp.md](docs/mcp.md) | MCP 服务器、连接时审查、运行时代理 | | [configuration.md](docs/configuration.md) | `.pkgxray` schema 和不变量 | | [reference.md](docs/reference.md) | 严重性策略、`recheck`、JSON 输出、缓存服务器 | | [benchmark.md](docs/benchmark.md) | 校准基准与真实世界验证 | | [compatibility.md](docs/compatibility.md) | 1.0 兼容性契约 | | [json-schema.md](docs/json-schema.md) | 完整的 `--format json` schema | 请从[文档索引](docs/README.md)开始浏览。长期计划： [采纳指南](docs/adoption.md) 和 GitHub issues。 ## 开发 ``` npm test # zero-dep node --test suite npm run benchmark # calibration corpus: precision/recall + 0-false-block gate npm run build:browser # build the MV3 browser extension ``` ## 安全与许可 发布到 npm 的版本包含来源证明（SLSA 证明），并受限于 测试套件、校准基准以及 pkgxray 自身的供应链守卫。 要报告 pkgxray 本身的漏洞，请参阅 [SECURITY.md](SECURITY.md)。 [MIT](LICENSE)

标签：DNS 反向解析, GNU通用公共许可证, MITM代理, Node.js, URL发现, 云安全监控, 人工智能, 大模型安全, 安全检测, 暗色界面, 用户模式Hook绕过, 网络信息收集, 自定义脚本, 零日漏洞检测, 静态分析