前言¶
第三方依赖是多数应用的真实攻击面：直接依赖上的已知漏洞、锁文件里解析出的传递依赖、上游仓库归档或维护停滞、npm 发布者集中度过高、安装阶段执行的脚本，都会在「还没读业务代码」之前就构成风险。手工翻 registry、用 gh 估维护者人数或下载量，容易把不同数据源混成一条结论——官方文档里就提到，重建本 Skill 之前曾出现「GitHub 贡献者很多、npm ACL 却只有一人」「gh 显示零下载、registry 侧却是每周上亿次」这类偏差。
下面介绍 Trail of Bits 在 skills 插件市场里提供的 supply-chain-risk-auditor：针对项目清单与锁文件生成供应链风险报告，由确定性脚本采集数据，由 Agent 做脚本不自动化的判断与叙述。
这是什么¶
supply-chain-risk-auditor 是 Claude Code / Codex 等环境中可加载的 Agent Skill（allowed-tools：Read、Write、Bash、Glob、Grep）。它审计项目的直接依赖（npm、PyPI、Go），并对锁文件解析出的完整依赖树做 advisory 扫描；覆盖版本匹配的漏洞公告、上游废弃或归档、npm 发布者集中度、安装时脚本执行等维度。
出品方为 Trail of Bits，Skill 源码与说明位于：
https://github.com/trailofbits/skills/tree/main/plugins/supply-chain-risk-auditor/skills/supply-chain-risk-auditor
本 Skill 不安装、不构建、不执行目标项目，也不读取依赖包源码；只基于 manifest、lockfile 以及 registry、advisory、仓库元数据工作。
核心功能¶
脚本采集，Agent 裁决¶
报告中的数字应来自采集脚本，而非记忆、gh 随手查询或网页搜索。官方明确要求：不要自行估算维护者数量、下载量、陈旧程度或 CVE 历史——运行 collector，并引用其测量结果。
脚本遵循两条规则：
- 拿不到的数据不能当作风险证据。 每条准则的结果是：已评估为干净、已评估为需关注、或不可评估（附原因）。
- 没有测量结果不能给出「全绿」结论。 若一次运行什么都没测到，进程以非零退出，而不是打印一份「零发现」的报告。
支持的生态与清单¶
目标目录需存在下列之一，否则应说明并停止，不要用手工方式审计未支持的生态：
package.json（npm）pyproject.toml、requirements*.txt（PyPI）go.mod（Go）
用于精确版本与传递依赖扫描的锁文件包括：package-lock.json / npm-shrinkwrap.json、uv.lock、Go 1.17+ 的 go.mod。若存在 yarn.lock、pnpm-lock.yaml、poetry.lock，报告会说明未读取这些文件，版本可能回退到 pin 或最新 release 的声明方式——二者在报告里会分开标注。
报告可读性约定¶
- Unassessable 不等于有风险（例如 PyPI 无维护者 ACL、Go 无统一 registry 时，部分行只是「无法得知」）。
- 覆盖范围表限定所有结论。「无 advisory」指「在已评估范围内无」，需先看 assessed 数量。
- 数字照抄报告原文，不要重算、四舍五入或润色。
- 某依赖在 findings 里未出现，只表示未在本 Skill 的准则下被标出，不是背书。
安装与启用¶
Skill 随 Trail of Bits 的 skills 市场插件分发；插件目录为 plugins/supply-chain-risk-auditor/。
Claude Code：
/plugin marketplace add trailofbits/skills
/plugin menu
在菜单中选择并安装对应插件（含 supply-chain-risk-auditor）。
Codex：
codex plugin marketplace add trailofbits/skills
codex plugin list
codex plugin add <plugin-name>@trailofbits
本地开发时，可在仓库父目录执行 /plugins marketplace add ./skills（路径以官方 README 为准）。
Cursor 侧若通过兼容 Claude 插件市场的机制加载同一市场，步骤以当前产品文档为准；本文仅收录上述已出现在官方仓库 README 中的命令。
典型用法¶
1、确认目标与 GitHub 认证¶
- 确认待审计目录含有支持的 manifest（见上文）。
- 执行
gh auth status。未认证的 GitHub API 约 60 次/小时，认证后约 5000 次/小时；采集器对每个依赖会发起多次请求。未认证时，与仓库相关的准则可能大量返回 unassessable，应在交付物中说明，而不是静默忽略。
2、采集并渲染报告¶
输出建议放在被审计仓库之外的目录（除非用户明确要求否则）：
uv run {baseDir}/scripts/collect.py <project-dir> --json <out-dir>/findings.json
uv run {baseDir}/scripts/render.py <out-dir>/findings.json --out <out-dir>/report.md
{baseDir} 为 Skill 安装目录下的技能根路径。约 50 个直接依赖时，完整采集可能需要数分钟（每个依赖多次 HTTP；Go 模块多会更慢；无 gh 认证会更慢）。
若 collect.py 以非零退出，表示拒绝生成报告——应原样转述其错误信息，不要擅自重试或绕过。
3、阅读交付物并补充判断¶
report.md：面向读者的主报告（事实由脚本渲染）。findings.json：每条结论背后的结构化数据，便于引用。
Agent 在脚本结果之外、且明确区分「测量」与「判断」地补充：
- 针对读者的短叙述：优先处理项及理由。
- Advisory 对应的升级路径（补丁级还是主版本跳跃）。
- 对废弃/归档依赖的替代候选（须在 registry 核实存在，并标明为判断而非测量）。
- 对 flagged 的安装脚本：本项目是否可采用
npm ci --ignore-scripts等策略。
补充文字宜采用安全报告体：陈述发现、依据数据、建议动作；避免第一/第二人称、感叹号、主观强化词；过去时描述审计行为，现在时描述依赖现状，将来时描述处置后果。
适用场景与注意¶
适合：
- 接安全评估或代码审计前，快速摸清依赖树上的公告与元数据风险。
- 用户明确要求「审计依赖」「评估供应链/第三方包风险」「在 engagement 前审查依赖树」时触发本 Skill（与官方
description一致）。
不适合或超出范围：
- 许可证合规审计。
- 扫描项目自有源码中的漏洞或密钥（本 Skill 不读依赖源码）。
- 判断项目能否成功安装或构建；损坏的安装与 import 时错误不在范围内。
- npm / PyPI / Go 以外的生态：应说明不支持，勿即兴手工审计。
常见误区（官方明确反对）：
- 用
gh维护者数替代 registry 发布权限视角。 - 忽视覆盖表，把「零 finding」说成「依赖安全」。
- 删掉 unassessable 行，使部分覆盖看起来像全面通过。
- 把「按 latest-release 检查的范围」与「锁文件解析版本」混为一谈。
结尾¶
supply-chain-risk-auditor 把供应链审计里易出错的「数字采集」交给 collect.py / render.py，把优先级、升级与替代方案留给 Agent，并在报告边界上区分 assessed 与 unassessable，减少误报与漏报。安装与 Skill 说明见 Trail of Bits 官方仓库：
https://github.com/trailofbits/skills/tree/main/plugins/supply-chain-risk-auditor/skills/supply-chain-risk-auditor
