env-secrets-manager

環境変数とシークレットの管理

ティア： POWERFUL カテゴリ： エンジニアリング ドメイン： セキュリティ／DevOps／構成管理

---

概要

ローカル開発から本番環境まで、環境変数の適切な管理とシークレットの安全性を保ちます。このスキルでは、実用的な監査、設定のずれの把握、ローテーションの準備に重点を置きます。

主な機能

• .env と .env.example のライフサイクルに関するガイダンス
• リポジトリの作業ツリーにおけるシークレット漏えいの検出
• 認証情報と思われる値の深刻度別の検出結果
• ローテーションと封じ込めに関する運用上の指針
• CI チェックにそのまま利用できる出力

---

使用する場面

• 環境変数や構成ファイルを変更したコミットをプッシュする前
• セキュリティ監査やインシデントのトリアージ時
• 安全な環境変数の運用方法が必要なコントリビューターのオンボーディング時
• 明らかなシークレットがハードコードされていないことを検証するとき

---

クイックスタート

# Scan a repository for likely secret leaks
python3 scripts/env_auditor.py /path/to/repo

# JSON output for CI pipelines
python3 scripts/env_auditor.py /path/to/repo --json

---

推奨ワークフロー

1. リポジトリのルートで scripts/env_auditor.py を実行します。
2. まず critical と high の検出結果に対処します。
3. 実際の認証情報をローテーションし、漏えいした値を削除します。
4. 必要に応じて .env.example と .gitignore を更新します。
5. プリコミットや CI におけるシークレットスキャンのゲートを追加または強化します。

---

参考ドキュメント

• references/validation-detection-rotation.md
• references/secret-patterns.md

---

よくある落とし穴

• .env.example に実際の値をコミットする
• 1 つのシステムでローテーションしても、下流の利用者を見落とす
• デバッグ中やインシデント対応中にシークレットをログへ記録する
• 検証せずに、漏えいが疑われる情報を緊急度の低い問題として扱う

ベストプラクティス

1. 本番環境の信頼できる唯一の情報源として、シークレットマネージャーを使用します。
2. 開発環境のファイルはローカルに保管し、Git の追跡対象から除外します。
3. マージ前に CI で検出を必須にします。
4. 認証情報のローテーション後、直ちにアプリケーションの経路を再テストします。

---

クラウドシークレットストアとの統合

本番アプリケーションでは、.env ファイルやコンテナイメージに埋め込まれた環境変数からシークレットを読み込まないでください。代わりに、専用のシークレットストアを使用します。

プロバイダーの比較

プロバイダー	最適な用途	主な機能
HashiCorp Vault	マルチクラウド／ハイブリッド	動的シークレット、ポリシーエンジン、プラグ可能なバックエンド
AWS Secrets Manager	AWS ネイティブのワークロード	Lambda／ECS／EKS とのネイティブ統合、RDS の自動ローテーション
Azure Key Vault	Azure ネイティブのワークロード	マネージド HSM、Azure AD RBAC、証明書管理
GCP Secret Manager	GCP ネイティブのワークロード	IAM ベースのアクセス、自動レプリケーション、バージョン管理

選定の指針

• 単一のクラウドプロバイダー — クラウドネイティブのシークレットマネージャーを使用します。IAM と緊密に統合され、運用負荷を軽減し、セルフホストよりもコストを抑えられます。
• マルチクラウドまたはハイブリッド — HashiCorp Vault を使用します。環境間で統一された API を提供し、自動的に有効期限が切れる動的なシークレット（データベース認証情報、クラウド IAM キーなど）の生成をサポートします。
• Kubernetes を多用する環境 — External Secrets Operator と上記のいずれかのバックエンドを組み合わせると、ハードコードせずにシークレットを K8s の Secret オブジェクトへ同期できます。

アプリケーションのアクセスパターン

