secrets-management

OCI Vault 和 Secrets Management — 专家知识

🏗️ 使用 OCI Landing Zone Terraform 模块

不要重复造轮子。 使用 oracle-terraform-modules/landing-zone 设置 Vault。

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（每月前 10k 次免费）
• 不使用缓存：每小时 1000 次请求 × 24 × 30 = 每月 720k 次 = $2.16/月
• 使用 60 分钟缓存：每小时 1000 次请求 → 每天调用 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 时：会收到令人困惑的 403 错误：“User not authorized to perform this operation”（用户无权执行此操作）

常见错误：忘记授予 use keys 权限，花数小时排查“授权失败”问题。

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>
• Secret 操作：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（每月 10k 次免费）

计算示例：

不使用缓存（每次 API 调用都检索）：

• 每小时 1000 次 API 调用
• 24 小时 × 30 天 = 每月 720,000 次 Vault 请求
• (720,000 / 10,000) × $0.03 = 每月 $2.16

使用 60 分钟的缓存 TTL：

• 每小时 1000 次 API 调用 → 每小时 1 次 Vault 请求
• 24 小时 × 30 天 = 每月 720 次 Vault 请求
• 低于 10k 免费额度 = 每月 $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 或实例主体身份
• 什么：访问的密钥 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-50 毫秒）

密钥包 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 支持的密钥保护
• 需要 Oracle 官方的 Vault 架构指南
• 设置跨区域密钥复制

以下情况请勿加载：

• 快速检索密钥示例（本技能中已有）
• 权限调试（上方的决策树中已有）
• 密钥轮换模式（上文中已有）

---

何时使用此技能

• 在 Vault 中存储凭据：密钥组织、IAM 设置
• 密钥检索失败：403 错误、权限调试
• 成本优化：缓存策略、减少 API 调用
• 密钥轮换：零停机更新、版本管理
• 安全性：临时文件处理、日志记录反模式、审计设置
• 生产环境：实例主体配置、监控告警