managing-secrets

シークレットの管理

アプリケーションやインフラストラクチャ向けのシークレット（API キー、データベース認証情報、TLS 証明書）を安全に保存、ローテーション、配布します。

このスキルを使用するタイミング

次の場合に使用します。

• API キー、データベース認証情報、暗号化キーを保存する
• シークレットのローテーション（手動または自動）を実装する
• 外部ストアから Kubernetes へシークレットを同期する
• 動的シークレット（データベース、クラウドプロバイダー）を設定する
• コードに漏えいしたシークレットがないかスキャンする
• ゼロ知識パターンを実装する
• コンプライアンス要件（SOC 2、ISO 27001、PCI DSS）を満たす

すばやく判断するためのフレームワーク

フレームワーク 1：シークレットストアの選択

シナリオ	第一候補	代替案
Kubernetes + マルチクラウド	Vault + ESO	Cloud Secret Manager + ESO
Kubernetes + 単一クラウド	Cloud Secret Manager + ESO	Vault + ESO
サーバーレス（AWS Lambda）	AWS Secrets Manager	AWS Parameter Store
マルチクラウドのエンタープライズ	HashiCorp Vault	Doppler（SaaS）
小規模チーム（アプリ 10 個未満）	Doppler、Infisical	1Password Secrets Automation
GitOps 中心	SOPS（git で暗号化）	Sealed Secrets（K8s 専用）

判断ツリー：

• Kubernetes を使用していますか？ → 選択したバックエンドと External Secrets Operator（ESO）を使用します
• 単一クラウドですか？ → クラウドネイティブ（AWS/GCP/Azure）を使用します
• マルチクラウド／オンプレミスですか？ → HashiCorp Vault を使用します
• GitOps を使用していますか？ → SOPS または Sealed Secrets を使用します

フレームワーク 2：静的シークレットと動的シークレット

シークレットの種類	動的にしますか？	TTL	ソリューション
データベース認証情報	はい	1 時間	Vault DB エンジン
クラウド IAM（AWS/GCP）	はい	15 分	Vault クラウドエンジン
SSH/RDP アクセス	はい	5 分	Vault SSH エンジン
TLS 証明書	はい	24 時間	Vault PKI / cert-manager
サードパーティの API キー	いいえ	四半期ごと	Vault KV v2（手動ローテーション）

フレームワーク 3：Kubernetes へのシークレット配布

方法	ユースケース	ローテーション	再起動が必要
External Secrets Operator	静的シークレット、定期同期	ポーリング（1 時間）	はい
Secrets Store CSI Driver	ファイルベース、ローテーションの監視	inotify	いいえ
Vault Secrets Operator	Vault 固有、動的	自動更新	任意

HashiCorp Vault の基礎

主なコンポーネント

• シークレットエンジン：KV v2（静的）、Database（動的）、AWS、PKI、SSH
• 認証方式：Kubernetes、JWT/OIDC、AppRole、LDAP
• ポリシー：HCL ベースのアクセス制御（最小権限）
• リース：シークレットの TTL、自動更新、自動失効

静的シークレット（KV v2）

# Create secret
vault kv put secret/myapp/config api_key=sk_live_EXAMPLE

# Read secret
vault kv get secret/myapp/config

# List versions
vault kv metadata get secret/myapp/config

動的データベース認証情報

# Configure PostgreSQL
vault write database/config/postgres \
  plugin_name=postgresql-database-plugin \
  connection_url="postgresql://{{username}}:{{password}}@postgres:5432/mydb"

# Create role
vault write database/roles/app-role \
  db_name=postgres \
  creation_statements="CREATE ROLE \"{{name}}\"..." \
  default_ttl="1h"

# Generate credentials
vault read database/creds/app-role

Vault のアーキテクチャの詳細については、references/vault-architecture.md を参照してください。

Kubernetes との統合

External Secrets Operator（ESO）

30 以上のプロバイダーから Kubernetes Secrets にシークレットを同期します。

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: "https://vault.example.com"
      auth:
        kubernetes:
          role: "app-role"

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
  target:
    name: db-credentials
  data:
  - secretKey: password
    remoteRef:
      key: secret/data/database/config

