项目定位与目标

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

核心能力矩阵

工具的判定结果以 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 声明）。全局安装：

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 完成上架与所有权核验。
• 允许 MCP Host 使用 npx -y pkgxray mcp-server 实现零安装启动。

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

概述与设计目标

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

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

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 等）可在对话中触发实时审计：

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

概述与子系统职责

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 与审计信息。

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

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

资料来源：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。

一、配置文件 `.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。规则形式为：

{
  "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

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 宿主按需查询，避免重复加载与重复定义。

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 示例代码组织为三块职责清晰的模块：

其中 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> 的完整数据流：

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

威胁建模的核心假设

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

资料来源：docs/threat-model.md:1-40

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

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

检测能力覆盖范围

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

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 仅是分发与编排层面的便利，不会扩展检测覆盖面，因此安全策略仍应以本文所述能力边界为准。

一、目的与定位

校准、基准与持续验证（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 中以 io.github.adamsjack711-ux/pkgxray 注册，并新增 pkgxray mcp-server 子命令以 stdio 方式对外暴露能力。mcpName 字段用于注册表归属校验，确保只有合法宿主能够触发服务。

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

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

持续验证的工作流如下：

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。

Pitfall Log / 踩坑日志

项目：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