secrets-management

OCI Vault とシークレット管理 — 専門知識

🏗️ OCI Landing Zone の Terraform モジュールを使用する

一から作り直す必要はありません。 Vault のセットアップには oracle-terraform-modules/landing-zone を使用してください。

Landing Zone が解決する課題：

• ❌ 悪いプラクティス #1：汎用コンパートメント（Landing Zone は Vault 用の Security コンパートメントを作成します）
• ❌ 悪いプラクティス #7：セキュリティサービスがない（Landing Zone は Cloud Guard によるモニタリングを統合します）
• ❌ 悪いプラクティス #10：監査ログがない（Landing Zone は Vault の監査ログを有効にします）

このスキルが提供するもの：Landing Zone 内にデプロイされた Vault の運用、シークレット管理パターン、トラブルシューティング。

---

⚠️ OCI CLI/API に関する知識の不足

OCI CLI コマンドや OCI API の構造は把握していません。

トレーニングデータに含まれる以下の知識は限られており、古くなっています。

• OCI CLI の構文とパラメーター（月次更新）
• OCI API のエンドポイントとリクエスト／レスポンス形式
• Vault サービスの CLI 操作（oci vault secret、oci kms）
• シークレットのエンコーディング形式と取得パターン
• Vault/KMS の最新機能とリージョン間レプリケーション

OCI の操作が必要な場合：

1. このスキルのリファレンスに記載されている正確な CLI コマンドを使用してください
2. OCI Vault の CLI 構文を推測しないでください
3. AWS Secrets Manager のパターンが OCI でも使えると想定しないでください
4. 詳細な Vault API ドキュメントについては、リファレンスファイルを読み込んでください

把握していること：

• シークレット管理の一般原則
• 暗号化とキー管理の概念
• シークレットのローテーションパターン

このスキルは、最新の OCI 固有の Vault パターンと注意点を提供し、この知識の不足を補います。

---

あなたは OCI Vault のエキスパートです。このスキルは、Claude に不足している知識、すなわちアンチパターン、IAM 権限に関する注意点、コストの最適化、セキュリティ上の脆弱性、OCI 固有の運用知識を提供します。

絶対にしないこと

❌ シークレットの内容を絶対にログに記録しないでください（デバッグ／エラーメッセージ内でも同様です）

# WRONG - secret ends up in log aggregation, retained for years
logger.debug(f"Retrieved secret: {secret_value}")
logger.error(f"Failed to parse secret: {secret_value}")

# RIGHT - log metadata only
logger.debug(f"Retrieved secret OCID: {secret_ocid[:20]}...")
logger.error(f"Failed to parse secret (type: {type(secret_value)})")

❌ 内容を書き込んだ後に、一時キーのファイル権限を絶対に設定しないでください

# WRONG - world-readable during write (security window)
with open('/tmp/key.pem', 'w') as f:
    f.write(private_key)
os.chmod('/tmp/key.pem', 0o600)  # Too late!

# RIGHT - secure BEFORE writing
fd = os.open('/tmp/key.pem', os.O_CREAT | os.O_WRONLY, 0o600)
with os.fdopen(fd, 'w') as f:
    f.write(private_key)

❌ 範囲が広すぎる IAM ポリシーを絶対に使用しないでください

BAD:  "Allow any-user to read secret-family in tenancy"
BAD:  "Allow group Developers to manage secret-family in tenancy"
GOOD: "Allow dynamic-group app-prod to read secret-family in compartment AppSecrets
       where target.secret.name = 'db-*'"

❌ キャッシュせずにシークレットを絶対に取得しないでください

• コスト：10,000 リクエストあたり $0.03（月あたり最初の 10,000 リクエストは無料）
• キャッシュなしの場合：1,000 リクエスト／時 × 24 × 30 = 月あたり 720k = $2.16／月
• 60 分間キャッシュする場合：1,000 リクエスト／時 → 1 日あたり 24 回 = 月あたり 720 回 = 無料
• 削減率：コストを 98% 削減

❌ 廃止予定の PLAIN コンテンツタイプを絶対に使用しないでください

• シークレットには常に BASE64 エンコーディングを使用してください
• PLAIN はレガシー形式であり、将来使用できなくなる可能性があります

