dependency-management

依存関係の管理

サードパーティ製の依存関係は、現代のソフトウェアにおいて最も強力であると同時に、最も危険な要素です。依存関係の管理ミスが原因で、log4shell が発生しました。Left-pad はわずか 11 分で数千ものビルドを停止させました。依存関係の混同を悪用したサプライチェーン攻撃は、大企業にも被害をもたらしました。このスキルでは、依存関係の選定、固定、監査、更新、削除というライフサイクル全体を、本番環境にふさわしい規律で扱います。

使用する場面

次のような場合に使用します：

• 新しい依存関係を追加するかどうかを判断するとき
• バージョン固定の方針（完全固定、範囲指定、ロックファイルのみ）を決めるとき
• 自動更新のワークフロー（Renovate、Dependabot）を設定するとき
• npm audit、pip audit、Snyk、Socket.dev を使ってセキュリティ監査を行うとき
• ライセンスの互換性（MIT／Apache／GPL）をスキャンするとき
• ソフトウェア部品表（SBOM）を生成するとき
• peer dependency の競合や npm overrides を解決するとき
• セキュリティ勧告や CVE への対応を行うとき
• タイポスクワッティングや依存関係の混同攻撃を検出するとき

次の用途には使用しません：

• 内部のモノレポにおけるパッケージ管理（monorepo-management を使用してください）
• npm、PyPI、crates.io への独自パッケージの公開
• 依存関係の管理以外のパッケージマネージャー設定（ワークスペース設定など）
• ベンダリングやエアギャップ環境（これらがあることには触れますが、この範囲の対象外です）

---

主要な判断：この依存関係を追加すべきか？

flowchart TD
    Start[Want to add a dependency?] --> Size{How much code does it replace?}
    Size -->|< 20 lines| Write[Write it yourself]
    Size -->|20-200 lines| Q2{Trivial to implement correctly?}
    Size -->|> 200 lines| Q3{Check the package}

    Q2 -->|Yes, pure logic| Write
    Q2 -->|No, edge cases / locale / timezone| Q3

    Q3 --> Audit{Run audit checks}
    Audit --> Downloads{Weekly downloads?}
    Downloads -->|< 10k| HighRisk[High risk: low adoption]
    Downloads -->|10k-100k| MedRisk[Medium: check actively]
    Downloads -->|> 100k| Maintained{Actively maintained?}

    Maintained -->|Last commit > 2 years| Fork[Consider fork or alternative]
    Maintained -->|Recent commits| License{License compatible?}

    License -->|GPL in proprietary| Reject[REJECT: license issue]
    License -->|MIT / Apache 2.0| Security{npm audit / Socket.dev scan?}

    Security -->|CVEs unfixed| Reject
    Security -->|Clean| Transitive{Transitive dep count?}

    Transitive -->|> 50 new deps| Reconsider[Reconsider: high blast radius]
    Transitive -->|< 50 new deps| Accept[Add with pinned version]

    HighRisk --> Fork
    MedRisk --> Maintained

---

バージョン固定の方針

Semver の意味をおさらい

^1.2.3  = >= 1.2.3, < 2.0.0   (minor + patch updates allowed)
~1.2.3  = >= 1.2.3, < 1.3.0   (patch updates only)
1.2.3   = exactly 1.2.3        (locked)
*       = any version           (never use)

使い分け

方針	使用箇所	理由
完全固定（1.2.3）	本番アプリ	ビルドを再現可能にしつつ、ロックファイルで柔軟性を確保できます
チルダ（~1.2.3）	公開するライブラリ	パッチの安全性を確保できます。マイナーバージョンの変更は利用者に影響する可能性があります
キャレット（^1.2.3）	開発ツールのみ	フォーマッターやリンターなら、変更を受け入れても差し支えありません
ロックファイルを基準にする	すべての本番環境	npm ci、pip install --frozen、cargo build
* は使わない	どこでも	重大な問題につながります。ビルド時に常に最新のバージョンがインストールされます

アンチパターン：本番アプリの依存関係にキャレットを使う