1. SDK／API による取得 — アプリケーションがプロバイダーの SDK を介して、起動時または必要に応じてシークレットを取得します。
2. サイドカーによる注入 — サイドカーコンテナ（例：Vault Agent）が、共有ボリュームにシークレットを書き込むか、環境変数として注入します。
3. 初期化コンテナ — Kubernetes の初期化コンテナが、メインコンテナの起動前にシークレットを取得します。
4. CSI ドライバー — Secrets Store CSI Driver を介して、シークレットをファイルシステムのボリュームとしてマウントします。

関連項目： 本番環境の Vault インフラストラクチャのパターン、高可用性デプロイ、災害復旧手順については、engineering/secrets-vault-manager を参照してください。

---

シークレットのローテーションワークフロー

古いシークレットはリスクになります。ローテーションにより、認証情報が漏えいした場合でも、その有効期間を限定できます。

フェーズ 1：検知

• シークレットストアのメタデータで、シークレットの作成日と有効期限を追跡します。
• 有効期限の30日前、14日前、7日前にアラートを設定します。
• scripts/env_auditor.py を使用して、ローテーション日が記録されていないシークレットを検出します。

フェーズ 2：ローテーション

1. 生成 — 新しい認証情報（API キー、データベースのパスワード、証明書）を生成します。
2. デプロイ — 新しい認証情報をすべての利用先（アプリ、サービス、パイプライン）に並行してデプロイします。
3. 検証 — 各利用先が新しい認証情報を使って認証できることを確認します。
4. 失効 — すべての利用先が正常であることを確認してから、古い認証情報を失効させます。
5. 更新 — メタデータを新しいローテーション日時と次回のローテーション日に更新します。

フェーズ 3：自動化

• AWS Secrets Manager — RDS、Redshift、DocumentDB 向けの組み込みの Lambda ベースのローテーションを使用します。
• HashiCorp Vault — TTL を設定した動的シークレットを構成します。認証情報は要求に応じて生成され、自動的に期限切れになります。
• Azure Key Vault — Event Grid 通知を使用してローテーション関数を起動します。
• GCP Secret Manager — ローテーションロジック用の Cloud Functions に連携する Pub/Sub 通知を使用します。

緊急ローテーションのチェックリスト

シークレットの漏えいが確認された場合：

1. 直ちに失効 — プロバイダー側で侵害された認証情報を失効させます。
2. 代替の認証情報を生成し、すべての利用先にデプロイします。
3. 漏えい期間中に不正利用がなかったか、アクセスログを監査します。
4. 漏えいした値が含まれていないか、Git の履歴、CI ログ、アーティファクトレジストリをスキャンします。
5. 影響範囲、タイムライン、修復手順を記録したインシデントレポートを作成します。
6. 再発を防止するため、検知制御を見直して強化します。

---

CI/CD シークレットの注入

CI/CD パイプライン内のシークレットは、ログ、アーティファクト、プルリクエストのコンテキストへの漏えいを防ぐため、慎重に取り扱う必要があります。

GitHub Actions

• ${{ secrets.SECRET_NAME }} を介して、リポジトリシークレットまたは環境シークレットを使用します。
• 有効期間の長いアクセスキーより、OIDC フェデレーション（role-to-assume を指定した aws-actions/configure-aws-credentials）を優先します。
• 必須レビュアーを設定した環境シークレットにより、本番環境へのデプロイに承認ゲートを設けられます。
• GitHub はログ内のシークレットを自動的にマスキングしますが、シークレットの値に対して echo や toJSON() を使用しないでください。

GitLab CI

• masked と protected のフラグを有効にして、シークレットをCI/CD 変数として保存します。
• GitLab に値を保存せずにシークレットを動的に注入するには、HashiCorp Vault インテグレーション（secrets:vault）を使用します。
• 最小権限を適用するため、変数の適用範囲を特定の環境（production、staging）に限定します。

共通パターン

