Secret Management Architecture

概要

このスキルは、機密情報を安全に管理するための構造的パターンと実装戦略を提供します。 プロジェクトの規模、環境の複雑さ、セキュリティ要件に応じた適切な管理方式の選択と、 階層的な Secret 管理設計を支援します。

Secret 管理方式の選択基準

1. 環境変数ファイル方式

適用条件:

• 小規模プロジェクト（開発者 5 名以下）
• 環境数が少ない（dev/prod 程度）
• ローカル開発が中心
• Secret 数が少ない（20 個未満）

メリット:

• シンプルで理解しやすい
• セットアップが迅速
• 追加コストなし
• ローカル開発との親和性が高い

デメリット:

• スケーラビリティに欠ける
• 手動 Rotation 必要
• 監査証跡が弱い
• チーム間共有が困難

実装パターン:

project/
├── .env.example          # テンプレート（Gitコミット可）
├── .env.development      # ローカル開発用（Gitignore）
├── .env.staging          # ステージング用（Gitignore）
└── .env.production       # 本番用（Gitignore、別管理推奨）

セキュリティ要件:

• 必ず.gitignore に追加
• .env.example には機密情報を含めない
• 本番 Secret は別管理（クラウド Secrets Manager 等）推奨

2. クラウド Secrets Manager 方式

適用条件:

• 中規模以上プロジェクト（開発者 5 名以上）
• マルチ環境（dev/staging/prod/DR 等）
• クラウドネイティブアーキテクチャ
• 高いセキュリティ要件

対応サービス:

• AWS Secrets Manager
• Google Cloud Secret Manager
• Azure Key Vault
• Railway Secrets
• GitHub Secrets（CI/CD 専用）

メリット:

• 自動 Rotation 対応
• 完全な監査証跡
• アクセス制御の細分化
• 暗号化の自動管理
• 高可用性

デメリット:

• コスト発生
• セットアップ複雑
• サービス依存
• ネットワーク遅延

実装パターン:

// Secret取得の統一インターフェース
interface ISecretManager {
  getSecret(name: string, env: Environment): Promise<string>;
  rotateSecret(name: string): Promise<void>;
}

// Railway Secrets実装例
class RailwaySecretManager implements ISecretManager {
  async getSecret(name: string, env: Environment): Promise<string> {
    // Railway環境変数から取得（自動注入）
    return process.env[name] || "";
  }
}

3. HashiCorp Vault 方式

適用条件:

• エンタープライズ環境
• マルチクラウド戦略
• 動的 Secret 生成が必要
• 高度な監査要件

メリット:

• 動的 Secret 生成
• 最も強力なアクセス制御
• 完全な監査ログ
• マルチクラウド対応
• Secret versioning

デメリット:

• 高い運用コスト
• 学習曲線が急
• インフラ複雑化
• 専門知識が必要

実装パターン: 詳細は resources/vault-integration-patterns.md を参照

4. Kubernetes Secrets 方式

適用条件:

• Kubernetes 環境
• コンテナ化アプリケーション
• マイクロサービスアーキテクチャ

メリット:

• Kubernetes ネイティブ統合
• Pod レベルでの注入
• ネームスペース分離

デメリット:

• デフォルトでは暗号化なし（etcd 暗号化が必要）
• Rotation 機能が弱い
• Kubernetes 依存

実装パターン: 詳細は resources/kubernetes-secrets-patterns.md を参照

階層的 Secret 管理設計

3 層階層モデル

Layer 1: グローバル共通 Secret

特性:

• プロジェクト全体で共通
• すべての環境で同じ値
• 変更頻度: 低い

例:

• サードパーティ API 基本設定
• ログ集約サービスエンドポイント
• 共通暗号化設定

管理方式: 中央集約、厳格なアクセス制御

Layer 2: 環境固有 Secret

特性:

• 環境毎に異なる値（dev/staging/prod）
• 環境内で共通
• 変更頻度: 中程度

例:

• DATABASE_URL（環境毎に異なる DB）
• API_ENDPOINT（環境毎のエンドポイント）
• REDIS_URL（環境毎の Redis）

管理方式: 環境グループ機能、環境変数注入

Layer 3: サービス専用 Secret

特性:

• 特定サービスのみ使用
• 他サービスからアクセス不可
• 変更頻度: 高い

例:

• DISCORD_WEBHOOK_URL（Discord 連携サービス専用）
• STRIPE_SECRET_KEY（決済サービス専用）
• SENDGRID_API_KEY（メールサービス専用）