❌ Vault の OCID をコードに絶対にハードコードしないでください

# WRONG - not portable, leaked in repos
VAULT_SECRET_OCID = "ocid1.vaultsecret.oc1.iad.xxxxx"

# RIGHT - configuration
VAULT_SECRET_OCID = os.environ['VAULT_SECRET_OCID']

IAM 権限に関する注意点（重要）

シークレットを取得するには、両方の権限が必要です。

"Allow dynamic-group X to read secret-family in compartment Y"
"Allow dynamic-group X to use keys in compartment Y"

両方が必要な理由：

• read secret-family → シークレットのメタデータの一覧表示と読み取りを許可します
• use keys → シークレットの内容の復号を許可します（シークレットはマスターキーで暗号化されています）

use keys がない場合：「User not authorized to perform this operation」という、わかりにくい 403 エラーが発生します

よくある間違い：use keys 権限を忘れ、「authorization failed」のデバッグに何時間も費やす

Vault の階層（混同されがち）

Vault (container)
 └─ Master Encryption Key (for encryption/decryption)
     └─ Secret (encrypted data)
         └─ Secret Versions (rotation over time)

コマンドによって使用するサービスが異なります：

• Vault の操作：oci kms management vault ...
• キーの操作：oci kms management key ... --endpoint <vault-endpoint>
• シークレットの操作：oci vault secret ...（kms ではありません！）

よくある間違い：oci vault-secret create（そのようなコマンドはありません）と oci vault secret create（正しいコマンド）を混同する

シークレット取得エラーの判断ツリー

Secret retrieval fails?
│
├─ 401 Unauthorized
│  ├─ On OCI compute? → Check dynamic group membership
│  ├─ Local dev? → Check ~/.oci/config, verify API key uploaded
│  └─ After rotation? → Cache still has old credentials (wait for TTL)
│
├─ 403 Forbidden
│  ├─ Have "read secret-family" permission? → Add if missing
│  └─ Have "use keys" permission? → THIS IS USUALLY THE ISSUE
│
├─ 404 Not Found
│  ├─ Wrong secret OCID? → Verify environment variable
│  ├─ Wrong compartment? → Secrets client must use secret's compartment
│  └─ Secret deleted? → Check vault for secret status
│
└─ 500 Internal Server Error
   └─ Vault service issue → Retry with exponential backoff (rate limit)

コストの最適化

Vault API の料金： 10,000 リクエストあたり $0.03（月あたり 10,000 リクエストは無料）

計算例：

キャッシュなし（API 呼び出しのたびに取得）：

• 1 時間あたり 1000 回の API 呼び出し
• 24 時間 × 30 日 = 1 か月あたり 720,000 件の Vault リクエスト
• (720,000 / 10,000) × $0.03 = 月額 $2.16

キャッシュ TTL が 60 分の場合：

• 1 時間あたり 1000 回の API 呼び出し → 1 時間あたり 1 件の Vault リクエスト
• 24 時間 × 30 日 = 1 か月あたり 720 件の Vault リクエスト
• 1 万件未満の無料枠内 = 月額 $0（無料）
• 節約率：98%

キャッシュ TTL の選択：

セキュリティ要件	キャッシュ TTL	理由
高（毎日ローテーション）	5-15 分	頻繁に更新しつつ、90% 以上を節約できます
標準（月ごとにローテーション）	30-60 分	セキュリティとコストのバランスを取ります
開発／テスト	キャッシュなし	開発用に常に最新の状態を保ちます

ルール：キャッシュ TTL はシークレットのローテーション間隔より短くする必要があります

シークレットのローテーション（ダウンタイムなし）

誤り（ダウンタイムが発生します）：

# Don't delete and recreate - breaks running apps
oci vault secret delete --secret-id <secret-ocid>
oci vault secret create ...  # New OCID, apps break

正しい方法（ダウンタイムなし）：

# Create new VERSION of existing secret
oci vault secret update-base64 \
  --secret-id <secret-ocid> \
  --secret-content-content "$(echo -n 'new-value' | base64)"

# Secret OCID stays same, apps automatically get new version
# Old version kept as "previous" for rollback

重要なポイント：

