supply-chain-risk-auditor

供应链风险审计

为项目的直接依赖项（npm、PyPI、Go）生成供应链风险报告，并对锁文件解析出的所有依赖项进行安全公告扫描。两个确定性脚本负责测量；你需要作出它们无法自动完成的判断。

为什么由脚本负责测量，而不是你

报告中的每个数字都是对他人项目的陈述，而在这项技能改为由脚本处理之前，人工收集的数据曾出现错误：GitHub 的贡献者数量显示有 5 位以上的人员维护 lodash，而 npm 的 ACL 显示只有 1 位；gh 显示某个每周有 1.64 亿次下载的包下载量为 0。不要根据 gh、网页搜索或记忆估算维护者数量、下载量、陈旧程度或 CVE 历史记录——运行收集器，并引用它测得的数据。

脚本强制执行两条规则，阅读输出前值得了解：

• 数据不可用从来不是风险证据。 每项标准的结果都属于以下之一：已评估且无问题、已评估且有风险，或无法评估并附有原因。
• 缺少测量结果绝不代表结论无问题。 如果一次运行没有测得任何数据，脚本会以非零状态退出，而不是打印一份声称未发现问题的报告。

工作流

1. 确认目标目录中包含清单文件：package.json、pyproject.toml、requirements*.txt 或 go.mod。如果一个都没有，请说明并停止——不要手动审计此收集器无法解析的生态系统。用于获取精确版本和进行传递依赖扫描的锁文件包括：package-lock.json/npm-shrinkwrap.json、uv.lock，以及 go 1.17+ 的 go.mod。不会读取 yarn.lock、pnpm-lock.yaml 和 poetry.lock——如果存在，报告会说明这一点，版本则回退为固定版本或最新发行版。

2. 检查 gh auth status。未通过身份验证的 GitHub 每小时允许 60 次请求，而通过身份验证后为 5,000 次；收集器对每个依赖项都会发起多次请求。没有身份验证时，仓库相关标准很可能会无法评估。请如实说明，不要悄悄替用户解决。

3. 先收集，再生成报告。除非另有要求，否则将输出放在受审计仓库之外：

   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
   

   大约 50 个依赖项预计需要几分钟——每个依赖项都要发起多次 HTTP 请求，Go 模块较多时需要更多请求；没有经过身份验证的 gh 时速度也会更慢。如果 collect.py 以非零状态退出，说明它拒绝生成报告——请原样转达其消息，不要重试或绕过限制。

4. 阅读 report.md 和 findings.json。报告是交付内容；需要引用某项结论时，JSON 文件中包含其背后的数据。

5. 补充收集器无法提供的内容，并与测量结果明确区分：

   • 面向此读者的简短说明：应优先处理什么，以及原因。
   • 安全公告相关发现的升级路径——确认修复版本相差的是补丁版本还是主版本。
   • 已弃用或已归档依赖项的替代候选项。指定候选项前，请确认其已在注册表中发布，并明确标注这是判断，而非测量结果。
   • 对于存在风险的安装脚本：确认此项目的构建能否使用 npm ci --ignore-scripts。

新增内容的写作风格

新增文字应采用安全报告的写法，报告附录和最终回复也应保持相同语体——回复会被原样粘贴到工单和报告中。陈述发现、依据数据以及采取的行动。

• 使用非人称、陈述式表达：不使用第一人称或第二人称（“我运行了收集器”“你应该升级”），不使用缩写形式。
• 使用主动语态，以事项本身为主语：“升级到 1.19.0 会清除全部 25 项安全公告”，而不是“建议升级 axios”。
• 保持客观：不使用程度副词或主观表述（“非常”“显著”“幸运的是”），不猜测项目选择某种方案的原因。
• 时态：审计做了什么用过去时；依赖项的状态用现在时；采取或不采取行动的后果用将来时。
• 提供建设性建议：建议应明确行动及其成本，不归咎于任何对象。

如果会话中提供了 report-writing:writing-style 技能，请遵循该技能——它是此语体的完整版本。

阅读报告

• 无法评估不等于存在风险。 PyPI 不公布维护者 ACL，Go 没有注册表；这些行说明的是哪些信息无法获知，而不是哪里出了问题。
• 覆盖表限定了每项结论。 “无安全公告”表示“在已评估的范围内未发现安全公告”——重复无问题的结论前，请先查看已评估数量。
• 逐字引用数字。 不要重新计算、四舍五入或添油加醋地描述报告中的数字；每个数字都可根据报告文件复现。
• 未列入发现项不代表认可。 未发现问题的依赖项仅依据这些标准进行了评估。

应拒绝的托词

• “gh 能比收集器更快统计维护者人数。”实测表明此说法不成立——代码仓库贡献者与注册表发布权限持有者是不同群体。
• “没有发现问题，所以依赖项是安全的。”请查看覆盖表；对于 PyPI 和 Go，一半的标准在结构上无法评估。
• “无法评估的行只会让读者困惑，我会删掉。”这些行界定了报告中每项结论的范围。删除它们会把部分覆盖伪装成全面安全，这正是重建此技能所要防止的问题。
• “这个版本大概足够接近。”针对最新发布版本检查的范围，与锁文件解析出的版本所对应的结论不同；报告会标明具体结论。保留该标注。

不适用情形

• 许可证合规审计。
• 扫描目标自身源代码中的漏洞或机密信息——此技能不会读取依赖项源代码，只会读取注册表、安全公告和代码仓库元数据。
• 判断项目能否安装或构建。此审计旨在仅凭依赖项清单（清单文件和锁文件）运行，绝不会安装、构建或执行任何内容。安装失败和导入时故障不在范围内；如果用户似乎对此有所期待，应明确说明。
• npm、PyPI 和 Go 之外的生态系统；应说明该生态系统不受支持，而不是临时编造审计方法。