env-secrets-manager

环境变量与密钥管理器

完整的环境变量和密钥管理生命周期：涵盖开发/预发布/生产环境中的 .env 文件结构、自动生成并剥离敏感值的 .env.example、启动时的必需变量验证、git 历史中的密钥泄漏检测、凭据轮换操作手册、环境漂移检测，以及与 HashiCorp Vault、AWS SSM、1Password CLI 和 Doppler 的集成。

核心功能

• .env 生命周期 — 采用带分类区块的结构化布局，自动生成 .env.example（剥离密钥），支持特定环境的文件，并在启动时快速失败验证。
• 密钥泄漏检测 — 扫描 git 历史、工作区和暂存文件；支持 pre-commit 钩子；可检测 API 密钥、令牌、密码和私钥。
• 凭据轮换 — 提供逐项密钥操作手册、范围分析、零停机双重读取轮换，以及轮换后的验证与监控。
• 密钥管理器集成 — HashiCorp Vault（KV v2 + OIDC）、AWS SSM Parameter Store（KMS）、1Password CLI（模板注入）、Doppler（项目/配置）。
• 漂移检测 — 比较预发布和生产环境中的变量键集合，并报告缺失/多余的键。

使用场景

• 设置新项目 — 搭建 .env.example 并配置验证。
• 每次提交前 — 扫描意外暂存的密钥。
• 事件发生后 — 系统地轮换泄漏的凭据。
• 开发者入职 — 提供完整的环境设置说明。
• 审计 — 检测预发布和生产环境之间的漂移。
• 合规 — 展示密钥管理实践。

请先确认

运行前，请确认以下输入。如果有任何信息未知或含糊不清，请先询问 — 不要自行假设：

• 任务 — 搭建/验证 .env、扫描泄漏的密钥，或检查环境漂移（决定使用 env_validator.py、secret_scanner.py 还是 env_sync_checker.py）
• 目标路径 — 要扫描的 .env/.env.example 文件或目录（工具读取的输入）
• 密钥管理器 — Vault、AWS SSM、1Password 或 Doppler（决定生成的集成方式和轮换命令）

停止规则：只询问对输出影响最大的 2-3 项。如果用户说“直接起草”，则继续操作，并在产物顶部列出假设。

工具

工具	用途	命令
env_validator.py	根据 .env.example 验证 .env：检查缺失/多余变量、空密钥和泄漏的凭据	python scripts/env_validator.py .env.example .env --strict --check-secrets
secret_scanner.py	通过模式匹配扫描目录/文件中的硬编码密钥	python scripts/secret_scanner.py ./src --severity high --json
env_sync_checker.py	比较开发/预发布/生产环境的配置并报告漂移	python scripts/env_sync_checker.py .env.* --baseline .env.example

参考资料

根据任务加载相应参考资料 — 保持此文件精简，按需获取详细信息：

• references/env-file-structure.md — 标准 .env 布局、.env.* 文件层级、必需的 .gitignore 模式，以及完整的 Python 启动验证脚本。在搭建项目或接入验证时阅读。
• references/leak-detection-and-rotation.md — git 历史密钥扫描器、pre-commit 钩子、4 步凭据轮换操作手册（范围、生成、双重写入、验证），以及环境漂移检测脚本。在扫描泄漏或轮换凭据时阅读。
• references/secret-manager-integration.md — 用于存储、读取和轮换密钥的 Vault、AWS SSM 和 Doppler 具体命令。在集成密钥管理器时阅读。
• references/best-practices-and-troubleshooting.md — 常见陷阱、8 项最佳实践、故障排除表和成功标准。在审查设置或排查问题时阅读。

范围与限制

此技能涵盖：

• 适用于任何语言/框架的 .env 文件搭建、层级结构和验证
• 检测 Git 历史记录、暂存文件和工作区中的密钥泄露
• 采用零停机双读策略的凭据轮换操作手册
• HashiCorp Vault、AWS SSM、1Password CLI 和 Doppler 的集成模式

此技能不涵盖：

• 在 Kubernetes 中注入运行时密钥（有关部署流水线密钥，请参阅 engineering/ci-cd-pipeline-builder）
• 用于配置 Vault 集群或 SSM 策略的基础设施即代码（请参阅 engineering/ci-cd-pipeline-builder）
• 应用层静态或传输中加密（有关 API 安全模式，请参阅 engineering/api-design-reviewer）
• 身份和访问管理（IAM）角色设计或 SSO/OIDC 提供商配置（有关访问控制框架，请参阅 ra-qm-team/ 合规技能）

集成点

技能	集成方式	数据流
engineering/ci-cd-pipeline-builder	将 Vault/SSM/Doppler 中的密钥注入 CI/CD 流水线阶段	轮换操作手册的输出会传递给流水线密钥更新步骤
engineering/dependency-auditor	标记捆绑或要求使用硬编码凭据的依赖项	依赖项审计结果会触发对受影响仓库的密钥泄露扫描
engineering/skill-security-auditor	验证技能包是否未嵌入密钥或凭据	安全审计会引用此技能的检测正则表达式
engineering/codebase-onboarding	在入职检查清单中加入 .env.example 设置和密钥管理器访问权限	入职工作流会使用 .env 层级结构和验证脚本
engineering/observability-designer	监控轮换后的身份验证失败情况；针对异常密钥访问发出警报	轮换后验证指标会传入可观测性仪表板
ra-qm-team/soc2-compliance-auditor	展示满足 SOC 2 CC6.1 和 CC6.6 标准的密钥管理控制措施	轮换审计日志和访问策略可作为 SOC 2 证据材料