• シークレット OCID は変わりません（アプリは動作し続けます）
• Vault はデフォルトで最新バージョンを提供します
• ロールバック用に以前のバージョンが保持されます
• アプリケーションは次回のキャッシュ更新時に新しいバージョンを取得します（再起動は不要です）

インスタンスプリンシパル認証

本番環境のコンピュートインスタンスでは、インスタンスプリンシパルを使用してください：

# 1. Create dynamic group
oci iam dynamic-group create \
  --name "app-instances" \
  --matching-rule "instance.compartment.id = '<compartment-ocid>'"

# 2. Grant Vault access
# "Allow dynamic-group app-instances to read secret-family in compartment Secrets"
# "Allow dynamic-group app-instances to use keys in compartment Secrets"

# 3. Application code (no credentials needed)
signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
secrets_client = oci.secrets.SecretsClient(config={}, signer=signer)

メリット：

• 認証情報の管理やローテーションが不要です
• コンピュートインスタンスにシークレットを保存しません
• トークンが自動的に更新されます
• どのインスタンスが何にアクセスしたかが監査証跡に記録されます

監査ログ

Vault のアクセスログを有効にします：

# Create log group
oci logging log-group create \
  --compartment-id <ocid> \
  --display-name "vault-audit-logs"

# Enable read access logging
oci logging log create \
  --log-group-id <log-group-ocid> \
  --display-name "secret-read-audit" \
  --log-type SERVICE \
  --configuration '{
    "source": {
      "sourceType": "OCISERVICE",
      "service": "vaults",
      "resource": "<vault-ocid>",
      "category": "read"
    }
  }'

記録される内容：

• 誰が：ユーザー OCID またはインスタンスプリンシパルの ID
• 何を：アクセスされたシークレット OCID
• いつ：タイムスタンプ（UTC）
• どこから：送信元 IP アドレス
• 結果：成功（200）または失敗（403、404 など）

推奨する監視アラート：

• 5 分間に 10 回を超えるアクセス失敗（不正アクセス）
• リクエスト元のインスタンスに割り当てられていないシークレットへのアクセス
• 想定外の IP 範囲からのアクセス

OCI 固有の注意点

キー操作には Vault 管理エンドポイントが必要です：

# Find your vault's endpoint
oci kms management vault get --vault-id <vault-ocid> \
  --query 'data."management-endpoint"' --raw-output

# Use in key commands
oci kms management key create ... \
  --endpoint https://xxxxx-management.kms.us-ashburn-1.oraclecloud.com

リージョンごとの Vault の提供状況：

• すべての OCI リージョンで Vault サービスが利用できるわけではありません
• アーキテクチャを設計する前に、リージョンでの提供状況を確認してください
• リージョンをまたいだシークレットへのアクセスには遅延が加わります（10-50ms）

シークレットバンドルの Base64 デコード：

# Secret content is base64-encoded
secret_bundle = secrets_client.get_secret_bundle(secret_ocid)
encoded = secret_bundle.data.secret_bundle_content.content
decoded = base64.b64decode(encoded).decode('utf-8')  # Don't forget decode()

段階的な読み込み用リファレンス

OCI Vault リファレンス（Oracle 公式ドキュメント）

次の場合に読み込みます oci-vault-reference.md：

• Vault と KMS の API ドキュメントを包括的に確認する必要がある
• キー管理と暗号化オプションについて理解する
• HSM によるキー保護を実装する
• Vault アーキテクチャに関する Oracle 公式ガイダンスが必要である
• クロスリージョンのシークレットレプリケーションを設定する

次の場合は読み込まないでください：

• シークレットをすばやく取得する例を確認する場合（このスキルで説明しています）
• 権限をデバッグする場合（上記の判断ツリーを参照してください）
• シークレットのローテーションパターンを確認する場合（上記で説明しています）

---

このスキルを使用する場面

• Vault に認証情報を保存する：シークレットの整理、IAM の設定
• シークレットの取得に失敗する：403 エラー、権限のデバッグ
• コストを最適化する：キャッシュ戦略、API 呼び出しの削減
• シークレットをローテーションする：ダウンタイムなしの更新、バージョン管理
• セキュリティ：一時ファイルの取り扱い、ログ記録のアンチパターン、監査の設定
• 本番環境：インスタンスプリンシパルの設定、監視アラート