dependency-upgrade

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

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

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

• フレームワークやライブラリのメジャーバージョンをアップグレードする
• サプライチェーン攻撃の防止策（クールダウン、スクリプトのブロック、ロックファイルの強化）を設定する
• 安全なパッケージマネージャーの設定を行う
• 依存関係の競合やピア依存関係の問題を解決する
• テストを伴う段階的なアップグレード計画を立てる
• 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 config

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	はい	2 つの無料ツールを組み合わせます
なし	—	スキップ

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

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

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

Tier 3：高度なオプション（ユーザーが選択した場合のみ）

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

9. Dev Containers — 強化された .devcontainer/devcontainer.json を生成する（はい／いいえ）

10. Secrets Manager — 1Password CLI ／ Infisical ／ なし

11. pnpm Trust Policy — 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"

PM ごとの詳細な設定、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 を含む、PM ごとの完全な強化設定については、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. 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 を読み込んでください。

開発環境の強化

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

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

セキュリティを強化した開発コンテナーの設定には、templates/devcontainer-security.tmpl を使ってください。

開発コンテナーの設定、シークレット管理、依存関係削減のパターンについては、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	特定の PM 向けのクールダウン設定、CI ツールとの連携、除外パターンの設定
references/package-manager-security.md	pnpm の信頼ポリシー、blockExoticSubdeps、PM 間のチートシートを含む、PM ごとの完全なセキュリティ強化ガイド
references/supply-chain-security.md	攻撃ベクトル、インシデント履歴、npq と sfw と Socket CLI の比較、公開者のセキュリティ（2FA、provenance、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 自動操縦
socket-scan-ci.tmpl	GitHub Actions：すべてのプッシュ／PR に対する Socket CI セキュリティゲート