secrets-handling

密钥处理

何时用

• 代码中需要使用 API key、数据库密码、JWT secret、OAuth 凭据等任何形式的密钥。
• 部署配置、CI/CD pipeline 涉及凭据传递时。
• 接到密钥泄露告警，需要评估影响并响应时。
• 代码审查发现任何疑似硬编码凭据时。

核心规则

1. 密钥不进代码库：用环境变量或 secret manager

规则： 任何密钥、token、密码都不允许出现在代码文件、配置文件、注释里；通过环境变量或专用 secret 管理工具（AWS Secrets Manager、HashiCorp Vault、GCP Secret Manager）在运行时注入；.env 文件本地使用但必须加入 .gitignore。

为什么： AI 生成示例代码时最常见的陷阱就是把真实密钥硬编码进代码并提交。GitHub 的安全研究表明，每天有数万个 API key 被意外推送到公开仓库，其中大量来自"我只是先写死方便测试，待会改"的侥幸心态，但改了代码、历史记录里的密钥仍然存在。GitGuardian 报告显示 AI 生成的代码中密钥硬编码比例显著高于人类开发者。

怎么做：

# 反例：硬编码
OPENAI_API_KEY = "sk-proj-abc123xyz..."    # ❌ 直接写死在代码里

# 正例：从环境变量读取
import os
OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]   # ✅ 启动时不存在则报错

# .gitignore
.env
.env.local
.env.production
*.pem
*_rsa
*_rsa.pub
credentials.json

• 提供 .env.example（只含变量名，无值）作为文档，不提供含真实值的 .env。

---

2. 已泄露的密钥立即轮换，不只是删除提交

规则： 发现密钥被提交进 git 后，第一步是立即在对应服务撤销/轮换该密钥，而不是先删除提交或 rebase；历史记录里的密钥通过 git filter-repo 清除只是事后补救，不能替代密钥轮换。

为什么： AI 有时建议"删掉那次提交然后 force push 就好了"，这是错误的响应姿势。在发现密钥泄露到 force push 完成之间的时间窗口内，密钥仍然有效；更重要的是，GitHub 等平台会镜像 push 事件，第三方爬虫可能在秒级内就已经抓取并存档了该密钥。2022 年 Samsung 源码泄露事件中，即便代码被删除，密钥早已被利用。

怎么做：

密钥泄露响应流程：
1. [立即] 在服务控制台撤销/轮换该密钥（AWS IAM、GitHub Settings、Stripe Dashboard 等）
2. [立即] 审计该密钥从泄露到轮换期间的访问日志，确认是否被滥用
3. [之后] 用 git filter-repo 清理历史（需要团队所有人重新 clone）
4. [之后] 复盘：补充 pre-commit 扫描防止再次发生

• 不要因为仓库是私有的就认为安全——内部人员、协作工具的 webhook、泄露的 deploy key 都可能导致私有仓库内容外泄。

---

3. 日志、报错、前端不输出密钥

规则： 日志输出、异常信息、HTTP 响应、前端 JavaScript（包括注释和 source map）都不能包含密钥或完整 token；脱敏展示时只显示前4后4位，中间用 **** 替代。

为什么： AI 生成的调试日志和错误处理代码里频繁出现 logger.error(f"API调用失败，key={api_key}, error={e}")，这行日志把完整 API key 写进日志文件。日志文件通常被运维、开发、监控系统等多人访问，远比代码库传播面广。前端 bundle 里的密钥更危险，任何访问网页的用户打开开发者工具即可获取。

怎么做：

def mask_secret(secret: str) -> str:
    """只保留前4后4位，其余脱敏"""
    if not secret or len(secret) <= 8:
        return "****"
    return f"{secret[:4]}****{secret[-4:]}"

# 反例
logger.error(f"调用失败: key={api_key}")         # ❌ 完整 key 进日志

# 正例
logger.error(f"调用失败: key={mask_secret(api_key)}, error={type(e).__name__}")  # ✅

• 前端只能持有"无权限到后台直接用的"公开配置，如 Google Maps 的 clientId（受域名限制），不能有任何后端密钥。
• Node.js 项目禁止把 .env 内容打包进 webpack bundle（检查 DefinePlugin 的使用）。