dependency-upgrade

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

関連スキル

• sap-hana-cli：依存関係を考慮したデータベースツールのワークフローとアップグレードガイダンス
• sap-cap-capire：CAP の依存関係に安全なランタイムとサービスの設定ガイダンス
• sap-fiori-tools：ツールがフロントエンドパッケージを扱う際の、安全な UI5/Fiori 依存関係戦略

サプライチェーンセキュリティ、互換性分析、段階的なロールアウト、主要なすべてのパッケージマネージャーにわたる包括的なテストを考慮しながら、依存関係のアップグレードを管理します。

このスキルを使用する場面

• フレームワークやライブラリのメジャーバージョンをアップグレードする場合
• サプライチェーン攻撃の防止（クールダウン、スクリプトのブロック、ロックファイルの強化）を設定する場合
• 安全なパッケージマネージャーの設定を行う場合
• 依存関係の競合やピア依存関係の問題を解決する場合
• テストを伴う段階的なアップグレード手順を計画する場合
• Renovate、Dependabot、Snyk を使って依存関係の更新を自動化する場合
• 脆弱性について依存関係を監査する場合
• CI/CD の依存関係セキュリティワークフローを設定する場合

2 つの動作モード

対話型 — 設定をカスタマイズするための質問に順に回答します。新規セットアップに使用します。

デフォルト — 推奨設定をすぐに適用します：7 日間のクールダウン、すべてのスクリプトをブロック、frozen-lockfile、lockfile-lint、クールダウンを設定した Dependabot。必要に応じてカスタマイズできます。

対話型セットアップの流れ

ユーザーがカスタマイズした設定を希望する場合は、以下の選択肢を順に確認します。デフォルトモードを使用する場合は、このセクション全体を省略してください。

ティア 1：必須の選択

設定を生成する前に、必ず次の 3 つの質問をします。

1. パッケージマネージャー

「このプロジェクトではどのパッケージマネージャーを使用していますか？」

回答	生成されるもの
npm	.npmrc
Bun	bunfig.toml
pnpm	pnpm-workspace.yaml
Yarn	.yarnrc.yml
Deno	deno.json の設定

2. クールダウン期間

「新しく公開されたパッケージは、インストール前に何日間経過させますか？これにより、悪意のあるパッケージが数日以内に発見され、公開停止されるサプライチェーン攻撃を防げます。」

オプション	日数	用途
積極的	3	ほとんどのタイポスクワッティングを検出します
推奨	7	ほとんどのプロジェクトに適したバランスです
慎重	14	重要なシステムや本番システム向けです
厳重	21	Snyk の組み込みデフォルトと一致します
カスタム	N	ユーザーが指定します

3. インストール後スクリプトのポリシー

「ライフサイクルスクリプト（postinstall、preinstall）をどのように扱いますか？これらはサプライチェーン攻撃の最大の攻撃経路です。」

オプション	動作
すべてブロック（推奨）	--ignore-scripts + allow-git=none
許可リスト	デフォルトでブロックし、信頼できる特定のパッケージを許可します
確認のみ	警告しますが、ブロックはしません

ティア 2: セキュリティツール（バッチとして提供）

「これらのセキュリティ機能のうち、どれを設定しますか？該当するものをすべて選択してください。」

4. CI/CD 自動化ツール

回答	生成されるもの
Dependabot	クールダウン付きの .github/dependabot.yml
Renovate	minimumReleaseAge 付きの renovate.json
Snyk	設定不要（21 日間のクールダウンが組み込み済み）
なし	スキップ

5. 自動マージポリシー

オプション	動作
なし	すべての更新に手動レビューが必要
マイナー+パッチのみ	安全な更新を自動マージし、メジャーはレビュー
承認付きですべて	チームの承認後に自動マージ

6. 更新スケジュール

オプション	設定値
毎日	"daily"
毎週（デフォルト）	"weekly"
隔週	"biweekly"
毎月	"monthly"

7. インストール時のセキュリティツール

「どのセキュリティツールで依存関係のインストールを保護しますか？」

