# https://github.com/adamsjack711-ux/pkgxray 项目说明书

生成时间：2026-07-25 20:28:30 UTC

## 目录

- [项目概览与快速上手](#page-1)
- [系统架构与流水线](#page-2)
- [CLI 命令、审计与监控](#page-3)
- [MCP 服务器、运行时代理与 MCP Registry](#page-4)
- [配置、策略与策略引擎](#page-5)
- [安装拦截、Hookshot 与浏览器扩展](#page-6)
- [威胁模型、检测能力与已知盲点](#page-7)
- [校准、基准与持续验证](#page-8)

<a id='page-1'></a>

## 项目概览与快速上手

### 相关页面

相关主题：[系统架构与流水线](#page-2), [CLI 命令、审计与监控](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/README.md)
- [CHANGELOG.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/CHANGELOG.md)
- [package.json](https://github.com/adamsjack711-ux/pkgxray/blob/main/package.json)
- [examples/onboarding-malicious.json](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/onboarding-malicious.json)
- [bin/pkgxray.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/bin/pkgxray.js)
- [src/cli.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/cli.js)
- [src/mcp-server.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/mcp-server.js)
</details>

# 项目概览与快速上手

## 项目定位与目标

`pkgxray` 是一个面向 npm 生态的**恶意软件包依赖扫描与取证分析工具**，通过解析 `package.json`、安装产物（lockfile / `node_modules`）以及包元数据，对 JavaScript/Node.js 项目的第三方依赖进行静态与启发式检测，输出可疑脚本、可疑生命周期钩子（`preinstall`、`postinstall`、`install`）以及最终裁决（verdict）。

工具以单一 CLI 二进制形式分发，同时兼容作为 **Model Context Protocol (MCP)** 服务器运行，供 AI 代理（如 Claude Desktop、其他 MCP Host）按需调用扫描能力。`package.json` 中的 `mcpName` 字段被声明为 `io.github.adamsjack711-ux/pkgxray`，用于 MCP Registry 的所有权验证。

资料来源：[package.json:1-80]()，[README.md:1-40]()

## 核心能力矩阵

| 能力维度 | 触发命令 / 接口 | 适用场景 |
| --- | --- | --- |
| 单包扫描 | `pkgxray scan <pkg>` | 审查某个依赖是否含可疑脚本 |
| 项目全量扫描 | `pkgxray scan ./my-app` | CI 中对 lockfile / `node_modules` 进行审计 |
| MCP 协议暴露 | `pkgxray mcp-server` | 通过 stdio 让 MCP Host 调用工具 |
| 报告输出 | `--format json\|sarif\|text` | 接入安全仪表盘 / IDE 插件 |

工具的判定结果以 JSON 报告呈现，字段通常包含 `package`、`version`、`signals[]`、`severity`、`verdict`，便于二次处理。仓库提供示例工件 `examples/onboarding-malicious.json` 作为测试样本与 CI fixture。

资料来源：[src/cli.js:1-60]()，[examples/onboarding-malicious.json:1-30]()

## 安装与首次运行

**环境要求**：Node.js ≥ 18（依据 `package.json` 中 `engines` 声明）。全局安装：

```bash
npm install -g pkgxray
# 或免安装直接通过 npx 调用
npx -y pkgxray mcp-server
```

安装完成后，可执行入口 `bin/pkgxray.js` 会暴露两个命令：`pkgxray`（主 CLI）和 `pkgxray-mcp`（MCP stdio 服务器，行为与 `pkgxray mcp-server` 完全等价，仅用于脚本中显式区分）。

最小化验证步骤：

1. 执行 `pkgxray --version` 确认版本号（v1.0.4+）。
2. 执行 `pkgxray scan ./examples/onboarding-malicious.json` 观察裁决结果。
3. 在 MCP Host 的配置文件中加入 `io.github.adamsjack711-ux/pkgxray` 服务条目，验证工具列表。

资料来源：[bin/pkgxray.js:1-40]()，[README.md:40-90]()

## 版本演进与 MCP 集成要点

最新发布版本 **v1.0.4** 聚焦于 MCP 生态适配，未改动检测/依赖/裁决逻辑（"No detection, dependency, or verdict" 变更），主要包括：

- 新增 `pkgxray mcp-server` 子命令，以 stdio 模式运行服务器。
- 保留旧入口 `pkgxray-mcp`，确保现有脚本不中断。
- 在 `package.json` 中加入 `mcpName` 字段，配合 [MCP Registry](https://registry.modelcontextprotocol.io) 完成上架与所有权核验。
- 允许 MCP Host 使用 `npx -y pkgxray mcp-server` 实现零安装启动。

```mermaid
flowchart LR
  Host[MCP Host<br/>Claude Desktop 等] -->|stdio JSON-RPC| Srv[pkgxray mcp-server]
  Srv --> Scan[scan / analyze 工具]
  Scan --> Report[verdict JSON]
  Report --> Host
```

该架构让 pkgxray 既可作为命令行工具独立运行，也可被 AI 代理按需调用，适合在"代码审计 + LLM 辅助"工作流中嵌入使用。

资料来源：[CHANGELOG.md:1-30]()，[src/mcp-server.js:1-50]()，[package.json:30-80]()

---

<a id='page-2'></a>

## 系统架构与流水线

### 相关页面

相关主题：[CLI 命令、审计与监控](#page-3), [威胁模型、检测能力与已知盲点](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/architecture.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/architecture.md)
- [docs/architecture.svg](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/architecture.svg)
- [docs/design.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design.md)
- [src/auditor.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/auditor.js)
- [src/sandbox.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/sandbox.js)
- [src/quarantine.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/quarantine.js)
</details>

# 系统架构与流水线

## 概述与设计目标

pkgxray 是一款面向 npm 生态的软件包安全审计工具，其系统设计围绕"静态检测 + 隔离执行"双轨思路展开。工具通过解析 `package.json`、锁定文件以及依赖树，结合沙箱化执行环境，输出对每个软件包的可重复、可机读的裁决（verdict）。整体架构遵循"检测层、执行层、裁决层"的关注点分离原则，便于独立扩展检测规则或替换沙箱后端。资料来源：[docs/design.md:1-40]()

从 v1.0.4 版本开始，pkgxray 引入了 MCP（Model Context Protocol）服务器模式，允许宿主以 stdio 协议将工具作为子进程拉起，实现零安装接入。该模式与本地 CLI 流水线复用同一套检测/裁决核心，避免逻辑分叉。资料来源：[docs/architecture.md:12-58]()

## 顶层架构视图

系统由以下关键节点构成：CLI 入口（或 MCP 服务器入口）、解析器（解析软件包元数据）、审计器（`src/auditor.js`）、沙箱（`src/sandbox.js`）、隔离区（`src/quarantine.js`）、裁决器与输出格式化层。资料来源：[docs/architecture.md:60-120]()

```mermaid
flowchart LR
  A[CLI / MCP Server 入口] --> B[包解析器]
  B --> C[审计器 auditor.js]
  B --> D[沙箱 sandbox.js]
  C --> E[裁决聚合]
  D --> E
  E --> F[输出层<br/>JSON / SARIF / MCP]
  E --> G[隔离区 quarantine.js]
```

## 核心流水线阶段

### 1. 输入与解析

入口接收软件包名、版本范围、本地路径或 tarball URL 后，统一进入解析阶段。该阶段建立依赖图谱，并标注传递依赖深度，为后续裁决提供结构化上下文。资料来源：[docs/design.md:42-78]()

### 2. 静态审计

`src/auditor.js` 负责在不解压、不执行代码的前提下，对 `package.json` 脚本字段、`postinstall` 钩子、可疑依赖来源、生命周期脚本混淆等模式进行规则匹配。审计器输出标准化的"信号（signal）"列表，每条信号附带严重级别与证据引用。资料来源：[src/auditor.js:1-60]()

### 3. 动态沙箱

对高风险软件包，`src/sandbox.js` 在受限环境中执行其生命周期脚本。沙箱通过白名单系统调用、网络出站限制、文件系统写隔离来阻断恶意行为外溢，同时收集真实行为信号补充静态审计结果。资料来源：[src/sandbox.js:1-80]()

### 4. 隔离与裁决

## MCP 服务器集成

v1.0.4 起，`pkgxray mcp-server` 子命令将上述流水线封装为 stdio MCP 服务器。宿主进程（如 IDE 插件）可通过 `npx -y pkgxray mcp-server` 直接拉起，无需本地安装。该模式通过 `mcpName` 字段（`io.github.adamsjack711-ux/pkgxray`）在 MCP Registry 完成归属校验，确保命名空间一致性。资料来源：[docs/architecture.md:122-180]()

复用同一套检测/裁决核心意味着：CLI 的所有检测规则、依赖解析、verdict 输出在 MCP 模式下行为一致，避免因传输层差异导致的语义漂移。资料来源：[docs/design.md:80-110]()

## 扩展点与限制

- 检测规则：审计器接受插件式规则注册，新规则只需实现统一信号接口即可被流水线收集。资料来源：[src/auditor.js:60-100]()
- 沙箱后端：当前实现依赖宿主 OS 能力，更换底层运行时需保持信号采集接口稳定。资料来源：[src/sandbox.js:80-120]()
- 裁决策略：聚合逻辑位于裁决器，可按组织需求调整权重或阈值。资料来源：[docs/design.md:110-150]()

社区已关注的限制包括：跨平台沙箱一致性、传递依赖的深度阈值默认值，以及 MCP 模式下大批量扫描的吞吐表现。资料来源：[docs/architecture.md:180-220]()

---

<a id='page-3'></a>

## CLI 命令、审计与监控

### 相关页面

相关主题：[系统架构与流水线](#page-2), [配置、策略与策略引擎](#page-5), [校准、基准与持续验证](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [bin/audit.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/bin/audit.js)
- [bin/mcp-server.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/bin/mcp-server.js)
- [bin/pkgxray-cache.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/bin/pkgxray-cache.js)
- [src/registry.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/registry.js)
- [src/recheck.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/recheck.js)
- [src/mcp-audit.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/mcp-audit.js)
</details>

# CLI 命令、审计与监控

pkgxray 的命令行层（CLI）是工具与外界交互的唯一入口，负责执行一次性包审计、本地缓存管理，并自 v1.0.4 起以 stdio MCP 服务器的形式提供持续监控能力。本页说明 CLI 子命令结构、审计流水线以及 MCP 监控协议的实现要点。

## 1. 命令结构与可执行入口

CLI 通过 `bin/` 目录暴露三个可执行入口，分别面向不同使用场景：

- `bin/audit.js` —— 默认入口（`pkgxray` 命令），解析参数后调度 `src/recheck.js` 执行一次同步扫描，并将结果写入 SQLite 缓存。资料来源：[bin/audit.js:1-40]()
- `bin/pkgxray-cache.js` —— 缓存运维子命令，用于查询、对比或清理本地审计结果数据库。资料来源：[bin/pkgxray-cache.js:1-30]()
- `bin/mcp-server.js` —— v1.0.4 新增的 stdio MCP 服务器入口，可通过 `npx -y pkgxray mcp-server` 零安装启动；`pkgxray-mcp` bin 保留以保证向后兼容。`mcpName = io.github.adamsjack711-ux/pkgxray` 用于 MCP Registry 归属验证。资料来源：[bin/mcp-server.js:1-40]()

## 2. 审计执行流水线

审计流程由 `src/recheck.js` 驱动，协调「依赖清单 → 注册表查询 → 风险判定 → 结果落库」四个阶段：

1. **清单解析**：读取 CLI 传入的 `package.json` 路径或 npm lockfile，构建依赖图。
2. **注册表查询**：委托 `src/registry.js` 从 npm registry 拉取每个包的最新版本、发布时间、弃用标记与脚本钩子（`preinstall` / `postinstall` 等）。资料来源：[src/registry.js:1-80]()
3. **风险判定**：综合脚本生命周期、维护者异常与传递依赖深度，产出 `verdict`（safe / suspicious / malicious 等）。
4. **结果持久化**：通过共享的 cache helper 将 JSON 报告写入 SQLite，供缓存查询与 MCP 工具复用。资料来源：[src/recheck.js:1-60]()

## 3. MCP 监控协议

`src/mcp-audit.js` 把审计流水线包装为 MCP 工具，让宿主（Claude Desktop、Cline 等）可在对话中触发实时审计：

```mermaid
flowchart LR
  Host[宿主 / Agent] -->|stdio JSON-RPC| Server[mcp-server.js]
  Server --> Tools[mcp-audit.js 工具定义]
  Tools --> Audit[recheck.js 审计执行]
  Audit --> Cache[(本地 SQLite 缓存)]
  Audit --> Reply[结构化风险报告]
  Reply --> Server --> Host
```

- 工具列表暴露 `audit_packages`、`query_cache` 等，分别对应一次性扫描与历史结果查询。资料来源：[src/mcp-audit.js:1-60]()
- 所有调用经 `bin/mcp-server.js` 的 stdio 桥接，进程以常驻方式响应宿主指令，适合纳入 CI 监控或交互式会话。资料来源：[bin/mcp-server.js:40-90]()
- 缓存命中时审计秒级返回；未命中则触发 `recheck.js` 的完整网络拉取，确保结果基于当前注册表状态。

## 4. 监控与缓存运维

`bin/pkgxray-cache.js` 是本地监控的运维入口，提供三类操作：

- **list**：按时间倒序列出最近审计记录与对应 `verdict`。
- **diff**：对比两次审计的依赖变化，常用于升级前的回归评估。
- **purge**：按保留策略清理过期记录，避免 SQLite 无限增长。

由于审计结果同时被 CLI 与 MCP 共享，清理缓存会直接影响后续 MCP 工具的查询结果，运维时需在 CI 与交互式宿主之间协调刷新时机。资料来源：[bin/pkgxray-cache.js:30-80]()

## 5. 典型使用模式

- **CI 集成**：`pkgxray --fail-on high` 在 PR 流水线中阻断高危依赖合入。
- **本地调试**：`pkgxray --json <pkg>` 输出机器可读报告，便于脚本二次处理。
- **Agent 监控**：`npx -y pkgxray mcp-server` 让 Agent 在对话窗口内直接询问当前项目的依赖风险，与 CI 形成互补。资料来源：[bin/mcp-server.js:1-20]()

---

<a id='page-4'></a>

## MCP 服务器、运行时代理与 MCP Registry

### 相关页面

相关主题：[系统架构与流水线](#page-2), [安装拦截、Hookshot 与浏览器扩展](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp-proxy.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/mcp-proxy.js)
- [src/mcp-client.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/mcp-client.js)
- [src/mcp-audit.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/mcp-audit.js)
- [src/mcp-pin.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/mcp-pin.js)
- [bin/mcp-server.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/bin/mcp-server.js)
- [examples/pkgxray-proxy/bin/proxy.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/pkgxray-proxy/bin/proxy.js)
</details>

# MCP 服务器、运行时代理与 MCP Registry

## 概述与子系统职责

pkgxray 围绕 Model Context Protocol (MCP) 提供了一整套运行时安全防护能力，将原本面向 CLI 的「软件包体检」能力（依赖、版本、来源、verdict 等）暴露为可被 MCP 主机发现、调用的工具集合。该子系统由三个互补组件构成：`bin/mcp-server.js` 作为 stdio 入口接入 MCP 主机，`src/mcp-client.js` 在主机侧代表 pkgxray 与远端/上游 MCP 服务建立会话，`src/mcp-proxy.js` 则是夹在被审计进程与真实 MCP 服务器之间的「中间人」，用于在运行时代理、检查并记录所有经过的请求与响应。资料来源：[bin/mcp-server.js:1-80]() [src/mcp-client.js:1-60]() [src/mcp-proxy.js:1-90]()。

社区最关心的部署形态是「零安装」启动：`pkgxray mcp-server` 子命令允许 MCP 主机使用 `npx -y pkgxray mcp-server` 直接拉取并执行，无需全局安装。原有的 `pkgxray-mcp` 二进制入口在 v1.0.4 中保持不变，向后兼容已有配置。资料来源：[bin/mcp-server.js:15-45]()。

## 架构与请求流

MCP 子系统的典型请求流可以概括为：MCP 主机 → stdio → `bin/mcp-server.js` 入口 → `src/mcp-client.js` 建立会话 → `src/mcp-proxy.js` 拦截/转发 → 上游 MCP 服务器 → 经代理回传 verdict 与审计信息。

```mermaid
flowchart LR
    A[MCP 主机<br/>如 Claude Desktop] -->|stdio JSON-RPC| B(bin/mcp-server.js)
    B --> C[src/mcp-client.js<br/>会话与工具发现]
    C --> D{src/mcp-proxy.js<br/>运行时代理}
    D -->|审计/脱敏/拦截| E[上游 MCP Server]
    E --> D
    D -->|verdict + 审计日志| C
    C --> A
```

- **`bin/mcp-server.js`**：CLI 子命令分发器，识别 `mcp-server` 子命令后启动 stdio 传输并加载客户端实现。资料来源：[bin/mcp-server.js:1-80]()。
- **`src/mcp-client.js`**：负责 MCP 协议握手、能力协商、工具列表枚举以及 tool call 的封装与响应解析。资料来源：[src/mcp-client.js:1-120]()。
- **`src/mcp-proxy.js`**：运行时代理核心，包装上游 MCP 传输层，截获 tools/list、tools/call、resources/read 等关键调用，并在转发前后执行策略校验。资料来源：[src/mcp-proxy.js:1-150]()。

## MCP Registry 登记与所有权校验

v1.0.4 起，pkgxray 在 [MCP Registry](https://registry.modelcontextprotocol.io) 中以 `io.github.adamsjack711-ux/pkgxray` 的命名空间登记。为了让主机在零安装场景下能够安全地校验发布者身份，`package.json` 中新增了 `mcpName` 字段，用于 Registry 的所有权签名核验。这意味着当用户执行 `npx -y pkgxray mcp-server` 时，主机可以确认拉取的产物归属于该 Registry 条目，避免「名称抢注」或「供应链替换」风险。资料来源：[bin/mcp-server.js:20-60]()。

登记声明应与下表字段保持一致：

| 字段 | 值 | 说明 |
|------|----|------|
| Registry 命名空间 | `io.github.adamsjack711-ux/pkgxray` | 唯一标识 |
| `mcpName` | `io.github.adamsjack711-ux/pkgxray` | 发布所有权校验 |
| stdio 入口命令 | `pkgxray mcp-server` | npx 零安装启动 |

资料来源：[bin/mcp-server.js:25-70]()。

## 审计、固定与示例代理

除了直接代理调用之外，子系统还提供两类辅助能力：

1. **`src/mcp-audit.js`**：对一次 MCP 会话或一段时间窗口内的工具调用进行审计，输出调用序列、参数摘要与命中策略，可用于离线取证或合规回放。资料来源：[src/mcp-audit.js:1-110]()。
2. **`src/mcp-pin.js`**：将允许调用的工具集合及其参数哈希「固定」下来，运行时若出现偏离（新增工具、参数漂移、版本变更）即触发拒绝或告警，从而抵御「工具清单漂移」类攻击。资料来源：[src/mcp-pin.js:1-95]()。

`examples/pkgxray-proxy/bin/proxy.js` 提供了一个最小可运行的代理示例，演示如何以几行代码把任意上游 MCP 服务器接入 pkgxray 的代理框架：监听 stdio、读取 JSON-RPC 帧、调用 `mcp-proxy` 的转发接口，并选择性地开启审计与固定模式。该示例是用户自定义代理策略的推荐起点。资料来源：[examples/pkgxray-proxy/bin/proxy.js:1-80]()。

## 小结

- `pkgxray mcp-server` 提供零安装 stdio MCP 接入，已登记至 MCP Registry 并通过 `mcpName` 完成所有权校验。资料来源：[bin/mcp-server.js:1-80]()。
- `mcp-proxy` 在协议层对上游 MCP 调用进行拦截与策略化转发，`mcp-client` 负责会话握手与能力枚举。资料来源：[src/mcp-proxy.js:1-150]() [src/mcp-client.js:1-120]()。
- `mcp-audit` 与 `mcp-pin` 提供事后审计与事前固定能力，与代理协同形成纵深防御。资料来源：[src/mcp-audit.js:1-110]() [src/mcp-pin.js:1-95]()。
- `examples/pkgxray-proxy/bin/proxy.js` 给出可复用的代理骨架，便于在自有场景中复用策略。资料来源：[examples/pkgxray-proxy/bin/proxy.js:1-80]()。

---

<a id='page-5'></a>

## 配置、策略与策略引擎

### 相关页面

相关主题：[CLI 命令、审计与监控](#page-3), [威胁模型、检测能力与已知盲点](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [.pkgxray.example.json](https://github.com/adamsjack711-ux/pkgxray/blob/main/.pkgxray.example.json)
- [src/config.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/config.js)
- [src/scanner.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/scanner.js)
- [src/policy.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/policy.js)
- [src/verdict.js](https://github.com/adamsjack711-ux/pkgxray/blob/main/src/verdict.js)
- [docs/configuration.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md)
- [docs/json-schema.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/json-schema.md)
</details>

# 配置、策略与策略引擎

pkgxray 的配置、策略与策略引擎共同构成其核心决策层。配置文件描述扫描对象与输出行为，策略文件描述风险判定规则，策略引擎则在扫描过程中将证据映射为最终结论。该模块是 pkgxray 从"探测器"演化为"判定器"的关键。资料来源：[README.md:1-40]()

## 一、配置文件 `.pkgxray.json`

pkgxray 在仓库根目录或当前工作目录查找 `.pkgxray.json`。示例文件 `.pkgxray.example.json` 展示了全部可选字段，包括：

- `targets`：要扫描的包名或路径列表
- `policies`：要启用的策略 ID 数组
- `output`：报告格式（`json` / `markdown` / `sarif`）
- `failOn`：触发非零退出码的严重级别阈值
- `offline`：是否禁用网络调用，仅依据本地文件分析
- `ignore`：Glob 模式列表，跳过匹配的依赖

加载逻辑由 `src/config.js` 中的 `loadConfig()` 完成：先读取用户配置，再用内置默认值补齐缺失字段，最后做 JSON Schema 校验以在早期暴露错误。资料来源：[src/config.js:1-80]()、[docs/configuration.md:1-60]()

JSON Schema 定义见 `docs/json-schema.md`，是机器可读的字段规范，可被编辑器用于自动补全与类型检查。资料来源：[docs/json-schema.md:1-40]()

## 二、策略定义

策略（Policy）是 pkgxray 中最小的判定单元。每条策略声明一个 `id`、一条 `description`、一组 `rules` 以及一个默认 `severity`。规则形式为：

```json
{
  "id": "deps.known-malicious",
  "severity": "critical",
  "when": { "kind": "dependency", "name": { "in": ["event-stream", "colors@<=1.4.2"] } },
  "then": { "verdict": "block" }
}
```

策略可通过 `policies` 内联在 `.pkgxray.json` 中，也可放在独立的 `*.policy.json` 文件中由 `policyDirs` 引入。资料来源：[.pkgxray.example.json:1-40]()

策略按 `severity` 分为 `info | low | medium | high | critical` 五级，决定其是否会进入 `verdict` 的最终统计与退出码判断。资料来源：[src/policy.js:1-60]()

## 三、策略引擎

策略引擎位于 `src/policy.js`，对外暴露 `evaluate(evidence, policies)`。其执行流程如下：

1. `src/scanner.js` 收集原始证据（依赖列表、脚本内容、license、签名等）。
2. 引擎将每条 evidence 顺序喂给当前策略集合；命中 `when` 子句即记录一次 `match`。
3. 所有命中合并后交给 `src/verdict.js` 计算 `pass / warn / fail`。
4. 命中严重级别 ≥ `failOn` 的策略会让 CLI 以非零退出码终止，便于在 CI 中阻断。资料来源：[src/scanner.js:1-120]()、[src/policy.js:60-140]()、[src/verdict.js:1-80]()

```mermaid
flowchart LR
  A[.pkgxray.json] --> B[loadConfig]
  P[策略文件] --> C[policyDirs]
  B --> D[扫描器 scanner.js]
  C --> D
  D --> E[evidence]
  E --> F[策略引擎 policy.js]
  F --> G[verdict.js]
  G --> H{severity >= failOn?}
  H -- 是 --> I[exit 1]
  H -- 否 --> J[报告输出]
```

## 四、与 MCP 服务器的集成

v1.0.4 新增的 `pkgxray mcp-server` 子命令复用同一套配置与策略引擎：宿主进程以 stdio 方式调用时，`evaluate()` 与 `loadConfig()` 被包装成 MCP 工具，供 LLM 即时检索某条 evidence 对应的策略命中情况。资料来源：[README.md:60-120]()

这意味着策略既可被本地 CI 使用，也可被 MCP 宿主按需查询，避免重复加载与重复定义。

---

<a id='page-6'></a>

## 安装拦截、Hookshot 与浏览器扩展

### 相关页面

相关主题：[CLI 命令、审计与监控](#page-3), [MCP 服务器、运行时代理与 MCP Registry](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/hookshot/README.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot/README.md)
- [examples/hookshot/main.go](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot/main.go)
- [examples/hookshot/helpers.go](https://github.com/adamsjack711-ux/pkgxray/helpers.go)
- [examples/hookshot/pkgxrayguard/guard.go](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot/pkgxrayguard/guard.go)
- [examples/hookshot/pkgxrayguard/wrap.go](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot/pkgxrayguard/wrap.go)
- [examples/hookshot/pkgxrayguard/configwrap.go](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot/pkgxrayguard/configwrap.go)
</details>

# 安装拦截、Hookshot 与浏览器扩展

`Hookshot` 是 pkgxray 提供的一个示例程序，演示了如何在依赖真正安装到本机之前对其"先扫描、再放行"。它通过包装常见的包管理器命令（如 `npm install`、`pip install`、`pnpm add`、`yarn add` 等），把目标依赖交给 pkgxray 进行裁决，从而把"安装拦截"的能力嵌入到现有的开发流程中。资料来源：[examples/hookshot/README.md:1-40]()

## 一、定位与核心思路

Hookshot 并不是一个生产级的拦截器，而是一个**参考实现**，展示如何把 pkgxray 的检测能力插入到命令行包管理器链路里。其核心思路是：

1. **包一层壳**：在用户输入 `npm install <pkg>` 之前，由一个"守卫"程序先接管命令。
2. **调用 pkgxray**：把待安装的包交给 pkgxray，让它输出风险裁决（verdict）。
3. **按策略放行或阻断**：依据裁决结果决定是否真正调用底层包管理器。

这种"前置守卫 + 后端裁决"模式与浏览器扩展（browser extension）的拦截思想一致——浏览器扩展会在请求真正发出前检查 URL、Cookie 或脚本；Hookshot 则在依赖真正落入 `node_modules` 之前检查包本身。资料来源：[examples/hookshot/main.go:1-60]()

## 二、组件划分

Hookshot 示例代码组织为三块职责清晰的模块：

| 模块 | 文件 | 职责 |
|------|------|------|
| 入口与命令解析 | `examples/hookshot/main.go` | 解析原始命令，决定要走哪种包装器 |
| 辅助函数 | `examples/hookshot/helpers.go` | 提供命令行拼装、环境变量处理等通用工具 |
| 守卫核心 | `examples/hookshot/pkgxrayguard/` | 实现"拦截 → 检测 → 放行/阻断"主逻辑 |

其中 `pkgxrayguard` 进一步拆分为：

- `guard.go`：守卫对外暴露的统一接口与状态机。
- `wrap.go`：针对不同包管理器（npm/pnpm/yarn/pip 等）的命令包装策略。
- `configwrap.go`：把 pkgxray 的配置项（如规则集、阻断阈值）映射到守卫行为上。

资料来源：[examples/hookshot/pkgxrayguard/guard.go:1-40]()、[examples/hookshot/pkgxrayguard/wrap.go:1-30]()、[examples/hookshot/pkgxrayguard/configwrap.go:1-30]()

## 三、工作流程

下图展示了 Hookshot 拦截一次 `npm install <pkg>` 的完整数据流：

```mermaid
flowchart LR
    A[用户输入 npm install foo] --> B[Hookshot 入口]
    B --> C{pkgxrayguard 守卫}
    C --> D[提取待安装包名与版本]
    D --> E[调用 pkgxray 检测]
    E --> F{verdict 裁决}
    F -- 安全 --> G[转发给真实包管理器]
    F -- 可疑/恶意 --> H[阻断并提示用户]
    G --> I[依赖写入 node_modules]
    H --> J[退出,返回非零状态码]
```

关键点在于：`guard.go` 负责串联流程，`wrap.go` 负责把原生命令改写为"先检测、再执行"的形式，而 `configwrap.go` 决定在什么条件下应该阻断、什么条件下只是告警。资料来源：[examples/hookshot/pkgxrayguard/guard.go:20-80]()、[examples/hookshot/pkgxrayguard/wrap.go:10-60]()

## 四、与浏览器扩展的类比

虽然 Hookshot 本身是 CLI 程序，但其拦截范式与浏览器扩展（如广告拦截器、隐私保护扩展）高度相似：

- **拦截点选择**：浏览器扩展通常在 `webRequest` 阶段介入；Hookshot 则在子进程 `exec` 阶段介入。
- **策略可插拔**：两者都允许通过配置文件或规则集动态启用/禁用规则。
- **裁决而非修改**：Hookshot 不修改包内容，只决定是否放行，与扩展不修改网页内容、只决定是否屏蔽资源一致。

借助这种类比，开发者可以把 Hookshot 当作"包管理器侧的扩展点"，把 pkgxray 当作"扩展背后的检测引擎"。资料来源：[examples/hookshot/README.md:20-60]()、[examples/hookshot/helpers.go:1-40]()

## 五、使用与扩展建议

要在本地试用 Hookshot，只需在 `examples/hookshot` 目录下构建并把它放到 `PATH` 中，使 `npm`、`pip` 等命令在执行前先经过守卫。后续若要支持新的包管理器（如 `cargo add`、`gem install`），可在 `wrap.go` 中新增一条包装策略，并在 `configwrap.go` 中补充对应的配置映射，无需改动 `guard.go` 的主流程。资料来源：[examples/hookshot/main.go:30-90]()、[examples/hookshot/pkgxrayguard/wrap.go:30-70]()

---

<a id='page-7'></a>

## 威胁模型、检测能力与已知盲点

### 相关页面

相关主题：[系统架构与流水线](#page-2), [配置、策略与策略引擎](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md)
- [docs/canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md)
- [docs/design/evasion-triage.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design/evasion-triage.md)
- [docs/design/integration-triage.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design/integration-triage.md)
- [docs/design/mcp-adapter-triage.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design/mcp-adapter-triage.md)
- [docs/design/mcp-adapter-prompt.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design/mcp-adapter-prompt.md)
</details>

# 威胁模型、检测能力与已知盲点

pkgxray 是一款面向 npm 生态的供应链安全扫描器，其设计目标是揭示 `package.json`、安装脚本、依赖关系与发布元数据中潜在的恶意或可疑行为。本页综合仓库内的威胁模型与设计文档，梳理 pkgxray 所假定的对抗场景、可观测的检测维度，以及当前版本明确承认的盲点，便于使用者正确解读判定结果。

## 威胁建模的核心假设

威胁模型文档将 pkgxray 的敌手限定在「能够向 npm 注册表发布或在安装阶段注入代码的参与者」，包括恶意维护者、被劫持的账号以及依赖混淆攻击者。文档指出 pkgxray 的判定逻辑建立在三类信号之上：声明性元数据（脚本钩子、`bin`、依赖列表）、网络与文件系统可达性、以及与已知合法包指纹的偏离度。

资料来源：[docs/threat-model.md:1-40]()

canary 威胁模型进一步限定了「蜜罐」式用例：pkgxray 可作为无人值守的探针运行，监控针对内部命名空间、相似拼写或私有 registry 别名的发布行为，从而在攻击者试探阶段就产生信号。该文档强调蜜罐应仅产生告警而非阻断，以避免与正常发布产生冲突。

资料来源：[docs/canary-threat-model.md:1-35]()

## 检测能力覆盖范围

pkgxray 的检测能力由多个分诊（triage）模块协同实现，下表概述其关注点与典型产出：

| 分诊模块 | 关注对象 | 典型产出 |
|---|---|---|
| `evasion-triage` | 安装脚本中的混淆、动态执行、环境探测 | 静态特征命中与可疑片段 |
| `integration-triage` | `dependencies`、`peerDependencies`、`optionalDependencies` 与传递依赖 | 依赖关系图与可疑上游标记 |
| `mcp-adapter-triage` | 通过 MCP 注册表引入的适配层行为 | 适配器 prompt 与工具调用约束 |

`evasion-triage` 设计文档指出，扫描器会优先标记 `eval`、`Function(...)`、`child_process`、未声明的 `curl`/`wget`/`fetch` 等模式，并尝试对简单 Base64、字符串拼接与十六进制编码进行归一化后再判定。

资料来源：[docs/design/evasion-triage.md:10-60]()

`integration-triage` 文档说明，依赖关系分析不仅比较包名，还会结合维护者数量、版本历史、下载量曲线与首次发布时间，用于识别 typosquatting 与依赖混淆候选。

资料来源：[docs/design/integration-triage.md:1-55]()

`mcp-adapter-triage` 与 `mcp-adapter-prompt` 描述了 v1.0.4 起新增的 MCP 适配层如何在不修改检测与判定逻辑的前提下，将扫描结果暴露为标准化的 prompt 与工具调用，使外部 MCP 主机可零安装调用 `pkgxray mcp-server`。

资料来源：[docs/design/mcp-adapter-triage.md:1-40]()
资料来源：[docs/design/mcp-adapter-prompt.md:1-45]()

## 已知盲点与诚实声明

pkgxray 在威胁模型与各分诊文档中均明确承认若干已知盲点：

- **网络二阶段载荷**：安装阶段从远端拉取的脚本或二进制不会被执行后再次扫描，因此延迟下载或条件触发（例如仅在特定日期运行）的逻辑可能逃过检测。
- **合法行为误报风险**：构建脚本、native 绑定安装（`node-gyp`）与 telemetry 上报与恶意行为在表面特征上重叠，文档建议结合 `bin`、`scripts` 与维护者声誉综合判断，而非依赖单一规则。
- **MCP 适配层仅为传输通道**：`mcp-adapter-triage` 与 `mcp-adapter-prompt` 明确指出，适配层只负责把已有判定结果以结构化方式呈现，不会引入新的检测能力，也不会改变 verdict 计算，因此其覆盖范围与底层扫描器一致。

资料来源：[docs/threat-model.md:60-95]()
资料来源：[docs/design/evasion-triage.md:80-120]()
资料来源：[docs/design/mcp-adapter-triage.md:30-55]()

## 使用建议

结合上述威胁模型与盲点，pkgxray 适合作为 CI 流水线中的「快速分流」环节：对高风险判定直接阻断，对中低风险判定交由人工或更重的动态分析系统复核。v1.0.4 引入的 MCP Server 仅是分发与编排层面的便利，不会扩展检测覆盖面，因此安全策略仍应以本文所述能力边界为准。

---

<a id='page-8'></a>

## 校准、基准与持续验证

### 相关页面

相关主题：[系统架构与流水线](#page-2), [CLI 命令、审计与监控](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/benchmark.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md)
- [validation/README.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/validation/README.md)
- [validation/top1000.txt](https://github.com/adamsjack711-ux/pkgxray/blob/main/validation/top1000.txt)
- [validation/defensible-blocks.json](https://github.com/adamsjack711-ux/pkgxray/blob/main/validation/defensible-blocks.json)
- [validation/mcp-registry-targets.txt](https://github.com/adamsjack711-ux/pkgxray/blob/main/validation/mcp-registry-targets.txt)
- [validation/mcp-registry-targets.meta.json](https://github.com/adamsjack711-ux/pkgxray/blob/main/validation/mcp-registry-targets.meta.json)
</details>

# 校准、基准与持续验证

## 一、目的与定位

校准、基准与持续验证（Calibration, Benchmarking & Continuous Validation）是 pkgxray 用来保证检测器、依赖分析与裁决结果**可重复、可审计、可回归**的工程体系。它由三类资产组成：基准文档（`docs/benchmark.md`）、受控验证语料（`validation/` 目录），以及由社区驱动的 MCP Registry 目标列表。资料来源：[validation/README.md:1-15]()

该体系服务于三类读者：
1. **算法维护者**：用基准与可辩护样本（defensible blocks）校准阈值、衡量误报/漏报。
2. **集成方**：通过 `validation/mcp-registry-targets.txt` 验证工具对真实注册表包的处理结果。
3. **终端用户**：在每次发布（如 v1.0.4 引入 `pkgxray mcp-server` 与 `mcpName` 后）能获得确定的回归保证。

## 二、基准测试套件

`docs/benchmark.md` 定义了 pkgxray 的基准运行流程，包含输入集合、运行命令、输出字段以及对比基线。资料来源：[docs/benchmark.md:1-25]()。基准通常以 `validation/top1000.txt` 中收录的 1000 个代表性包作为默认输入，覆盖主流生态、各类元数据完整度与已知异常情形。资料来源：[validation/top1000.txt:1-10]()

基准结果会输出三类指标：
- **检测指标**：被识别为恶意的包数 / 总数。
- **裁决指标**：每条裁决（verdict）对应的等级分布。
- **依赖图指标**：节点数、边数、平均深度、循环检测命中率。

`docs/benchmark.md` 中通常会写明如何在本地复现基准（依赖 Node.js 与 `npx pkgxray`），以及如何把输出与历史基线对齐。资料来源：[docs/benchmark.md:30-60]()

## 三、可辩护样本与验证语料

`validation/defensible-blocks.json` 是项目用来**抵抗误报争议**的核心资产：每一项都记录了一个经过人工核验的包及其“应当被如何裁决”的判例，供检测器回归使用。资料来源：[validation/defensible-blocks.json:1-20]()。该文件让“裁决变更”不再是黑箱，而是有据可查的最小可辩护单元（defensible block）。

`validation/README.md` 描述了如何新增、修改与撤销 defensible block，包括字段约定（如 `package`、`expected_verdict`、`rationale`、`added_in`、`reviewed_by`），以及 PR 评审的最低门槛。资料来源：[validation/README.md:10-40]()

## 四、MCP Registry 持续验证

随着 v1.0.4 发布，pkgxray 在 [MCP Registry](https://registry.modelcontextprotocol.io) 中以 `io.github.adamsjack711-ux/pkgxray` 注册，并新增 `pkgxray mcp-server` 子命令以 stdio 方式对外暴露能力。`mcpName` 字段用于注册表归属校验，确保只有合法宿主能够触发服务。

围绕这次发布，仓库新增了两份资产用于**持续验证**：

| 文件 | 角色 |
|---|---|
| `validation/mcp-registry-targets.txt` | 选取自 MCP Registry 的目标包清单，用作回归与外部一致性测试的输入 |
| `validation/mcp-registry-targets.meta.json` | 配套元数据，记录每个目标的版本、抓取时间、期望裁决与运行环境 |

资料来源：[validation/mcp-registry-targets.txt:1-8]()；[validation/mcp-registry-targets.meta.json:1-15]()。

持续验证的工作流如下：

```mermaid
flowchart LR
    A[top1000.txt<br/>基准输入] --> C[pkgxray 检测]
    B[mcp-registry-targets.txt<br/>注册表输入] --> C
    D[defensible-blocks.json<br/>可辩护样本] --> E{裁决比对}
    C --> E
    E -->|不一致| F[回归失败 / 调整阈值]
    E -->|一致| G[基线更新]
```

任何针对 `pkgxray mcp-server` 或检测逻辑的改动，都必须同时通过 `top1000.txt` 基准与 `mcp-registry-targets` 外部一致性测试，否则视为破坏性变更，需要在 PR 中显式更新 `defensible-blocks.json`。资料来源：[validation/README.md:40-60]()。

## 五、操作清单（Quick Reference）

- **运行完整基准**：`npx pkgxray benchmark --input validation/top1000.txt`
- **仅跑 MCP 注册表回归**：`npx pkgxray mcp-server` 后由宿主以 `mcpName=io.github.adamsjack711-ux/pkgxray` 调用
- **审计裁决变更**：对照 `validation/defensible-blocks.json` 与 `validation/mcp-registry-targets.meta.json`

资料来源：[docs/benchmark.md:60-80]()；[validation/mcp-registry-targets.meta.json:10-20]()。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：adamsjack711-ux/pkgxray

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://news.ycombinator.com/item?id=49005722 | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49005722 | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=49005722 | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=49005722 | no_demo; severity=medium

## 5. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49005722 | issue_or_pr_quality=unknown

## 6. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49005722 | release_recency=unknown

<!-- canonical_name: adamsjack711-ux/pkgxray; human_manual_source: deepwiki_human_wiki -->