初心者：「バグ修正を自動で常に取得できるように ^ を使っています。そのほうが安全です。」 エキスパート：キャレット範囲を指定すると、semver 上の破壊的変更が認識されないままインストールされる可能性があります。semver は努力目標であって、強制されるものではありません。マイナーバージョンで破壊的変更を含むパッケージがリリースされることも珍しくありません。ロックファイルによって開発者のマシンではこうした事態を防げますが、npm ci ではなく npm install を実行する CI 環境では、気づかないうちにアップグレードされます。直接依存関係はバージョンを完全に固定し、推移的依存関係はロックファイルで管理してください。更新内容は、Renovate や Dependabot の PR を通じて慎重に確認しましょう。 検出方法：本番アプリのランタイム依存関係に ^ が付いていないか、package.json を確認します。新しいクローンで npm ci を実行し、インストールされた依存関係ツリーを直近のデプロイと比較します。

---

更新ワークフローの判断

flowchart TD
    Update[How to handle updates?] --> Auto{Use automation?}
    Auto -->|Yes| Tool{Which tool?}
    Auto -->|No, manual| Manual[Monthly audit: npm outdated / pip list --outdated]

    Tool -->|GitHub repo| Dependabot[GitHub Dependabot]
    Tool -->|Any platform| Renovate[Renovate Bot — more powerful]

    Dependabot --> DConfig[Configure .github/dependabot.yml]
    Renovate --> RConfig[Configure renovate.json]

    DConfig --> DGroup{Group updates?}
    RConfig --> RGroup{Group updates?}

    DGroup -->|Yes| DGrouped[Group patch updates together]
    DGroup -->|No| DPR[One PR per dependency]
    RGroup -->|Yes| RGrouped[Group by type: devDeps patch / prod minor]
    RGroup -->|No| RPR[One PR per dependency]

    RGrouped --> AutoMerge{Automerge safe?}
    DGrouped --> AutoMerge

    AutoMerge -->|Dev deps + patch only| EnableAM[Enable automerge with test gate]
    AutoMerge -->|Prod deps, major versions| RequireReview[Require human review]

---

セキュリティ監査

監査スタック

最も高速で無料のものから、最も詳細なものへ順に実行します。

# 1. npm audit (built-in, free, fast — checks known CVEs)
npm audit
npm audit --audit-level=high    # Only high+ severity
npm audit fix                   # Auto-fix where possible
npm audit fix --force           # ⚠️ May break API — review first

# 2. pip audit (Python equivalent)
pip install pip-audit
pip-audit
pip-audit --fix                 # Write fixed requirements.txt

# 3. Socket.dev (supply chain analysis beyond CVEs)
npx socket check                # Checks for malicious behavior, typosquatting

# 4. Snyk (deeper analysis, CI integration)
npx snyk test
npx snyk monitor                # Continuous monitoring

# 5. SBOM generation (for compliance)
npx @cyclonedx/cyclonedx-npm --output-format json > sbom.json
# Python: pip install cyclonedx-bom && cyclonedx-py -p

アンチパターン：セキュリティ勧告を無視する

初心者：「監査で脆弱性が見つかりましたが、開発用の依存関係か、使われていないコードパスにあります。リスクはありません。」 エキスパート：開発用の依存関係が本番環境に影響する経路は 2 つあります。（1）本番コードを処理するビルドツールが侵害される場合、（2）勧告では「開発用のみ」とされていますが、実際にはそのパッケージが本番バンドルに含まれている場合です。npm ls <package> を実行して、依存関係の経路を確認してください。本当に開発用のみのパッケージ（mocha、jest、eslint）なら、中程度の深刻度の勧告は対応を延期できる場合があります。開発用の依存関係であっても、重大または高深刻度の脆弱性は、SLA の期限内に解決してください。「リスクなし」は評価であり、無視してよいという意味ではありません。判断内容を記録してください。 検出方法：npm audit --production を実行して、本番環境のみの依存関係に対象を絞ります。npm ls <vulnerable-pkg> を確認し、どのパッケージが依存しているかを把握します。

---

サプライチェーンセキュリティ

タイポスクワッティングの検出

よくある攻撃パターン：

• lodash → 1odash（文字の l を数字の 1 に置き換える）
• express → expres（文字を省略する）
• react → React（大文字・小文字の違い — 大文字・小文字を区別するレジストリ）
• @org/package → org-package（スコープの混同）

# Socket.dev catches most of these
npx socket check

# Manual: verify before install
npm view <package-name>         # Check metadata: author, description, repo URL
npm view <package-name> repository  # Verify GitHub repo matches official source

依存関係の混乱攻撃

