NPM 包漏洞应急手册

解决什么问题

安全通告到达时，npm audit 给出的报告往往令人沮丧：上百条路径、大量 extraneous、devDependencies 的告警，以及同一个漏洞在不同传递依赖里被重复计数。工程团队真正想知道的是：这个漏洞为什么进入了 lockfile、从哪条依赖路径注入、先升级谁才能消除它，以及能不能先接受风险而不是立刻改代码。

现实里，排查经常从「跑一次 npm audit」开始，却卡在几个环节：

• 报告把生产依赖与开发依赖混在一起，无法快速判断影响面。
• 同一漏洞多路径时，缺少依赖树分析，容易做出错误的升级决策。
• 升级某个包后，npm audit 仍报同一漏洞，因为问题其实在上游 peer/transitive 依赖。

技能如何工作

这个技能的价值在于把「读报告」变成「按证据分诊」。它以两个公开数据源为基础：

• npm Audit API：读取锁文件生成的审计报告，提供漏洞所在包、严重级别与依赖路径。
• OSV.dev API：补充漏洞的元数据与影响范围，帮助判断通告的真实性和依赖面。

当执行任务时，它按以下关键步骤工作：

1. 收集证据：读取项目的 package.json 与锁文件，调用 npm Audit API 获取结构化告警，并将结果按包名聚合，避免重复路径干扰。
2. 补充上下文：用 OSV.dev 查询漏洞详情，将 npm 报告里的条目与 OSV 中的受影响版本区间对应起来。
3. 生成可执行的 runbook：按漏洞包生成分步修复说明，给出对应的补丁命令和建议目标版本，并解释该命令作用在哪一层依赖。
4. 分析依赖树路径：展示漏洞从根包到受影响模块的传递路径，帮助判断这是直接依赖问题还是上游依赖问题。

适用边界与注意点

这个技能适合 Node.js 项目漏洞的初筛和定位。它能把 npm audit 的原始报告转换为带证据的应急文档，但有几个边界需要清楚：

• 它依赖 npm Audit API 与 OSV.dev 的数据，如果上游源延迟同步，通告可能未被覆盖。
• 它输出的是修复指引，不会自动升级依赖或修改锁文件。升级决策仍应由维护者确认兼容性。
• npm audit fix 可能引入破坏性变更，尤其是 major 版本升级。
• 项目若使用私有 registry、npm 替代方案或复杂的 monorepo，审计路径需要额外确认。
• 高危漏洞确认后，补丁只是开始，还需要检查运行环境是否存在暴露面。