dependency-upgrader

依存関係のアップグレード

契約を確認する

1. リポジトリの指示を読み、マニフェスト、ラッパー、バージョンカタログ、ロックファイル、選択されているパッケージマネージャー、既存のセキュリティツールを特定します。
2. 対象パッケージ、許可されるバージョン範囲、アップグレードの理由、メジャーバージョンへの移行が対象に含まれるかを確認します。「依存関係を更新する」という指示は、すべてのメジャーバージョンをアップグレードする許可ではなく、互換性のある安定版への最小限の更新として扱います。
3. 編集前に、現在宣言されているバージョンと解決済みバージョン、依存関係の経路、最小限かつ信頼できるベースラインチェックを記録します。
4. 作業ツリーに重複する変更がある場合、または必要なツールを利用できない場合は作業を中止して報告します。パッケージマネージャーを切り替えたり、別のパッケージマネージャーのロックファイルを再生成したりしないでください。

バージョンを選ぶ

1. 最新のレジストリメタデータに加えて、公式リリースノート、移行ガイド、互換性表、セキュリティアドバイザリを確認します。
2. 指定された問題を解決する、最小の安定版を優先します。依頼がない限り、プレリリース版やリリース候補版は選ばないでください。
3. 密接に連携するパッケージはまとめ、それ以外は依存関係を1つずつ、またはリスクの低いグループごとに更新します。
4. メジャーバージョンへの更新では、編集前にランタイム要件、削除された API、設定変更、ロールバックの制約を特定します。

既知の脆弱性を監査する

依存関係をアップグレードする場合も、脆弱性を監査する場合も、references/vulnerability-audit-playbook.md を読みます。

1. バージョンを選ぶ前に、対象となる各依存関係と、その解決済みの推移的依存関係全体を監査します。利用可能な場合は、アップグレードによって持ち込まれた、または残存する脆弱性をベースラインの検出結果と切り分けるため、リポジトリ全体のスキャンも1つ実行します。
2. リポジトリ標準のチェックと GitHub コネクターの Dependabot または依存関係レビューのデータを優先し、その後、エコシステムの監査コマンドと OSV で照合します。単一のデータベースですべてを網羅できるとは考えないでください。
3. すべての検出結果について、解決済みの正確なパッケージ、バージョン、スコープ、依存関係の経路と照合します。GHSA または OSV の識別子と、存在する場合は CVE の別名を記録します。CVE 識別子がないことは、脆弱性がないことを意味しません。
4. 影響を受けるバージョン範囲と修正済みバージョン範囲を、権威あるアドバイザリまたはベンダー通知で確認します。既知の脆弱性への露出、実際の到達可能性、誤検知、取り下げられたアドバイザリ、カバレッジの欠落を区別します。
5. 互換性のある最も近い修正版を提案します。脆弱な推移的依存関係については、最も近い直接依存関係、プラットフォーム、または BOM のアップグレードを優先します。一時的な制約やオーバーライドは、親パッケージの修正が利用できないか、互換性がない場合にのみ使用します。

サプライチェーンのリスクを確認する

リポジトリに既存のポリシーがある場合は、それに従います。ポリシーがない場合は、通常のアップグレードに対して72時間の最低リリース経過時間ゲートを推奨し、緊急のセキュリティ修正に対する例外があれば記録します。Node の場合は、references/node-upgrade-playbook.md にある選択済みパッケージマネージャーの設定を使用します。Gradle または Maven の場合は、リポジトリのポリシーに従うか、公開日時を手動で確認します。パッケージマネージャーに依存しない設定をでっち上げてはいけません。

ロックファイルの差分を受け入れる前に、次の点を確認します。

• 新たに追加された直接依存関係と推移的依存関係、バージョン、レジストリ、URL、整合性値、ライフサイクルスクリプトをすべて確認します。
• 予期しないパッケージの置き換え、新しいメンテナー、プロベナンスの変更、Git や tarball のソース、推移的依存関係の大幅な増加を調査します。
• 選択したパッケージマネージャーとレジストリが対応している場合は、レジストリの署名またはプロベナンスの検証を利用します。ただし、プロベナンスをコードが安全であることの証明として扱ってはいけません。
• リポジトリですでに使用されている場合は、frozen-lockfile、脆弱性、依存関係レビューのチェックを有効なままにします。
• アップグレードを完了させるためだけに、整合性、署名、ポリシー、脆弱性に関するエラーを決して回避してはいけません。

緊急のアドバイザリを受けて、対象を絞った経過時間ゲートの例外を提案できる場合があります。選択した修正とアドバイザリを確認したうえで、ユーザーまたはリポジトリ所有者の明示的な承認を得て、対象を絞った検証に合格した場合にのみ適用します。

適用と検証

1. リポジトリのパッケージマネージャーまたはビルドラッパーを使用し、ロックファイルの形式を維持します。
2. アップグレードを反映するために必要な最小限のマニフェストとロックファイルの変更を行います。
3. パッケージスクリプトを実行する前に差分を確認します。対応している場合は、調査にはロックファイルのみを更新するモードまたはスクリプトを無効にするモードを使用し、必要かつ信頼できる場合にのみスクリプトを有効にします。
4. リスクグループごとに対象を絞ったテストを実行し、その後、リポジトリに関連する CI 相当のチェックを実行します。
5. 最終的に解決された依存関係グラフに対し、同じ脆弱性スキャンを再実行します。対象のアドバイザリが存在しないこと、新たな脆弱性が導入されていないこと、想定される安全なバージョンとパスが選択されていることを確認します。
6. 失敗をベースラインと比較し、無関係な変更はそのまま整えずに元に戻します。

検出されたエコシステムに応じて、references/node-upgrade-playbook.md または references/gradle-upgrade-playbook.md のみを使用します。

報告

古いバージョンと新しい宣言済み／解決済みバージョン、依存関係のパス、アドバイザリ ID と情報源、影響を受ける範囲と修正済み範囲、スキャンの日時と網羅性の不足、理由と緊急度、移行作業、サプライチェーンのチェック、コマンドと結果、ベースラインの検出結果、未解決のリスクを記載します。依存関係が安全だと断言するのではなく、「これらの情報源では既知の脆弱性は見つかりませんでした」と述べます。