secrets-vault-manager

密钥保险库管理器

等级: POWERFUL 类别: 工程 领域: 安全 / 基础设施 / DevOps

---

概述

面向运行 HashiCorp Vault、云原生密钥存储或混合架构的团队,提供生产环境密钥基础设施管理。本技能涵盖策略编写、认证方法配置、自动轮换、动态密钥、审计日志记录以及事件响应。

与 env-secrets-manager 的区别: 后者负责本地 .env 文件的卫生管理与泄露检测。本技能作用于基础设施层,涉及 Vault 集群、云 KMS、证书颁发机构以及 CI/CD 密钥注入。

适用场景

• 搭建新的 Vault 集群或迁移到托管密钥存储
• 为服务、CI 运行器和人工操作员设计认证方法
• 实施自动化凭据轮换(数据库、API 密钥、证书)
• 为合规需求审计密钥访问模式(SOC 2、ISO 27001、HIPAA)
• 应对需要大规模吊销的密钥泄露事件
• 将密钥集成到 Kubernetes 工作负载或 CI/CD 流水线中

---

HashiCorp Vault 模式

架构决策

决策	建议	理由
部署模式	基于 Raft 存储的 HA	无外部依赖,内置领导者选举
自动解封	云 KMS(AWS KMS / Azure Key Vault / GCP KMS)	消除手动解封,支持自动重启
命名空间	每个环境一个(dev/staging/prod)	隔离爆炸半径,策略相互独立
审计设备	文件 + syslog(双写)	若所有审计设备均失败,Vault 会拒绝请求——双写可防止服务中断

认证方法

AppRole — 面向服务和批处理作业的机器对机器认证。

# Enable AppRole
path "auth/approle/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Application-specific role
vault write auth/approle/role/payment-service \
  token_ttl=1h \
  token_max_ttl=4h \
  secret_id_num_uses=1 \
  secret_id_ttl=10m \
  token_policies="payment-service-read"

Kubernetes — 通过服务账户令牌实现的 Pod 原生认证。

vault write auth/kubernetes/role/api-server \
  bound_service_account_names=api-server \
  bound_service_account_namespaces=production \
  policies=api-server-secrets \
  ttl=1h

OIDC — 通过 SSO 提供商(Okta、Azure AD、Google Workspace)实现的人工操作员访问。

vault write auth/oidc/role/engineering \
  bound_audiences="vault" \
  allowed_redirect_uris="https://vault.example.com/ui/vault/auth/oidc/oidc/callback" \
  user_claim="email" \
  oidc_scopes="openid,profile,email" \
  policies="engineering-read" \
  ttl=8h

密钥引擎

引擎	使用场景	TTL 策略
KV v2	静态密钥(API 密钥、配置)	带版本,手动轮换
Database	动态数据库凭据	默认 1 小时,最长 24 小时
PKI	TLS 证书	叶子证书 90 天,中间 CA 5 年
Transit	加密即服务	每 90 天轮换密钥
SSH	签发的 SSH 证书	交互式 30 分钟,自动化 8 小时

策略设计

遵循最小权限原则,采用基于路径的细粒度控制:

# payment-service-read policy
path "secret/data/production/payment/*" {
  capabilities = ["read"]
}

path "database/creds/payment-readonly" {
  capabilities = ["read"]
}

# Deny access to admin paths explicitly
path "sys/*" {
  capabilities = ["deny"]
}

策略命名约定: {service}-{access-level}(例如 payment-service-read、api-gateway-admin)。

---

云密钥存储集成

对比矩阵

特性	AWS Secrets Manager	Azure Key Vault	GCP Secret Manager
轮换	内置 Lambda	通过 Functions 自定义逻辑	Cloud Functions
版本控制	自动	手动或自动	自动
加密	AWS KMS(默认或 CMK)	HSM 支持	Google 管理或 CMEK
访问控制	IAM 策略 + 资源策略	RBAC + 访问策略	IAM 绑定
跨区域	支持复制	默认异地冗余	支持复制
审计	CloudTrail	Azure Monitor + 诊断日志	Cloud Audit Logs
计费模式	按密钥 + 按 API 调用	按操作 + 按密钥	按密钥版本 + 按访问

如何选择

• AWS Secrets Manager:开箱即用支持 RDS/Aurora 凭据轮换。适合完全部署在 AWS 上的场景。
• Azure Key Vault:证书管理能力突出。Azure AD 集成工作负载的必选项。
• GCP Secret Manager:API 界面最简洁。适合使用 Workload Identity 的 GKE 原生工作负载。
• HashiCorp Vault:多云、动态密钥、PKI、Transit 加密。适合复杂或混合环境。

