环境变量机密管理器

env-secrets-manager
分类通用
作者Alireza Rezvani
许可MIT
评分4.50/5
使用14.5K

环境与密钥管理器 (Env & Secrets Manager)

等级： 强大 (POWERFUL)
类别： 工程 (Engineering)
领域： 安全 / DevOps / 配置管理

---

概述

管理本地开发和生产工作流中的环境变量卫生与密钥安全。本技能专注于实用的审计、漂移感知和轮换准备。

核心能力

  • .env 和 .env.example 生命周期指导
  • 仓库工作树的密钥泄露检测
  • 基于严重程度的潜在凭据分析
  • 轮换与遏制的运维指南
  • 可集成至 CI 检查的输出格式

---

使用场景

  • 在推送涉及环境/配置文件的提交之前
  • 在进行安全审计和事故分诊期间
  • 为需要安全环境规范的新贡献者进行引导时
  • 在验证是否存在硬编码的明显密钥时

---

快速上手

bash
# 扫描仓库中可能的密钥泄露
python3 scripts/env_auditor.py /path/to/repo

为 CI 流水线输出 JSON 格式

python3 scripts/env_auditor.py /path/to/repo --json

---

推荐工作流

1. 在仓库根目录运行 scripts/env_auditor.py。
2. 优先处理 critical（紧急）和 high（高）级别的发现。
3. 轮换真实凭据并删除泄露的值。
4. 根据需要更新 .env.example 和 .gitignore。
5. 添加或加强 pre-commit/CI 密钥扫描门禁。

---

参考文档

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

---

常见陷阱

  • 在 .env.example 中提交真实值
  • 轮换了某个系统但遗漏了下游消费者
  • 在调试或事故响应期间将密钥打印到日志中
  • 在未验证的情况下将疑似泄露视为低优先级

最佳实践

1. 使用密钥管理器作为生产环境的唯一事实来源。
2. 将开发环境文件保持在本地并加入 .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 初始化容器在主容器启动前获取机密。
4. CSI 驱动 —— 通过 Secrets Store CSI Driver 将机密挂载为文件系统卷。

> 交叉引用： 关于生产环境 Vault 基础设施模式、高可用 (HA) 部署和灾难恢复流程，请参阅 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 流水线中的机密需要谨慎处理，以避免在日志、制品或 PR 上下文中泄露。

GitHub Actions

  • 通过 ${{ secrets.SECRET_NAME }} 使用 仓库机密 (repository secrets) 或 环境机密 (environment secrets)。
  • 优先使用 OIDC 联邦身份验证（使用 role-to-assume 的 aws-actions/configure-aws-credentials），而非长期访问密钥。
  • 为环境机密设置审核员，可为生产部署增加审批门禁。
  • GitHub 会自动在日志中掩码机密，但应避免对机密值使用 echo 或 toJSON()。

GitLab CI

  • 将机密存储为 CI/CD 变量，并启用 masked（掩码）和 protected（保护）标志。
  • 使用 HashiCorp Vault 集成 (secrets:vault) 进行动态机密注入，无需在 GitLab 中存储具体值。
  • 将变量范围限定在特定环境（如 production、staging），以执行最小权限原则。

通用模式

  • 严禁在流水线输出中 echo 或 print 机密值，即使是为了调试。
  • 尽可能使用 短期令牌（OIDC, STS AssumeRole）替代静态凭据。
  • 限制 PR 访问权限 —— 不要将密钥暴露给由 fork 或不可信分支触发的流水线。
  • 定期轮换 CI 密钥 —— 轮换周期应与应用程序密钥一致；流水线凭据同样是攻击向量。
  • 定期审计流水线日志 —— 检查掩码（masking）可能遗漏的意外密钥泄露。

---

提交前密钥检测 (Pre-Commit Secret Detection)

在密钥进入版本控制之前将其拦截是最具成本效益的防御手段。目前有两个主流工具可实现此功能。

gitleaks

toml
# .gitleaks.toml — 最小化配置
[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 下载。
  • Pre-commit 钩子：gitleaks git --pre-commit --staged
  • 基线扫描：gitleaks detect --source . --report-path gitleaks-report.json
  • 在 .gitleaksignore 中管理误报（每行一个指纹）。

detect-secrets

bash
# 生成基线
detect-secrets scan --all-files > .secrets.baseline

Pre-commit 钩子 (通过 pre-commit 框架)


.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 纳入版本控制，以便整个团队共享排除项。
  • 在安全审计期间审查误报列表 —— 随着时间推移，某些模式可能会掩盖真实的泄露。
  • 优先通过收紧正则模式而非广泛忽略文件来减少误报。

---

审计日志 (Audit Logging)

了解谁在何时访问了哪个密钥，对于事件调查和合规性至关重要。

云原生审计追踪

| 提供商 | 服务 | 捕获内容 |
|----------|---------|-----------------|
| AWS | CloudTrail | 所有的 GetSecretValue、DescribeSecret、RotateSecret API 调用 |
| Azure | Activity Log + Diagnostic Logs | Key Vault 访问事件，包括调用者身份和 IP |
| GCP | Cloud Audit Logs | Secret Manager 的数据访问日志，包含主体和时间戳 |
| Vault | Audit Backend | 完整的请求/响应日志（支持文件、syslog 或 socket 后端） |

告警策略

  • 对来自未知 IP 范围或预期服务账号之外的访问发出告警。
  • 对批量读取密钥（在特定时间窗口内访问超过 N 个密钥）发出告警。
  • 对在部署窗口之外且无 CI/CD 流水线运行时的访问发出告警。
  • 将审计日志接入 SIEM（如 Splunk, Datadog, Elastic），以便与其他安全事件进行关联分析。
  • 每季度审查一次审计日志，作为访问权限重新认证的一部分。

---

交叉引用

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

| 技能 | 路径 | 关系 |
|-------|------|-------------|
| 密钥库管理器 (Secrets Vault Manager) | engineering/secrets-vault-manager | 生产环境 Vault 基础设施、高可用部署、灾难恢复 |
| 高级 SecOps (Senior SecOps) | engineering/senior-secops | 安全运营视角、事件响应 |
| CI/CD 流水线构建师 (CI/CD Pipeline Builder) | engineering/ci-cd-pipeline-builder | 流水线架构、密钥注入模式 |
| 基础设施即代码 (Infrastructure as Code) | engineering/infrastructure-as-c | (待续) |
| code | Terraform/Pulumi 密钥后端配置 |
| 容器编排 | engineering/container-orchestration | Kubernetes 密钥挂载、密封密钥 (sealed secrets) |