Vault Secrets Operator（VSO）

リースを自動更新する、Kubernetes ネイティブの Vault 統合です。

apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  name: postgres-creds
spec:
  vaultAuthRef: vault-auth
  mount: database
  path: creds/app-role
  renewalPercent: 67  # Renew at 67% of TTL
  destination:
    name: dynamic-db-creds

ESO、CSI、VSO の比較については、references/kubernetes-integration.md を参照してください。

シークレットのローテーションパターン

パターン 1：バージョン管理された静的シークレット（ブルー／グリーン）

1. Vault で新しいシークレットバージョンを作成します
2. ステージング環境を更新します
3. エラーを監視します（24～48 時間）
4. 本番環境へ段階的にロールアウトします（10% → 50% → 100%）
5. 古いシークレットを失効させます（7 日後）

パターン 2：動的データベース認証情報

Vault は TTL の短い認証情報を自動生成します。

• アプリが Vault から認証情報を取得します
• Vault がリースを自動更新します（TTL の 67% 経過時）
• 有効期限が切れると、Vault はアクセスを失効させます
• 更新に失敗した場合、アプリは新しい認証情報を要求します

パターン 3：TLS 証明書のローテーション

cert-manager + Vault PKI を使用します。

• cert-manager が Vault に証明書を要求します
• 有効期限前に自動更新します（デフォルト：有効期間の 67% 経過時）
• 更新時に Kubernetes Secret を更新します
• 任意でポッドを再起動します（Reloader 経由）

ローテーションワークフローの詳細については、references/rotation-patterns.md を参照してください。

複数言語との統合

Python（hvac）

import hvac

client = hvac.Client(url='https://vault.example.com')
client.auth.kubernetes(role='app-role', jwt=jwt)

# Fetch dynamic credentials
response = client.secrets.database.generate_credentials(name='postgres-role')
username = response['data']['username']
password = response['data']['password']

Go（Vault API）

import vault "github.com/hashicorp/vault/api"

client, _ := vault.NewClient(vault.DefaultConfig())
k8sAuth, _ := auth.NewKubernetesAuth("app-role")
client.Auth().Login(context.Background(), k8sAuth)

secret, _ := client.Logical().Read("database/creds/postgres-role")

TypeScript (node-vault)

import vault from 'node-vault';

const client = vault({ endpoint: 'https://vault.example.com' });
await client.kubernetesLogin({ role: 'app-role', jwt });

const response = await client.read('database/creds/postgres-role');

完全なサンプルについては、examples/dynamic-db-credentials/ を参照してください。

シークレットスキャン

コミット前フック（Gitleaks）

# Install Gitleaks
brew install gitleaks

# Run on staged files
gitleaks protect --staged --verbose

コミット前フックにより、シークレットがコミットされるのを防ぎます。 セットアップについては、examples/secret-scanning/pre-commit を参照してください。

CI/CD との統合

# GitHub Actions
- name: Run Gitleaks
  uses: gitleaks/gitleaks-action@v2

修復ワークフロー

シークレットが漏えいした場合：

1. 直ちにローテーションする（1 時間以内）
2. プロバイダーで無効化する
3. Git の履歴から削除する（BFG Repo-Cleaner）
4. 強制プッシュする（チームに通知）
5. アクセスを監査する（漏えい期間中に誰がアクセスできたか）
6. インシデントを記録する

詳細な修復手順については、references/secret-scanning.md を参照してください。

ゼロ知識パターン

クライアント側の暗号化（E2EE）

ユーザーのパスワード → PBKDF2 → 暗号化キー → シークレットを暗号化 → サーバーに送信

サーバーには暗号化されたデータのみが保存されます（復号できません）。

シャミアの秘密分散法

シークレットを N 個のシェアに分割し、再構築には M 個を必要とします（例：5 個中 3 個）。

# Initialize Vault with Shamir shares
vault operator init -key-shares=5 -key-threshold=3

# Unseal requires 3 of 5 key shares
vault operator unseal <KEY_1>
vault operator unseal <KEY_2>
vault operator unseal <KEY_3>

実装については、references/zero-knowledge.md を参照してください。

ライブラリの推奨事項（2025 年）