SDK 访问模式

原则: 始终在启动时或通过边车(sidecar)获取密钥——切勿将其打包进镜像或配置文件。

# AWS Secrets Manager pattern
import boto3, json

def get_secret(secret_name, region="us-east-1"):
    client = boto3.client("secretsmanager", region_name=region)
    response = client.get_secret_value(SecretId=secret_name)
    return json.loads(response["SecretString"])

# GCP Secret Manager pattern
from google.cloud import secretmanager

def get_secret(project_id, secret_id, version="latest"):
    client = secretmanager.SecretManagerServiceClient()
    name = f"projects/{project_id}/secrets/{secret_id}/versions/{version}"
    response = client.access_secret_version(request={"name": name})
    return response.payload.data.decode("UTF-8")

# Azure Key Vault pattern
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

def get_secret(vault_url, secret_name):
    credential = DefaultAzureCredential()
    client = SecretClient(vault_url=vault_url, credential=credential)
    return client.get_secret(secret_name).value

---

密钥轮换工作流

按密钥类型划分的轮换策略

密钥类型	轮换频率	方法	停机风险
数据库密码	30 天	双账号切换	零（A/B 轮换）
API 密钥	90 天	生成新密钥，废弃旧密钥	零（重叠窗口）
TLS 证书	到期前 60 天	ACME 或 Vault PKI	零（平滑重载）
SSH 密钥	90 天	Vault 签发的证书	零（基于 CA）
服务令牌	24 小时	动态生成	零（短期有效）
加密密钥	90 天	密钥版本化（重新封装）	零（版本共存）

数据库凭证轮换（双账号）

1. 存在两个数据库账号：app_user_a 和 app_user_b
2. 应用当前使用 app_user_a
3. 轮换操作更新 app_user_b 的密码，并更新密钥存储
4. 应用在下一次获取凭证时切换到 app_user_b
5. 经过宽限期后，轮换 app_user_a 的密码
6. 循环重复

API 密钥轮换（重叠窗口）

1. 向服务商生成新的 API 密钥
2. 将新密钥以 current 存入密钥存储，并将旧密钥移至 previous
3. 部署应用，应用读取 current
4. 所有实例重启完成（或 TTL 过期）后，吊销 previous
5. 在吊销之前，通过监控确认旧密钥的使用量为零

---

动态密钥

动态密钥按需生成，并自动过期。只要条件允许，应优先使用动态密钥而非静态凭证。

数据库动态凭证（Vault）

# Configure database engine
vault write database/config/postgres \
  plugin_name=postgresql-database-plugin \
  connection_url="postgresql://{{username}}:{{password}}@db.example.com:5432/app" \
  allowed_roles="app-readonly,app-readwrite" \
  username="vault_admin" \
  password="<admin-password>"

# Create role with TTL
vault write database/roles/app-readonly \
  db_name=postgres \
  creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
  default_ttl=1h \
  max_ttl=24h

云 IAM 动态凭证

Vault 可以生成短期有效的 AWS IAM 凭证、Azure 服务主体密码或 GCP 服务账号密钥，从而彻底消除长期有效的云凭证。

SSH 证书颁发机构

用 Vault 签发证书的模式取代 SSH 密钥分发：

1. Vault 充当 SSH CA
2. 用户或机器以较短的 TTL（30 分钟）申请签名证书
3. SSH 服务器信任 CA 公钥，无需管理 authorized_keys
4. 证书自动过期，正常运维中无需吊销

---

审计日志

记录内容

事件	优先级	保留期
密钥读取访问	高	至少 1 年
密钥创建/更新	高	至少 1 年
认证方式登录	中	90 天
策略变更	严重	2 年（合规要求）
失败的访问尝试	严重	1 年
令牌创建/吊销	中	90 天
Seal/Unseal 操作	严重	永久

异常检测信号

• 密钥被来自新 IP/CIDR 范围的请求访问
• 访问量激增（超过某路径基线的 3 倍）
• 人工认证方式在非工作时间访问
• 服务访问超出其策略范围的密钥（被拒绝的请求）
• 同一来源出现多次认证失败
• 创建了 TTL 异常长的令牌

合规报告

定期生成以下内容的报告：