攻撃者が、プライベートな @org/package と同じ名前のパブリックパッケージを公開します。パッケージマネージャーは、バージョン番号が高いため、パブリックパッケージを取得します。

防止策：

# npm: Use .npmrc scoped registry config
@your-org:registry=https://your-private-registry.example.com

# Or set resolutions/overrides to lock the source
# package.json:
{
  "overrides": {
    "@your-org/internal-package": "npm:@your-org/internal-package@^1.0.0"
  }
}

ロックファイルの整合性

# Never commit node_modules — commit only the lockfile
# Verify lockfile integrity after pulls
npm ci                          # Fails if lockfile doesn't match package.json
                                # NEVER use npm install in CI

# Python: use pip-compile for deterministic locks
pip install pip-tools
pip-compile requirements.in     # Generates pinned requirements.txt
pip-sync requirements.txt       # Install exactly this

---

ライセンスのコンプライアンス

互換性マトリックス

プロジェクト	MIT 依存関係	Apache 2.0 依存関係	LGPL 依存関係	GPL 依存関係
プロプライエタリ	OK	OK（帰属表示）	OK（動的リンク）	拒否
MIT/Apache	OK	OK	OK	複雑
GPL	OK	OK	OK	OK

# Scan all licenses in your dependency tree
npx license-checker --production --onlyAllow "MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC;0BSD"
npx license-checker --production --failOn "GPL;AGPL"

# Python
pip install pip-licenses
pip-licenses --format=markdown --order=license

アンチパターン：些細な機能のために依存関係を過剰に追加する

初心者：npm install is-odd（実在するパッケージで、週間ダウンロード数は 5,400 万件）。1 行のコード n % 2 !== 0 を含むパッケージをインストールします。 エキスパート：left-pad の事件（2016 年）は、些細なユーティリティパッケージが運用上の負担になることを示しました。本番環境で使う依存関係はすべて、CVE の潜在的な発生源、サプライチェーン攻撃の攻撃対象領域、semver の競合の発生源、そして認知負荷の要因となります。パッケージを追加する前に、README を ChatGPT に貼り付けて「中核となる機能は < 20 行ですか？」と尋ねてください。日付操作、文字列ユーティリティ、数学演算には、関数を自分で実装してください。ローカライズ、暗号化、プロトコル解析には、実績のあるライブラリを使用してください。 検出：npx cost-of-modules を実行するか、npm ページでソースコードのサイズを確認してください。重要な領域のパッケージで 10KB 未満のものは、ほぼ必ず置き換え可能です。 経緯：left-pad 事件後（2016 年）、エコシステムではこの問題への認識が高まりましたが、このパターンは今も続いています。2024 年の polyfill.io CDN の侵害は、CDN 依存関係にも同じことが当てはまると示しました。

---

npm の Overrides と Resolutions

直接の依存関係が更新されていない場合に、脆弱な間接依存関係を修正するために使用します：

// package.json — npm overrides (npm 8.3+)
{
  "overrides": {
    "semver": ">=7.5.2",           // Force minimum version across all deps
    "lodash": "4.17.21",           // Force exact version
    "vulnerable-pkg": {
      "sub-dependency": "^2.0.0"   // Scoped: only for this parent
    }
  }
}

// package.json — yarn/pnpm resolutions
{
  "resolutions": {
    "semver": ">=7.5.2"
  }
}

注意：Overrides は、古い API を必要とするパッケージを壊すことがあります。追加した後は、必ずテストスイートを実行してください。

---

Peer Dependencies

# Check what peer deps a package needs
npm info <package> peerDependencies

# npm 7+ auto-installs peer deps (may surprise you with version conflicts)
# Opt out: npm install --legacy-peer-deps (last resort)

# Check for peer dep conflicts
npm install 2>&1 | grep "peer dep"
npm ls 2>&1 | grep "WARN" | grep "peer"

ルール：Peer dependency の警告が表示されたら、無視しないでください。微妙な実行時エラーを引き起こす可能性のあるバージョンの不一致を示しています。共通の peer dependency を互換性のあるバージョンに固定して解決してください。

---

参考資料

• references/update-strategies.md — Renovate と Dependabot の設定の詳細、グループ化戦略、自動マージポリシー、更新 PR を安全にテストする方法については、こちらを参照してください
• references/security-auditing.md — npm audit / Snyk / Socket.dev の詳細、SBOM の生成、ライセンススキャンツール、CI 統合のパターンについては、こちらを参照してください