• デバッグ目的であっても、パイプラインの出力にシークレットの値を絶対にエコーまたは出力しないでください。
• 可能な限り、静的な認証情報の代わりに有効期間の短いトークン（OIDC、STS AssumeRole）を使用します。
• プルリクエストへのアクセスを制限します。フォークや信頼されていないブランチから起動されたパイプラインにシークレットを公開しないでください。
• パイプラインの認証情報も攻撃対象となるため、CI シークレットはアプリケーションのシークレットと同じスケジュールでローテーションします。
• マスキングをすり抜けたシークレットの偶発的な漏えいがないか、パイプラインのログを定期的に監査します。

---

コミット前のシークレット検出

シークレットがバージョン管理に入る前に検出することが、最も費用対効果の高い防御策です。この分野では、主要なツールが2つあります。

gitleaks

# .gitleaks.toml — minimal configuration
[extend]
useDefault = true

[[rules]]
id = "custom-internal-token"
description = "Internal service token pattern"
regex = '''INTERNAL_TOKEN_[A-Za-z0-9]{32}'''
secretGroup = 0

• インストール：brew install gitleaks を実行するか、GitHub のリリースからダウンロードします。
• コミット前フック：gitleaks git --pre-commit --staged
• ベースラインスキャン：gitleaks detect --source . --report-path gitleaks-report.json
• .gitleaksignore で誤検知を管理します（1行につき1つのフィンガープリント）。

detect-secrets

# Generate baseline
detect-secrets scan --all-files > .secrets.baseline

# Pre-commit hook (via pre-commit framework)
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']

• 組織固有のパターンに対応したカスタムプラグインをサポートします。
• 監査ワークフロー：detect-secrets audit .secrets.baseline を実行すると、対話形式で真陽性と誤検知を判定できます。

誤検知の管理

• .gitleaksignore または .secrets.baseline をバージョン管理に含め、チーム全体で除外設定を共有します。
• セキュリティ監査の際に誤検知リストを確認します。パターンによっては、時間の経過とともに実際の漏えいを見逃す原因になります。
• ファイルを大まかに無視するのではなく、正規表現パターンを厳密にすることを優先します。

---

監査ログ

インシデント調査やコンプライアンス対応では、誰がいつどのシークレットにアクセスしたかを把握することが重要です。

クラウドネイティブな監査証跡

プロバイダー	サービス	記録される内容
AWS	CloudTrail	すべての GetSecretValue、DescribeSecret、RotateSecret API 呼び出し
Azure	Activity Log + Diagnostic Logs	呼び出し元の ID と IP を含む、Key Vault へのアクセスイベント
GCP	Cloud Audit Logs	principal とタイムスタンプを含む、Secret Manager のデータアクセスログ
Vault	Audit Backend	リクエスト／レスポンスの全記録（file、syslog、socket の各バックエンド）

アラート戦略

• 不明な IP 範囲からのアクセスや、想定された一覧にないサービスアカウントからのアクセスに対してアラートを設定します。
• シークレットの一括読み取り（一定時間内に N 個を超えるシークレットにアクセス）に対してアラートを設定します。
• CI/CD パイプラインが実行されていない場合に、デプロイウィンドウ外のアクセスに対してアラートを設定します。
• 監査ログを SIEM（Splunk、Datadog、Elastic）に取り込み、ほかのセキュリティイベントと相関分析します。
• アクセス権の再認証の一環として、監査ログを四半期ごとに確認します。

---

相互参照

このスキルでは、環境変数の衛生管理とシークレット検出を扱います。関連分野について詳しくは、以下を参照してください。

スキル	パス	関連内容
Secrets Vault Manager	engineering/secrets-vault-manager	本番環境の Vault インフラストラクチャ、高可用性デプロイ、災害復旧
Senior SecOps	engineering/senior-secops	セキュリティ運用の視点、インシデント対応
CI/CD Pipeline Builder	engineering/ci-cd-pipeline-builder	パイプラインアーキテクチャ、シークレット注入パターン
Infrastructure as Code	engineering/infrastructure-as-code	Terraform/Pulumi のシークレットバックエンド設定
Container Orchestration	engineering/container-orchestration	Kubernetes のシークレットマウント、シールドされたシークレット