1. 访问清单 — 哪些身份在何时访问了哪些密钥
2. 轮换合规性 — 逾期未轮换的密钥
3. 策略漂移 — 自上次审查以来被修改的策略
4. 孤立密钥 — 近期（>90 天）无访问记录的密钥

使用 audit_log_analyzer.py 解析 Vault 或云审计日志，以发现上述信号。

---

应急处理流程

密钥泄露响应（立即执行）

时间目标：发现后 15 分钟内完成遏制。

1. 确定影响范围 — 哪些密钥发生泄露，泄露位置（代码仓库、日志、错误信息、第三方）
2. 立即吊销 — 在源头轮换受损凭证（服务商 API、Vault、云密钥管理服务）
3. 使令牌失效 — 吊销所有访问过泄露密钥的 Vault 令牌
4. 审计影响面 — 在暴露时间窗口内查询审计日志，检查受损密钥的使用情况
5. 通知相关方 — 安全团队、受影响服务的负责人、合规部门（若涉及个人信息或受监管数据）
6. 事后复盘 — 记录根本原因，更新控制措施以防止再次发生

Vault 密封操作

何时密封: 影响 Vault 基础设施的活跃安全事件,或怀疑密钥泄露。

密封会停止所有 Vault 操作。仅作为最后手段使用。

解封流程:

1. 召集达到法定人数的解封密钥持有者(Shamir 阈值)
2. 或确认自动解封的 KMS 密钥可以访问
3. 通过 vault operator unseal 解封,或重启并使用自动解封
4. 验证审计设备已重新连接
5. 检查活跃租约和令牌有效性

完整的应急手册请参阅 references/emergency_procedures.md。

---

CI/CD 集成

Vault Agent Sidecar(Kubernetes)

Vault Agent 与应用 Pod 并行运行,负责身份认证和密钥渲染:

# Pod annotation for Vault Agent Injector
annotations:
  vault.hashicorp.com/agent-inject: "true"
  vault.hashicorp.com/role: "api-server"
  vault.hashicorp.com/agent-inject-secret-db: "database/creds/app-readonly"
  vault.hashicorp.com/agent-inject-template-db: |
    {{- with secret "database/creds/app-readonly" -}}
    postgresql://{{ .Data.username }}:{{ .Data.password }}@db:5432/app
    {{- end }}

External Secrets Operator(Kubernetes)

适用于偏好声明式 GitOps 而非 Agent Sidecar 的团队:

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: api-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: api-credentials
  data:
    - secretKey: api-key
      remoteRef:
        key: secret/data/production/api
        property: key

GitHub Actions OIDC

通过 OIDC 联合认证,在 CI 中消除长期有效的密钥:

- name: Authenticate to Vault
  uses: hashicorp/vault-action@v2
  with:
    url: https://vault.example.com
    method: jwt
    role: github-ci
    jwtGithubAudience: https://vault.example.com
    secrets: |
      secret/data/ci/deploy api_key | DEPLOY_API_KEY ;
      secret/data/ci/deploy db_password | DB_PASSWORD

---

反模式

反模式	风险	正确做法
在源代码中硬编码密钥	通过代码仓库、日志或错误输出泄露	运行时从密钥存储中获取
长期有效的静态令牌(>30 天)	凭据陈旧,无法追溯责任	动态密钥,或短 TTL 加轮换
共享服务账号	无法按消费方进行审计追踪	每个服务使用独立身份和唯一凭据
没有轮换策略	凭据泄露后会无限期有效	按计划自动轮换
在 CI 中通过环境变量传递密钥	在构建日志和进程表中可见	使用 Vault Agent 或基于 OIDC 的注入
只有单一解封密钥持有者	总线系数为 1,恢复受阻	Shamir 分割(3-of-5)或自动解封
未配置审计设备	对访问行为完全不可见	双审计设备(文件 + syslog)
通配符策略(path "*")	权限过大,违反最小权限原则	为每个服务显式编写基于路径的策略

---

工具

脚本	用途
vault_config_generator.py	根据应用需求生成 Vault 策略和认证配置
rotation_planner.py	根据密钥清单文件生成轮换计划
audit_log_analyzer.py	分析审计日志,查找异常和合规缺口

---

交叉引用

• env-secrets-manager — 本地 .env 文件管理、泄露检测、配置漂移感知
• senior-secops — 安全运营、事件响应、威胁建模
• ci-cd-pipeline-builder — 使用密钥的流水线设计
• docker-development — 容器密钥注入模式
• helm-chart-builder — Helm Chart 中的 Kubernetes 密钥管理