audit-dependencies

依存関係の監査

概要

.github/workflows/audit-dependencies.sh によって報告された依存関係の脆弱性を修正します。修正は次の順序で優先します: 直接依存関係のバンプ > ロックファイルの更新 > pnpm オーバーライド。すべてのオーバーライドには、より単純なアプローチが実行できない理由の正当性が必要です。

コアワークフロー

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 はスキルに渡される重大度です（省略時は high がデフォルト）。スクリプトは pnpm audit --prod --json を実行し、対処可能な脆弱性（パッチ済みバージョンが利用可能なもの）をフィルタリングします。high には critical が含まれます。

出力を解析して、以下を含む脆弱なパッケージの重複排除されたリストを作成します:

• パッケージ名と現在のバージョン
• 修正バージョンの要件
• 完全な依存関係チェーン（例: packages/plugin-sentry > @sentry/nextjs > rollup）

2. 脆弱なパッケージごとに

依存関係チェーンをたどる

脆弱なパッケージが次のどちらであるかを特定します:

• 直接依存関係: ワークスペースパッケージの package.json に記載されている
• 推移的依存関係: 別のパッケージによって取り込まれている

まず直接バンプを試す

推移的依存関係については、チェーンをさかのぼって、自分が管理する最も近いパッケージを見つけます:

1. 親パッケージをバンプすることで脆弱性が解消されるかを確認する
   • pnpm view <parent>@latest dependencies.<vulnerable-pkg>
   • 中間バージョンも確認する（修正がマイナーバンプに存在する場合があります）
2. 親のバンプで解消される場合は、破壊的変更を調査する:
   • 変更履歴/リリースノートを確認する
   • 互換性の問題について GitHub issue を検索する
   • このリポジトリで使用されている API サーフェスを確認する（ソースファイルを読む）
   • バージョン範囲がメジャーバージョンの境界をまたぐかを確認する
3. リスク評価とともに調査結果をユーザーに提示する

調査を並列化する: 複数のパッケージで破壊的変更の分析が必要な場合、並列エージェント（パッケージごとに 1 つ）を起動して同時に調査します。

ロックファイルの更新で十分かを確認する

オーバーライドに頼る前に、親のバージョン指定子が固定（3.10.3 のような正確なバージョン）か範囲指定（^2.3.1、~4.0.3 など）かを確認します:

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

範囲に修正バージョンがすでに含まれている場合、必要なのはロックファイルの更新だけです:

pnpm update <vulnerable-pkg> --recursive

package.json の変更は不要です — ロックファイルが古かっただけです。

正当化される場合にのみオーバーライドにフォールバックする

ルートの package.json に pnpm オーバーライドを追加するのは、次の場合のみです:

• 親が修正を満たさない正確なバージョンを固定している
• 親パッケージのどのバージョンでも脆弱性が修正されない
• 親のバンプに破壊的変更のリスクが高い（メジャーな API 変更、テストカバレッジなし、多数のファイルにわたるコード変更が必要）
• ユーザーが親のバンプを別の PR に延期することを明示的に決定した

オーバーライドの形式: "<parent>><vulnerable-pkg>": "^<fixed-version>"

オーバーライド構文のルール:

• >= ではなく ^ 範囲を使用してください。>= はメジャーバージョンをまたぐ可能性があり、予期しない解決を引き起こします（例: "picomatch": ">=2.3.2" が 4.x に解決されることがあります）。
• pnpm は単一レベルの親スコープのみをサポートします: "parent>pkg" は機能しますが、"grandparent>parent>pkg" は機能しません。
• pnpm はオーバーライドキー内のバージョンセレクターをサポートしていません: "pkg@^2" は機能しません。
• 同じ脆弱なパッケージが多数の推移的パスを通じて現れる場合、グローバルオーバーライドが必要になることがあります。別のメジャーバージョン上の無関係なコンシューマーに影響しないよう注意してください — パッケージがツリー全体で複数のメジャーバージョンにまたがる場合は、親スコープのオーバーライドを使用してください。
• pnpm はルートワークスペースの package.json の overrides のみを尊重します。ワークスペースパッケージ内のオーバーライドは無視されます。

