secrets-handlinglisted

# 密钥处理 ## 何时用 - 代码中需要使用 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 生成的代码中密钥硬编码比例显著高于人类开发者。 **怎么做：** ```python # 反例：硬编码 OPENAI_API_KEY = "sk-proj-abc123xyz..." # ❌ 直接写死在代码里 # 正例：从环境变量读取 import os OPENAI_API_KEY = os.environ["OPENAI_API_KEY"] # ✅ 启动时不存在则报错 ``` ```gitignore # .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. 日志、报错、前端不输出密钥 **规则：** 日志输出、异