オプション	無料？	機能
socket npm wrapper	はい（ベータ）	npm/npx をラップし、インストール前に悪意のあるパッケージをブロックします。システム全体で有効にするには socket wrapper on を実行します。
npq	はい	インストール前の監査ツール（CVE、タイポスクワット、経過期間、来歴のチェック）
Socket Firewall (sfw)	いいえ	リアルタイムの詳細分析、悪意のあるパッケージをブロック
socket npm + npq	はい	両方の無料ツールを組み合わせ
なし	—	スキップ

認証や無料機能と認証済み機能の違いを含む Socket CLI の完全なセットアップについては、references/socket-cli-guide.md を読み込んでください。

8. ロックファイルの検証

オプション	動作
はい（推奨）	lockfile-lint + CI スクリプトを追加
いいえ	スキップ

ティア 3: 高度なオプション（ユーザーがオプトインした場合のみ）

「高度なオプションを設定しますか？」

9. Dev Containers — 堅牢化された .devcontainer/devcontainer.json を生成（はい/いいえ）

10. シークレットマネージャー — 1Password CLI / Infisical / なし

11. pnpm トラストポリシー — trustPolicy: no-downgrade を有効化（pnpm 10.21+ のみ、はい/いいえ）

12. クールダウンの除外 — クールダウンを回避するパッケージ名（例: @types/react、typescript、esbuild）

セキュリティファーストのアップグレード原則

1. インストール前にクールダウン — 新しいパッケージバージョンがコミュニティによって検証されるまで 7 日間待ちます
2. インストール後スクリプトをブロック — npm install 中の任意コード実行を防ぎます
3. CI でロックファイルを固定 — 決定論的なインストールを使用します（npm ci、--frozen-lockfile）
4. ロックファイルの完全性を検証 — lockfile-lint を使用してインジェクションを検出します
5. 信頼する前に監査 — インストール前に npq または Socket CLI を使用してパッケージをチェックします
6. 段階的にアップグレード — 一度に 1 つのメジャーバージョンずつ、各間にテストを挟みます
7. 盲目的にアップグレードしない — レビューなしで npm update や npm-check-updates -u を避けます
8. 前後でスキャン — socket scan を使用して CVE を超えたサプライチェーンの問題を検出します

クールダウン期間: サプライチェーン攻撃を防ぐ

新しく公開されたパッケージには、数時間以内に発見される悪意のあるコードが含まれている可能性があります。インストールを遅延させるクールダウン期間を設定してください。

クイックセットアップ

npm（.npmrc）:

min-release-age=7

Bun（bunfig.toml）:

[install]
minimumReleaseAge = 604800  # 7 days in seconds
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

pnpm（pnpm-workspace.yaml）:

minimumReleaseAge: 10080  # 7 days in minutes
minimumReleaseAgeExclude:
  - '@types/react'
  - typescript

Yarn（.yarnrc.yml）:

npmMinimalAgeGate: "7d"
npmPreapprovedPackages:
  - "@types/react"
  - "typescript"

パッケージマネージャーごとの詳細な設定、CI ツール連携、除外パターンについては、references/cooldown-config-guide.md を読み込んでください。

コピー＆ペーストですぐに使える設定ファイルには templates/<pm>-security.tmpl を使用してください。

インストール後スクリプトを無効化する

インストール後スクリプトは最も一般的なサプライチェーン攻撃の経路です（Shai-Hulud、Nx、event-stream のインシデント）。

クイックセットアップ

npm:

npm config set ignore-scripts true
npm config set allow-git none

Bun: デフォルトで無効。package.json で特定のパッケージを許可します:

{ "trustedDependencies": ["esbuild", "sharp"] }

pnpm (10.0+): デフォルトで無効。pnpm-workspace.yaml で特定のパッケージを許可します:

allowBuilds:
  esbuild: true
strictDepBuilds: true  # Hard error on unreviewed scripts

pnpm の trustPolicy、blockExoticSubdeps、@lavamoat/allow-scripts を含むパッケージマネージャーごとの完全な堅牢化については、references/package-manager-security.md を読み込んでください。

再現可能で固定されたインストール

再現可能なビルドを確保するため、CI では必ず固定インストールコマンドを使用してください。