オーバーライドを追加する前に、対象バージョンが存在することを確認します:

pnpm view <pkg>@<version> version

3. 計画をユーザーに提示する

修正を適用する前に、各脆弱性、提案された修正戦略（直接バンプ / ロックファイルの更新 / オーバーライド）、および正当性を示すサマリーテーブルをユーザーに提示します。先に進む前に確認を得てください。

4. 修正を適用する

• 直接バンプの場合は package.json ファイルを編集する
• ロックファイルのみの修正の場合は pnpm update <pkg> --recursive を実行する
• オーバーライドの場合はルートの package.json の pnpm.overrides を編集する（アルファベット順を維持する）
• 直接バンプによって動作が変わる場合は、利用側のコードを更新する（例: API のデフォルトが変更された場合に allowOverwrite: true を追加する）

5. インストールと検証

pnpm install

ネイティブビルドエラー（例: better-sqlite3）によりインストールが失敗する場合は、次の方法にフォールバックします:

pnpm install --ignore-scripts

その後、同じ severity で監査スクリプトを再実行します:

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

監査スクリプトは終了コード 0 で終了する必要があります。脆弱性が残っている場合は、他のワークスペースパッケージに同じ依存関係の追加のインスタンスがないか確認してください。

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、severity、1 行の説明
• NVD のリンクよりも GHSA のリンク（https://github.com/advisories/GHSA-xxxx-xxxx-xxxx）を優先する

CVE の検索を並列化する: すべてのパッケージにわたって CVE を同時に検索するために、並列エージェントをディスパッチします。

8. コミットと PR の作成

Conventional Commits 形式でコミットします:

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]

よくある間違い

間違い	修正
すぐにオーバーライドに飛びつく	確認: 親をバンプできますか？できない場合、semver 範囲がすでに修正を許可していますか（ロックファイルの更新）？その場合にのみオーバーライドします。
オーバーライド範囲で >= を使用する	同じメジャーバージョン内に留まるには ^ を使用します。>=2.3.2 は 4.x に解決される可能性があります。
固定 vs 範囲を確認しない	pnpm view <parent> dependencies.<pkg> — 範囲指定で修正が範囲内にある場合は、単に pnpm update を実行します。
ネストされたオーバーライドのスコープ（a>b>c）	pnpm は単一レベルのみサポートします: "parent>pkg"。より深いチェーンでは、直接の親をオーバーライドするか、グローバルオーバーライドを使用します。
オーバーライドキーのバージョンセレクター（pkg@^2）	pnpm ではサポートされていません。代わりに親スコープまたはグローバルオーバーライドを使用してください。
複数のメジャーバージョンに影響するグローバルオーバーライド	"picomatch": ">=4.0.4" はすべての picomatch を 4.x に強制し、2.x を必要とするコンシューマーを壊します。パッケージが複数のメジャーにまたがる場合は、親にスコープを限定してください。
すべてのワークスペースパッケージを確認しない	同じ依存関係が複数の package.json ファイルに現れることがあります（例: changelogen が tools/releaser と tools/scripts の両方に）
存在しないバージョンでオーバーライドする	インストール前に pnpm view でターゲットバージョンが存在することを確認してください
--ignore-scripts へのフォールバックを行わない	既存のネイティブビルドの失敗が pnpm install をブロックします。--ignore-scripts を使用してロックファイルを更新してください
破壊的バンプに対するコード変更が欠けている	バンプが API デフォルトを変更する場合は、呼び出しコードを更新してください
PR にアドバイザリリンクを忘れる	各脆弱性について常に GHSA リンクを調べて含めてください
ユーザーの確認なしに修正を適用する	完全な計画（脆弱性ごとの戦略 + 正当化）を提示し、変更を加える前に確認を得てください