env-secrets-manager

环境变量与密钥管理器

级别: POWERFUL 分类: Engineering 领域: 安全 / DevOps / 配置管理

---

概述

在本地开发和生产工作流中管理环境变量的规范性与密钥安全。本技能侧重于实用的审计、配置漂移感知以及轮换就绪性。

核心能力

• .env 与 .env.example 的生命周期指导
• 代码仓库工作区中的密钥泄露检测
• 针对疑似凭据的分级别问题发现
• 轮换与遏制的操作指引
• 可直接集成到 CI 检查中的输出

---

使用场景

• 提交涉及 env/配置文件的修改之前
• 安全审计与事件分诊期间
• 为需要遵循安全环境变量规范的贡献者办理入职时
• 验证没有明显的密钥被硬编码时

---

快速开始

# 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. 使用密钥管理服务作为生产环境的权威来源。
2. 将开发环境的 env 文件保存在本地，并加入 gitignore。
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. Sidecar 注入 — 由 sidecar 容器（例如 Vault Agent）将密钥写入共享卷，或将其注入为环境变量。
3. Init 容器 — Kubernetes init 容器在主容器启动前获取密钥。
4. CSI 驱动 — 通过 Secrets Store CSI Driver 将密钥挂载为文件系统卷。

交叉引用: 有关生产环境 Vault 基础设施模式、高可用部署和灾难恢复流程，请参阅 engineering/secrets-vault-manager。

---

密钥轮换工作流

陈旧的密钥就是隐患。轮换可以确保即使凭据泄露，其可用时长也是有限的。

第一阶段：检测

• 在密钥存储的元数据中记录密钥的创建日期和过期日期。
• 设置在过期前 30、14 和 7 天的提醒。
• 使用 scripts/env_auditor.py 标记没有轮换日期记录的密钥。

第二阶段：轮换

1. 生成新凭据（API 密钥、数据库密码、证书）。
2. 并行部署新凭据到所有使用方（应用、服务、流水线）。
3. 验证每个使用方都能使用新凭据完成身份验证。
4. 仅在所有使用方均确认运行正常后，才吊销旧凭据。
5. 更新元数据，记录新的轮换时间戳和下次轮换日期。

第三阶段：自动化

• 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 变量。
• 使用 HashiCorp Vault 集成（secrets:vault）动态注入密钥，无需在 GitLab 中存储其值。
• 将变量限定在特定环境（production、staging）中，以落实最小权限原则。

通用模式

• 即使是为了调试，也切勿在流水线输出中回显或打印密钥值。
• 尽可能使用短期令牌（OIDC、STS AssumeRole），而不是静态凭据。
• 限制 PR 访问：不要将密钥暴露给由 Fork 或不受信任分支触发的流水线。
• 与应用密钥同周期轮换 CI 密钥；流水线凭据同样是攻击入口。
• 定期审计流水线日志，排查屏蔽机制可能遗漏的意外密钥暴露。

---

提交前密钥检测

在密钥进入版本控制之前将其拦截，是性价比最高的防御手段。以下两款主流工具覆盖了这一领域。

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 Releases 下载。
• 提交前钩子：gitleaks git --pre-commit --staged
• 基线扫描：gitleaks detect --source . --report-path gitleaks-report.json
• 在 .gitleaksignore 中管理误报（每行一个指纹）。

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	Key Vault 访问事件，包括调用方身份和 IP
GCP	Cloud Audit Logs	Secret Manager 的数据访问日志，包含主体和时间戳
Vault	Audit Backend	完整的请求/响应日志（file、syslog 或 socket 后端）

告警策略

• 对来自未知 IP 段的访问或预期集合之外的服务账号访问发出告警。
• 对批量读取密钥（在某个时间窗口内访问的密钥数量超过 N 个）发出告警。
• 对部署窗口之外、且没有 CI/CD 流水线运行时的访问发出告警。
• 将审计日志接入你的 SIEM（Splunk、Datadog、Elastic），与其他安全事件进行关联分析。
• 将审计日志审查纳入访问重新认证流程，每季度进行一次。

---

交叉引用

本 Skill 涵盖环境变量卫生和密钥检测。如需深入了解相关领域，请参阅：

Skill	路径	关系
Secrets Vault Manager	engineering/secrets-vault-manager	生产环境密钥库基础设施、高可用部署、灾难恢复
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 密钥挂载、Sealed Secrets