パッケージマネージャー	コマンド	動作
npm	npm ci	node_modules を削除し、ロックファイルに記載された正確なバージョンをインストールします
Bun	bun install --frozen-lockfile	ロックファイルに不整合がある場合は失敗します
pnpm	pnpm install --frozen-lockfile	ロックファイルに不整合がある場合は失敗します
Yarn	yarn install --immutable --immutable-cache	ロックファイルとキャッシュを検証します
Deno	deno install --frozen	固定インストールを行います

すべてのロックファイルをバージョン管理にコミットしてください：package-lock.json、bun.lock、pnpm-lock.yaml、yarn.lock、deno.lock。

ロックファイルの検証

ロックファイルへのインジェクション攻撃を検出するため、lockfile-lint をインストールして設定します。

npm install --save-dev lockfile-lint

{
  "scripts": {
    "lint:lockfile": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https",
    "preinstall": "npm run lint:lockfile"
  }
}

注：lockfile-lint は現在、Bun の bun.lock / bun.lockb 形式に対応していません。

インストール前のセキュリティ監査

npq — インストール前監査ツール

npm install -g npq
npq install <package>          # Audit before installing
npq install <package> --dry-run # Audit without installing

# Shell alias for seamless use
alias npm='npq-hero'

# Use with other PMs
NPQ_PKG_MGR=pnpm npq install <package>
NPQ_PKG_MGR=bun npq install <package>

Socket Firewall (sfw) — リアルタイムブロッカー

npm install -g sfw
sfw npm install <package>      # Blocks malicious packages
sfw pnpm add <package>
sfw yarn add <package>

npq と sfw の詳細な比較、およびそれぞれの検証内容については、references/supply-chain-security.md を読み込んでください。

Socket CLI の統合

Socket CLI は、基本的な脆弱性スキャンにとどまらない予防的なサプライチェーンセキュリティを提供します。マルウェア検出、タイポスクワッティング、抗議目的のソフトウェア、インストールスクリプトのリスク、ライセンスコンプライアンスを対象とします。

予防的なアップグレードワークフロー

1. PRE-UPGRADE:   socket scan create --report          → establish baseline
2. EVALUATE:      socket package score npm <pkg>@<ver>  → assess target package safety
3. SAFE INSTALL:  socket npm install <pkg>              → block malicious packages
4. POST-UPGRADE:  socket scan create --report          → verify no new alerts
5. DIFF:          socket scan diff <before> <after>     → see exactly what changed
6. FIX:           socket fix --minimum-release-age 7d   → auto-fix any new CVEs
7. OPTIMIZE:      socket optimize                       → apply security overrides

クイックリファレンス

# Install
npm install -g socket

# Authenticate (required for scans, fixes, package scores)
socket login

# Check a package before upgrading
socket package score npm <package>

# Scan your whole project
socket scan create --report

# Auto-fix CVEs (complements Dependabot/Renovate)
socket fix --minimum-release-age 7d

# Gate CI on security policy
socket ci

# Safe npm wrapper (free, no auth needed)
socket wrapper on

包括的なコマンドリファレンス、CI ワークフローテンプレート、アラートカテゴリ、無料機能と認証が必要な機能の一覧については、references/socket-cli-guide.md を読み込んでください。

依存関係の分析

# Audit for vulnerabilities
bun audit       # Bun
npm audit       # npm
yarn audit      # Yarn

# Socket: deep security assessment (CVEs + supply chain + license)
socket package score npm <package>
socket scan create --report

# Check for outdated packages
bun outdated
npm outdated

# Interactive upgrade (safe — review each)
bunx npm-check-updates --interactive

# Analyze dependency tree
npm ls <package-name>
yarn why <package-name>

段階的なアップグレード戦略

依存関係を一度に1つずつアップグレードし、その都度テストを行ってください。

# 1. Create feature branch
git checkout -b upgrade/<package>-<version>

# 2. (Optional) Baseline scan — capture current state
socket scan create --report

# 3. Evaluate target package before upgrading
socket package score npm <package>@<version>

# 4. Upgrade single package
bun add <package>@<version>

# 5. Test immediately
bun test && bunx tsc --noEmit && bun run build

