secure-dependency-health-check

セキュアな依存関係の健全性チェック

セキュリティの健全性、脆弱性の履歴、人気度、コミュニティ、メンテナンス状況を評価することで、開発者や AI エージェントがオープンソースパッケージを選ぶ際に、十分な情報に基づいて判断できるよう支援します。

基本原則：依存関係を慎重に選び、サプライチェーンリスクを最小限に抑えます。

---

クイックスタート

パッケージの推奨を求められた場合：

1. 機能要件を特定します
2. 候補となるパッケージを調査します
3. 各候補で snyk_package_health_check を実行します
4. 最も健全で安全な選択肢を比較して推奨します

---

フェーズ 1：要件の把握

目標：パッケージを推奨する前に、ユーザーのニーズを明確にします。

ステップ 1.1：候補の特定

ユーザーが候補を提示した場合：

• 各パッケージ名とバージョン（指定されている場合）を記録します
• パッケージのエコシステムを特定します

ユーザーが提案を求めている場合：

• 機能要件を満たすパッケージを検索します
• 人気度や関連性に基づいて、上位 2～4 個の候補を選びます

---

フェーズ 2：セキュリティと健全性の分析

目標：各候補パッケージのセキュリティ態勢と全体的な健全性を評価します。

ステップ 2.1：各候補のパッケージ健全性チェックを実行

各候補パッケージについて、パッケージ名、バージョン、エコシステム（npm、pypi、maven、nuget、または golang）を指定して snyk_package_health_check を実行します。主な返却フィールド：

• overall_rating：「Healthy」または「Review recommended」 — 主な評価指標として使用します
• security：深刻度（critical/high/medium/low）別の脆弱性数とセキュリティ評価
• maintenance：ライフサイクルの状態、最新リリース日、is_archived フラグ、メンテナンス評価（「Healthy」、「Sustainable」、「Inactive」）
• popularity：ダウンロード数、依存するパッケージ／リポジトリの数、人気度評価
• community：スター数、コミュニティ関連ファイルの有無、評価（「Active」または「Sustainable」）
• latest_version：公開済みの最新バージョン
• recommendation：総合評価を人が読みやすい形でまとめた内容

ステップ 2.2：ツールの結果を確認

比較のため、ツールのレスポンスから以下を提示します：

• 総合評価（「Healthy」か「Review recommended」か）
• セキュリティ評価と深刻度別の脆弱性の内訳
• メンテナンス評価とライフサイクルの状態（is_archived、latest_release_published_at を確認）
• 人気度とコミュニティの評価

ステップ 2.3：除外条件

総合評価にかかわらず、次の場合は直ちにパッケージを除外します：

• critical または high の脆弱性など、セキュリティ上の問題が見つかった場合
• メンテナンス評価が「Inactive」である、またはパッケージがアーカイブされている（is_archived: true）場合
• リリースが 3 年以上ない場合（latest_release_published_at を確認）
• 悪意のあるパッケージとして知られている場合（サプライチェーン攻撃）
• タイポスクワッティングの兆候がある場合（人気パッケージと名前が似ている）

---

フェーズ 3：推奨事項の作成

目標：明確で実行可能な比較を提示します。

ステップ 3.1：比較表

## Package Comparison: [Use Case]

| Criteria | Package A | Package B | Package C |
|----------|-----------|-----------|-----------|
| **Overall Rating** | Healthy | Review recommended | Healthy |
| **Security Rating** | Security issues found | Security issues found | No known security issues |
| **Critical CVEs** | 0 | 1 | 0 |
| **High CVEs** | 1 | 2 | 0 |
| **Maintenance** | Healthy | Inactive | Healthy |
| **Last Release** | 2 weeks ago | 8 months ago | 1 month ago |
| **Downloads** | 500K | 2M | 300K |
| **Popularity** | Influential project | Influential project | Influential project |

### Recommendation: **Package C**

**Reasons**:
1. "Healthy" overall rating with no known security issues
2. Healthy maintenance rating - actively maintained with recent release
3. Fewest vulnerabilities across all severity levels

**Trade-offs**:
- Fewer downloads than Package B (less battle-tested)
- Consider if specific features of Package A/B are required

**Recommended version**: Use the `latest_version` from the tool response to pin an exact version.

ステップ 3.2：代替シナリオ

セキュリティ基準を満たすパッケージがない場合：

## Warning: No Secure Option Available

All evaluated packages have significant security concerns:
- Package A: 2 Critical CVEs (actively exploited)
- Package B: Abandoned - no updates in 3 years
- Package C: Multiple high-severity vulnerabilities with no fix available

### Alternatives:
1. **Implement in-house**: For simple functionality
2. **Fork and fix**: If one package is close but has fixable issues
3. **Wait**: If updates are expected soon
4. **Accept risk**: With documented justification and monitoring

---

フェーズ 4：統合ガイダンス

目標：推奨パッケージをユーザーが安全に追加できるよう支援します。

ステップ 4.1：インストール後のスキャン

インストール後に snyk_sca_scan を実行し、依存関係ツリー全体に想定外の脆弱性が持ち込まれていないことを確認するよう推奨します。

ステップ 4.2：モニタリングの推奨

ロックファイルをコミットし、脆弱性通知を有効にして、セキュリティ更新を定期的に確認するよう勧めます。

---

エラー処理

パッケージが見つからない

• パッケージ名とエコシステムを確認します
• 入力ミスがないか確認します
• 別名を検索します

スキャンの失敗またはデータ不足

• 一部のパッケージでは、ツールが「Snyk doesn't have sufficient information about this package」を返すことがあります
• 1 回再試行し、それでもデータがない場合は手動調査に切り替えます
• ツールでこのパッケージを評価できなかった旨の免責事項を添えて、部分的な結果を報告します

基準を満たす候補がない

• 各候補が不適格となった理由を報告します
• 代替案（社内での開発、フォーク、様子見）を提案します
• それでもユーザーが進める場合のリスクを記録します

---

制約

1. 既知の脆弱性を持つパッケージは決して推奨しないでください
2. 推奨する際は必ず正確なバージョンを指定してください
3. 完全な分析ができない場合は、制限事項を明示してください
4. ユーザーから新たな制約が提示された場合は、推奨内容を更新してください