管理方式: サービススコープ制限、最小権限アクセス

Secret 分類フレームワーク

重要度分類

Critical（最重要）:

• 本番データベース認証情報
• 本番 API キー（課金対象）
• 暗号化マスターキー
• OAuth Client Secret（本番）

High（重要）:

• ステージング環境認証情報
• サードパーティ API キー（無料枠）
• セッション暗号化キー

Medium（中程度）:

• 開発環境認証情報
• 内部 API 認証トークン
• ログ集約サービスキー

Low（低）:

• 非機密設定値
• 公開情報への参照
• デフォルト設定

スコープ分類

Global（グローバル）:

• すべてのサービスで使用
• 環境横断で共通
• 例: LOG_LEVEL、APP_NAME

Environment（環境）:

• 環境毎に異なる
• 環境内で共通
• 例: DATABASE_URL、API_BASE_URL

Service（サービス）:

• 特定サービスのみ
• 他サービスアクセス不可
• 例: DISCORD_WEBHOOK_URL、STRIPE_KEY

Rotation 頻度分類

頻繁（30 日毎）:

• 外部 API キー（高リスク）
• データベースパスワード（本番）
• OAuth Secret

定期（90 日毎）:

• 暗号化キー
• セッション Secret
• 内部 API 認証

不定期（必要時）:

• 開発環境 Secret
• 設定値
• 侵害検知時の緊急 Rotation

アクセス制御マトリクス設計

ロール定義

人間ロール:

• Developer: 開発環境 Secret のみアクセス
• DevOps Engineer: すべての環境にアクセス（承認制）
• Security Admin: すべての Secret へのフルアクセス

システムロール:

• CI/CD Pipeline: 必要最小限の Secret（GitHub Secrets 経由）
• Application Service: 実行時必要な Secret のみ
• Monitoring Service: ログ・メトリクス用 Secret のみ

アクセス制御マトリクス例

Secret 名	重要度	Developer	DevOps	Security Admin	CI/CD	App Service
DB_PASSWORD_PROD	Critical	❌	🔐（承認）	✅	❌	✅
DB_PASSWORD_DEV	Medium	✅	✅	✅	❌	✅
API_KEY_STRIPE	Critical	❌	🔐（承認）	✅	❌	✅
DISCORD_WEBHOOK	High	✅	✅	✅	✅	✅
LOG_LEVEL	Low	✅	✅	✅	✅	✅

🔐 = 承認が必要

設計時の判断基準チェックリスト

Secret 管理方式選択

• プロジェクト規模（開発者数、環境数）を評価したか？
• Secret 数と複雑度を確認したか？
• セキュリティ要件（コンプライアンス含む）を確認したか？
• 予算とリソース制約を考慮したか？
• 既存インフラとの統合性を評価したか？

階層設計

• Secret が 3 層（グローバル/環境/サービス）に分類されているか？
• 各層のアクセス権限が明確に定義されているか？
• クロススコープアクセスが最小化されているか？
• 環境間の Secret 共有が防止されているか？

アクセス制御

• すべてのロール（人間・システム）が定義されているか？
• 最小権限の原則が適用されているか？
• アクセス制御マトリクスが完全か？
• 承認プロセスが高リスク Secret に設定されているか？

Rotation 戦略

• 各 Secret の重要度に応じた Rotation 頻度が定義されているか？
• Rotation プロセスがダウンタイムを発生させないか？
• ロールバック手順が明確か？
• 自動 Rotation 可能な Secret が特定されているか？

関連スキル

• .claude/skills/zero-trust-security/SKILL.md - アクセス制御設計の詳細
• .claude/skills/encryption-key-lifecycle/SKILL.md - 鍵ライフサイクル管理
• .claude/skills/environment-isolation/SKILL.md - 環境分離戦略
• .claude/skills/railway-secrets-management/SKILL.md - Railway 統合
• .claude/skills/github-actions-security/SKILL.md - GitHub Actions 統合

リソースファイル

詳細な実装パターンは以下を参照:

• resources/vault-integration-patterns.md - HashiCorp Vault 統合
• resources/kubernetes-secrets-patterns.md - Kubernetes Secrets 実装
• resources/secret-classification-framework.md - Secret 分類詳細
• resources/access-control-matrix-template.md - アクセス制御設計テンプレート

テンプレート

• templates/env-example-template.md - .env.example ファイルテンプレート
• templates/secret-inventory-template.md - Secret 棚卸しテンプレート
• templates/rotation-plan-template.md - Rotation 計画テンプレート