audit-dependencies

审计依赖

概述

修复由 .github/workflows/audit-dependencies.sh 报告的依赖漏洞。按以下顺序优先选择修复方式：直接依赖升级 > lockfile 更新 > pnpm override。每个 override 都需要说明为什么更简单的方案不可行。

核心工作流

digraph audit {
    "Run audit script" [shape=box];
    "Group by package" [shape=box];
    "Trace dependency chain" [shape=box];
    "Can bump direct dep?" [shape=diamond];
    "Research breaking changes" [shape=box];
    "Breaking changes acceptable?" [shape=diamond];
    "Apply direct bump" [shape=box];
    "Is version pinned or ranged?" [shape=diamond];
    "Lockfile update" [shape=box];
    "Apply pnpm override" [shape=box];
    "More packages?" [shape=diamond];
    "Present plan to user" [shape=box];
    "Install and verify" [shape=box];
    "Build and verify" [shape=box];
    "Commit and create PR" [shape=box];

    "Run audit script" -> "Group by package";
    "Group by package" -> "Trace dependency chain";
    "Trace dependency chain" -> "Can bump direct dep?";
    "Can bump direct dep?" -> "Research breaking changes" [label="yes"];
    "Can bump direct dep?" -> "Is version pinned or ranged?" [label="no"];
    "Research breaking changes" -> "Breaking changes acceptable?";
    "Breaking changes acceptable?" -> "Apply direct bump" [label="yes"];
    "Breaking changes acceptable?" -> "Is version pinned or ranged?" [label="no"];
    "Is version pinned or ranged?" -> "Lockfile update" [label="ranged - fix is in range"];
    "Is version pinned or ranged?" -> "Apply pnpm override" [label="pinned - explain why"];
    "Apply direct bump" -> "More packages?";
    "Lockfile update" -> "More packages?";
    "Apply pnpm override" -> "More packages?";
    "More packages?" -> "Trace dependency chain" [label="yes"];
    "More packages?" -> "Present plan to user" [label="no"];
    "Present plan to user" -> "Install and verify";
    "Install and verify" -> "Build and verify";
    "Build and verify" -> "Commit and create PR";
}

分步操作

1. 运行审计脚本

./.github/workflows/audit-dependencies.sh $ARGUMENTS

$ARGUMENTS 是传递给该 skill 的严重级别（省略时默认为 high）。该脚本会运行 pnpm audit --prod --json 并筛选出可处理的漏洞（即有可用修复版本的漏洞）。high 包含 critical。

解析输出，构建一个去重后的易受攻击包列表，包含：

• 包名和当前版本
• 修复版本要求
• 完整依赖链（例如 packages/plugin-sentry > @sentry/nextjs > rollup）

2. 对每个易受攻击的包

追踪依赖链

确定易受攻击的包属于：

• 直接依赖：列在某个 workspace 包的 package.json 中
• 传递依赖：由另一个包引入

先尝试直接升级

对于传递依赖，沿依赖链向上查找你控制的最接近的包：

1. 检查升级父包是否能解决该漏洞
   • pnpm view <parent>@latest dependencies.<vulnerable-pkg>
   • 也检查中间版本（修复可能存在于某个次要版本升级中）
2. 如果升级父包能解决该问题，研究破坏性变更：
   • 查看 changelog / 发行说明
   • 搜索 GitHub issue 中的兼容性问题
   • 审查本仓库中使用的 API 范围（阅读源文件）
   • 检查版本范围是否跨越主版本边界
3. 向用户展示调查结果及风险评估

并行研究：当多个包需要破坏性变更分析时，并行派发 Agent（每个包一个）同时进行研究。

检查 lockfile 更新是否足够

在动用 override 之前，检查父包的版本说明符是固定版本（精确版本，如 3.10.3）还是范围版本（如 ^2.3.1、~4.0.3）：

pnpm view <parent> dependencies.<vulnerable-pkg>

如果该范围已包含修复版本，只需更新 lockfile 即可：

pnpm update <vulnerable-pkg> --recursive

无需修改 package.json —— 只是 lockfile 过时了。

仅在合理时回退到 override

仅在以下情况下，才在根 package.json 中添加 pnpm override：

• 父包固定了不满足修复的精确版本
• 父包的任何版本都无法修复该漏洞
• 升级父包有很高的破坏性变更风险（重大 API 变更、缺乏测试覆盖、需要跨多个文件修改代码）
• 用户明确决定将父包升级推迟到单独的 PR

Override 格式："<parent>><vulnerable-pkg>": "^<fixed-version>"

Override 语法规则：

