技能
Security
轮换操作手册
凭据轮换操作手册——消费者清单、鉴权范围验证、完整载荷重放、规范密钥路径、轮换日志。
概述
凭据轮换看起来很简单——签发新密钥、吊销旧密钥——而这正是它出错的原因。反复出现的故障模式并不在轮换本身,而在其周边:一个没人记得的消费者、一个未真正通过鉴权却返回绿色的验证探测、一个隐藏在鉴权失败背后的校验回归,以及一个被写回其他文档都不认可的路径的密钥。本技能将反复真实轮换演练中提炼出的纪律正式化。
何时使用
- 轮换任何凭据:API 密钥、访问令牌、OAuth 客户端密钥、webhook 签名密钥、TLS 密钥、数据库密码。
- 响应泄露或暴露的凭据(意外提交、明文文件、审计发现)。
- 验证过去的轮换是否真正收敛(密钥存储 ↔ 生产者真值核对)。
操作手册
- 首先清点每一个消费者。 枚举凭据被读取的每一处:CI/CD 密钥存储、env 文件、密钥管理器路径、服务配置、cron 任务、同级项目。在密钥存储与生产者之间执行真值核对——将“消费者副本 ≠ 生产者真值”作为任何此前正常工作的集成返回 HTTP 401 的首要假设。
- 审慎选择轮换窗口。 当提供方支持时,优先使用宽限窗口(双重有效期);对于正在活跃泄露的凭据,必须立即吊销(宽限 = 0),否则仅在消费者原子更新时才可接受。
- 仅使用鉴权范围端点进行验证。 公共或目录端点无需鉴权即返回成功——这是虚假的绿色。必须双向验证:旧凭据 → 明确拒绝;新凭据 → 成功。在宣布失败前,需考虑提供方的传播延迟。
- 重放完整生产者载荷,而非最小探测。 鉴权失败可能掩盖集成中断期间累积的校验回归。只有完整的端到端重放才能证明集成可用。
- 将新密钥存储在规范路径,该路径由项目的密钥存储模式文档定义——绝不要存储在计划时临时发明的路径。
- 记录轮换——日期、凭据名称、原因、拒绝/成功证据、已更新的消费者——写入项目的凭据文档。
- 泄露响应附加项: 先轮换,后清理;保留本地镜像作为清理前备份(同一远程上的备份标签会被强制推送销毁);从全新克隆验证清理结果。
故障模式检查清单
- 消费者副本 ≠ 生产者真值 → 正常工作的集成返回 401 → 步骤 1 真值核对。
- 虚假绿色验证 → 已吊销密钥仍然“可用” → 步骤 3 鉴权范围端点。
- 隐藏的校验回归 → 修复 401 后立即出现 400 → 步骤 4 完整重放。
- 密钥路径约定漂移 → 三份文档命名三个路径 → 步骤 5 规范模式。
- 备份标签因强制推送丢失 → 清理前状态无法恢复 → 步骤 7 本地镜像。
- 过早验证失败 → 新密钥在签发后数秒被拒绝 → 步骤 3 传播等待。