シークレットストア

ライブラリ	用途	信頼スコア
HashiCorp Vault	エンタープライズ、マルチクラウド	高（73.3/100）
External Secrets Operator	Kubernetes との統合	高（85.0/100）
AWS Secrets Manager	AWS ワークロード	高
GCP Secret Manager	GCP ワークロード	高
Azure Key Vault	Azure ワークロード	高

シークレットスキャン

ライブラリ	用途	信頼スコア
Gitleaks	コミット前、CI/CD	高（89.9/100）
TruffleHog	Git 履歴のスキャン	中

クライアントライブラリ

言語	ライブラリ	バージョン
Python	hvac	2.2.0+
Go	vault/api	最新
TypeScript	node-vault	0.10.2+
Rust	vaultrs	0.7+

よくあるワークフロー

ワークフロー 1：Kubernetes 上の Vault + ESO

1. Vault をインストールする（Helm chart）
2. Vault を初期化してアンシールする
3. Kubernetes 認証を有効にする
4. External Secrets Operator をインストールする
5. SecretStore を作成する（Vault 接続）
6. ExternalSecret を作成する（シークレットのマッピング）

手順ごとのガイドについては、examples/vault-eso-setup/ を参照してください。

ワークフロー 2：動的なデータベース認証情報

1. データベースシークレットエンジンを有効にする
2. データベース接続を設定する
3. TTL を指定してロールを作成する
4. アプリが認証情報を取得する
5. Vault がリースを自動更新する

実装については、examples/dynamic-db-credentials/ を参照してください。

ワークフロー 3：シークレットスキャンの修復

1. Gitleaks がシークレットを検出する
2. コミットをブロックする（コミット前フック）
3. 開発者がシークレットを削除する
4. 開発者が Vault に保存する
5. 開発者が Vault のパスを参照する

セットアップについては、examples/secret-scanning/ を参照してください。

関連スキルとの統合

• auth-security：OAuth クライアントシークレット、JWT 署名キー
• databases-*：動的なデータベース認証情報
• deploying-applications：コンテナレジストリの認証情報
• observability：Grafana／Datadog API キー
• infrastructure-as-code：クラウドプロバイダーの認証情報

セキュリティのベストプラクティス

1. シークレットを Git にコミットしない（Gitleaks のコミット前フックを使用する）
2. 可能な場合は動的シークレットを使用する
3. シークレットを定期的にローテーションする（静的シークレットは四半期ごと、動的シークレットは 1 時間ごと）
4. 最小権限を適用する（Vault ポリシー、RBAC）
5. 監査ログを有効にする
6. 保存時に暗号化する（Vault ストレージ、etcd の暗号化）
7. 短い TTL を使用する（動的シークレットは 24 時間未満）
8. アクセス失敗の試行を監視する

よくある落とし穴

環境変数内のシークレット

環境変数はプロセス一覧から確認できます。 解決策： ファイルベースのシークレット（Kubernetes ボリューム、CSI ドライバー）を使用します。

マニフェスト内にハードコードされたシークレット

Base64 は暗号化ではありません。 解決策： External Secrets Operator を使用します。

シークレットのローテーションなし

古い認証情報は侵害のリスクを高めます。 解決策： 動的シークレットを使用するか、ローテーションを自動化します。

本番環境でのルートトークン

権限に制限がありません。 解決策： 最小権限のポリシーを持つ認証方式を使用します。

詳細については、以下を参照してください

• references/vault-architecture.md - Vault の内部構造、HA のセットアップ、ポリシー
• references/kubernetes-integration.md - ESO、CSI ドライバー、VSO の比較
• references/rotation-patterns.md - ローテーションのワークフローの詳細
• references/secret-scanning.md - Gitleaks、修正手順
• references/zero-knowledge.md - E2EE、Shamir の秘密分散法
• references/cloud-providers.md - AWS、GCP、Azure のシークレットマネージャー
• examples/vault-eso-setup/ - Kubernetes の完全なセットアップ
• examples/dynamic-db-credentials/ - 複数言語のサンプル
• examples/secret-scanning/ - コミット前フック、CI/CD
• scripts/setup_vault.sh - Vault の自動インストール