• 使用 ^ 范围，而非 >=。>= 可能跨越主版本并导致意外的解析结果（例如 "picomatch": ">=2.3.2" 可能解析到 4.x）。
• pnpm 仅支持单层父包作用域："parent>pkg" 有效，"grandparent>parent>pkg" 无效。
• pnpm 不支持在 override 键中使用版本选择器："pkg@^2" 无效。
• 如果同一个易受攻击的包通过多条传递路径出现，可能需要全局 override。注意不要影响处于不同主版本的不相关使用者 —— 当该包在依赖树中跨越多个主版本时，使用父包作用域的 override。
• pnpm 仅遵循根 workspace package.json 中的 overrides。workspace 包中的 override 会被忽略。

在添加任何 override 之前，验证目标版本是否存在：

pnpm view <pkg>@<version> version

3. 向用户展示方案

在应用修复之前，向用户展示一个汇总表，列出每个漏洞、建议的修复策略（直接升级 / lockfile 更新 / override）以及理由。在继续之前获得确认。

4. 应用修复

• 对于直接升级，编辑 package.json 文件
• 对于仅需修复 lockfile 的情况，运行 pnpm update <pkg> --recursive
• 对于 override，编辑根 package.json 的 pnpm.overrides（保持字母顺序）
• 如果直接升级改变了行为，请更新使用该依赖的代码（例如，当 API 默认值发生变化时添加 allowOverwrite: true）

5. 安装并验证

pnpm install

如果安装因原生构建错误（例如 better-sqlite3）而失败，请回退到：

pnpm install --ignore-scripts

然后使用相同的严重级别重新运行审计脚本：

./.github/workflows/audit-dependencies.sh $ARGUMENTS

审计脚本必须以 0 退出。如果仍存在漏洞，请检查其他 workspace 包中是否存在同一依赖的其他实例。

6. 构建并验证

pnpm run build:core

对于依赖发生变化的包，还要运行其特定的构建：

pnpm run build:<package-name>

7. 查找 CVE

对于每个已修复的漏洞，找到 GitHub Security Advisory（GHSA）：

• 检查每个包的 https://github.com/<org>/<repo>/security/advisories
• 在网上搜索 <package-name> GHSA <fixed-version>
• 记录：GHSA ID、CVE ID、严重级别、一行描述
• 优先使用 GHSA 链接（https://github.com/advisories/GHSA-xxxx-xxxx-xxxx）而非 NVD 链接

并行化 CVE 查找：派发并行 Agent，同时搜索所有包中的 CVE。

8. 提交并创建 PR

使用约定式提交格式进行提交：

fix(deps): resolve $ARGUMENTS severity audit vulnerabilities

使用 gh pr create 创建 PR，正文结构如下：

# Overview

[What the PR fixes, mention `pnpm audit --prod`]

## Key Changes

- **[Package name] in [workspace path]**
  - [old version] → [new version]. Fixes [GHSA-xxxx-xxxx-xxxx](https://github.com/advisories/GHSA-xxxx-xxxx-xxxx) ([description]).
  - [Why this approach: direct bump because X / lockfile update because Y / override because Z]
  - [Any code changes required by the bump]

## Design Decisions

[Why direct bumps were preferred, justification for any remaining overrides]

常见错误

错误	修复
直接跳到 overrides	检查：能否升级父依赖？如果不能，semver 范围是否已允许该修复（lockfile 更新）？只有这样才使用 override。
在 override 范围中使用 >=	使用 ^ 以保持在同一个主版本内。>=2.3.2 可能会解析到 4.x。
未检查固定版本与范围版本	pnpm view <parent> dependencies.<pkg> — 如果是有范围的并且修复在范围内，只需执行 pnpm update。
嵌套 override 作用域（a>b>c）	pnpm 仅支持单层："parent>pkg"。对于更深的链条，override 直接父依赖或使用全局 override。
在 override 键中使用版本选择器（pkg@^2）	pnpm 不支持。请改用父级作用域或全局 override。
全局 override 影响多个主版本	"picomatch": ">=4.0.4" 会强制所有 picomatch 到 4.x，破坏需要 2.x 的使用方。当某个包跨多个主版本时，将 override 限定到父依赖。
未检查所有工作区包	同一个依赖可能出现在多个 package.json 文件中（例如，changelogen 同时存在于 tools/releaser 和 tools/scripts）
使用不存在的版本进行 override	在安装前用 pnpm view 验证目标版本是否存在
未回退到 --ignore-scripts	预先存在的原生构建失败会阻塞 pnpm install；使用 --ignore-scripts 以更新 lockfile
破坏性升级缺少代码更改	如果升级改变了 API 默认值，请更新调用代码
在 PR 中忘记附上安全公告链接	始终查找并包含每个漏洞的 GHSA 链接
未经用户确认就应用修复	在做出更改前，先展示完整计划（每个漏洞的策略 + 理由）并获得确认