# 6. (Optional) Post-upgrade scan — verify no new alerts
socket scan create --report

# 7. Commit and continue
git add -A && git commit -m "chore: upgrade <package> to <version>"

codemod による自動化、カスタム移行スクリプト、ピア依存関係の処理については、references/staged-upgrades.md を読み込んでください。

バージョン互換性の表（React 18/19、Next.js 13-15、TypeScript、Tailwind 3/4）については、references/compatibility-matrix.md を読み込んでください。

クールダウン期間を設けた自動更新

CI/CD ツールがクールダウン期間を遵守するように設定します。

Dependabot (.github/dependabot.yml)

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 7

Renovate (renovate.json)

{
  "extends": ["config:base"],
  "minimumReleaseAge": "7 days",
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "minimumReleaseAge": "14 days"
    }
  ]
}

Snyk

Snyk には、アップグレード PR 用の21日間のクールダウン期間が組み込まれています。設定は不要です。

Socket Fix（Dependabot/Renovate を補完）

Socket Fix は、インテリジェントなアップグレード計画によって CVE を自動的に解決します。他の自動化ツールと並行して実行され、特に CVE の修正に焦点を当てます。

# Fix all fixable CVEs with cooldown alignment
socket fix --minimum-release-age 7d

# Conservative: no major version bumps
socket fix --minimum-release-age 7d --no-major-updates

# Target specific CVEs
socket fix --id GHSA-hhq3-ff78-jv3g --minimum-release-age 7d

# Preview without applying
socket fix --no-apply-fixes --minimum-release-age 7d

CI オートパイロットモード（修正 PR の自動作成と自動マージ）には、templates/socket-fix-ci.tmpl を使用してください。

--autopilot、--range-style、--pr-limit を含む socket fix の全オプションについては、references/socket-cli-guide.md を読み込んでください。

完全な設定ファイルには、templates/dependabot-security.tmpl または templates/renovate-security.tmpl を使用してください。

公開時のセキュリティ

パッケージのメンテナー向け：

# Enable 2FA
npm profile enable-2fa auth-and-writes

# Publish with provenance (cryptographic build proof)
npm publish --provenance

# Trusted publishing via OIDC (eliminates long-lived tokens)
# Configure on npmjs.com, then:
# In GitHub Actions: permissions: id-token: write

OIDC の設定や依存関係ツリーの縮小を含む、公開時のセキュリティに関する完全なガイドについては、references/supply-chain-security.md を読み込んでください。

開発環境の強化

依存関係の実行環境をホストシステムから隔離します。

• Dev Containers — 悪意のあるパッケージの影響範囲を限定します
• シークレット管理 — 平文の .env ファイルの代わりに、1Password CLI または Infisical を使用します
• 依存関係ツリーの縮小 — 一般的なパッケージをネイティブ JS に置き換えます

強化された Dev Container の設定には、templates/devcontainer-security.tmpl を使用してください。

Dev Container のセットアップ、シークレット管理、依存関係の縮小パターンについては、references/secrets-and-containers.md を読み込んでください。

テスト戦略

各アップグレード後に、すべてのレベルでテストを実行します。

# 1. Static analysis (fastest)
bunx tsc --noEmit && bun run lint

# 2. Unit tests
bun test

# 3. Build check
bun run build

# 4. Integration / E2E (after major upgrades)
bun run test:e2e

テストピラミッド全体、CI との統合、バンドル分析については、references/testing-strategy.md を読み込んでください。

ロールバック計画

#!/bin/bash
git stash
git checkout -b upgrade/<package>

bun add <package>@latest

if bun test && bun run build; then
  git add package.json bun.lock
  git commit -m "chore: upgrade <package>"
else
  echo "Upgrade failed, rolling back"
  git checkout main
  git branch -D upgrade/<package>
  bun install
fi

アップグレードのチェックリスト

Pre-Upgrade:
- [ ] Review current dependency versions
- [ ] Read changelogs for breaking changes
- [ ] Create feature branch
- [ ] Tag current state (git tag pre-upgrade)
- [ ] Run full test suite (baseline)
- [ ] Verify cooldown period is configured

