存储库中的秘密:预提交和 CI 中的 gitleaks 以及发生泄漏时该怎么办
如果密钥已经泄露,首先这个
操作顺序比工具更重要,所以让我们从最后开始。
- 1.**立即从提供商处撤销并重新颁发密钥,然后再清除历史记录和分析。公共存储库会不断被机器人扫描,最终出现在公共提交中的密钥从推送的那一刻起就应该被视为受到损害。
- 2.更新所有环境中的密钥(CI 密钥、托管变量、密钥管理器)并重新启动服务。
- 3.与您的提供商检查密钥使用日志:来自陌生地址的呼叫、异常数量、创建的资源。对于云密钥 - 新实例和 IAM 用户。
- 4.然后才决定是否清除历史记录。 您可以通过
git filter-repo重写它,但您无法控制克隆、分叉、CI缓存和镜像服务的副本。从历史中删除是为了卫生,而不是为了修复漏洞。如果密钥被撤销,无论它在哪里都是无害的。
一个常见的错误是删除带有新提交的文件并认为问题已解决。该值保留在历史记录中,并可通过一个命令 git log -p 找到。
预防:本地gitleaks
gitleaks 根据一组规则在代码和历史记录中搜索与已知服务的键和高熵值相似的字符串。通过预提交框架连接:
# .pre-commit-config.yaml
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.30.1 # конкретный тег; pre-commit autoupdate обновит его
hooks:
- id: gitleakspip install pre-commit # или brew install pre-commit pre-commit install # ставит хук в .git/hooks pre-commit run gitleaks --all-files
该钩子仅检查您提交的内容,因此速度很快。但它是本地的:没有运行pre-commit install的同事没有它,并且它被git commit --no-verify禁用。因此,预提交对于开发者来说是一种便利,真正的障碍是CI中的验证。
一次性检查现有存储库的整个历史记录(在版本 8.19 及更高版本中,命令称为 git 和 dir;保留旧的 detect 和 protect 以实现兼容性):
gitleaks git --redact -v .
--redact 标志隐藏输出中找到的值 - 如果没有它,如果将报告复制到票证中,报告本身就会成为泄漏。
CI 中的验证
# .github/workflows/secrets.yml
name: secrets
on: [pull_request, push]
permissions:
contents: read
jobs:
gitleaks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # полная история, иначе проверяется только последний коммит
- uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}对于组织存储库,gitleaks-action 需要 GITLEAKS_LICENSE 变量中的许可证密钥(免费,可根据请求提供)。没有密钥的替代方法是在 run 步骤中运行二进制文件本身或 gitleaks Docker 映像。
将此任务设为分支保护规则中的强制检查。然后,本地泄露的秘密将在 PR 处停止,甚至在它到达主分支之前。
误报
测试装置、文档中的示例密钥以及锁定文件中的哈希值有时看起来像秘密。选项:
- 该行中的
gitleaks:allow注释是有针对性的例外,在评论中可见。 - 文件
.gitleaksignore包含报告中具体调查结果的指纹。 - 拥有
.gitleaks.toml,扩展标准规则并沿路径设置例外。
不要排除像 config/ 这样的整个目录 - 这就是秘密最终所在的地方。
GitHub 推送保护
GitHub 具有内置秘密扫描功能,可以阻止已知令牌格式的推送。它可免费用于公共存储库,也可作为付费 GitHub Secret Protection 的一部分用于私人存储库。它补充了 gitleaks:它在服务器端工作,不能被标记错过,但它只知道 GitHub 合作伙伴的格式,看不到你自己的任何类型的秘密。
原则上如何防止泄漏
- 从第一次提交开始,
.gitignore中的.env*在存储库中只有.env.example具有空值。 - 具有最小权限的密钥并且针对每个环境是独立的:泄漏测试密钥不应打开生产。
- CI 中的秘密 - 通过内置的秘密存储,从不在 YAML 中。
- 注意日志:调试构建时打印的环境变量值保留在 CI 日志中。
不该做什么
- 提交之前不要“加密”base64 密钥。扫描仪并不总是能捕获到这一点,但攻击者会在一秒钟内对其进行解码。
- 在明确是否有人使用过该钥匙之前,请勿延迟轮换。澄清需要几个小时,轮换需要几分钟。
- 不要默默地重写共享线程的历史记录。拥有本地副本的同事将在下一次推送时恢复旧的提交;同意并要求重新克隆存储库。