Security Pre-Checks:
- [ ] Post-install scripts are disabled
- [ ] Lockfile validation is active
- [ ] Install auditing tools configured (if applicable)
- [ ] CI uses frozen-lockfile install
- [ ] Run `socket scan create --report` for baseline (if Socket available)

During Upgrade:
- [ ] Upgrade one dependency at a time
- [ ] Check target package: `socket package score npm <pkg>` (if Socket available)
- [ ] Respect cooldown period (don't force latest)
- [ ] Update peer dependencies
- [ ] Fix TypeScript errors
- [ ] Run test suite after each upgrade
- [ ] Check bundle size impact

Post-Upgrade:
- [ ] Post-upgrade scan: `socket scan diff` to verify no new alerts (if Socket available)
- [ ] Consider `socket fix --minimum-release-age 7d` for any new CVEs
- [ ] Full regression testing
- [ ] Performance testing
- [ ] Update documentation
- [ ] Deploy to staging
- [ ] Monitor for errors
- [ ] Deploy to production

よくある落とし穴

• すべての依存関係を一度にアップグレードする（段階的にアップグレードしてください）
• 確認せずに npm update や npm-check-updates -u を実行する
• 個々のアップグレードごとにテストしない
• ピア依存関係の警告を無視する
• ロックファイルの更新やコミットを忘れる
• 変更履歴に記載された破壊的変更の説明を読まない
• メジャーバージョンを順に進めずに飛ばす
• ロールバック計画を立てない
• npmjs.org に表示されるソースコードを信頼する（実際の tarball と異なる場合があります）
• post-install スクリプトを有効のままにする（最も一般的な攻撃経路です）
• 新しいパッケージバージョンにクールダウン期間を設定しない

リファレンスを読み込むタイミング

SKILL.md のクイックリファレンスを超える詳細情報が必要な場合は、以下のリファレンスファイルを読み込んでください。

このファイルを読み込む	読み込むタイミング
references/cooldown-config-guide.md	特定のパッケージマネージャーのクールダウン設定、CI ツールとの統合、または除外パターンの設定
references/package-manager-security.md	pnpm の信頼ポリシー、blockExoticSubdeps、パッケージマネージャー横断のチートシートを含む、パッケージマネージャーごとの包括的な強化ガイド
references/supply-chain-security.md	攻撃経路、インシデントの履歴、npq と sfw と Socket CLI の比較、パブリッシャーのセキュリティ（2FA、来歴、OIDC）の理解
references/secrets-and-containers.md	開発コンテナーの設定、1Password/Infisical を使ったシークレット管理
references/socket-cli-guide.md	スキャン、修正、パッケージのスコアリング、CI 統合、ラッパーモード、アラートカテゴリでの Socket CLI の使用
references/compatibility-matrix.md	React、Next.js、TypeScript、Tailwind のアップグレードにおけるバージョン互換性の確認
references/staged-upgrades.md	Codemod の自動化、カスタム移行スクリプト、ピア依存関係の処理、ワークスペースのアップグレード
references/testing-strategy.md	包括的なテストピラミッド、CI 統合、バンドル分析、パフォーマンステスト

テンプレートファイル

templates/ にすぐに使える設定ファイルがあります。

テンプレート	用途
npmrc-security.tmpl	スクリプト無効化とクールダウンを設定した安全な .npmrc
bunfig-security.tmpl	クールダウンと除外を設定した安全な bunfig.toml
pnpm-workspace-security.tmpl	クールダウン、allowBuilds、trustPolicy を設定した安全な pnpm-workspace.yaml
yarnrc-security.tmpl	年齢ゲートと事前承認済みパッケージを設定した安全な .yarnrc.yml
dependabot-security.tmpl	7 日間のクールダウンを設定した Dependabot 構成
renovate-security.tmpl	minimumReleaseAge と自動マージルールを設定した Renovate 構成
devcontainer-security.tmpl	セキュリティオプションで強化した開発コンテナー
socket-fix-ci.tmpl	GitHub Actions：クールダウンに合わせた CVE 修正を行う Socket Fix autopilot
socket-scan-ci.tmpl	GitHub Actions：すべての push/PR で Socket CI セキュリティゲートを実行