FDE Times 数据在招 FDE 职位 881▼8 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 55在招公司 185支持远程 25%美国薪资中位数 $201k招聘最多 Databricks 98
ENVI

前线部署工程师(FDE)的专业媒体

工具

HEAD 干净的仓库,Git 历史里仍可能泄露密钥

Gitleaks 能找出泄露的密钥,但在改写任何历史之前,先吊销密钥。

分享微博

要点速览

  • Gitleaks 底层使用 git log -p,能读到已从文件中删除、但仍留在旧提交里的密钥。
  • 发现密钥泄露后,第一步是吊销或轮换;改写历史无法撤销。
  • Gitleaks 已功能完备,今后只发布安全修复;Betterleaks 可直接替代,兼容原有参数和配置。
Git 历史时间线:第 3 次提交添加了一个含密钥的 .env 文件(橙色高亮),第 200 次提交删除了 .env,HEAD 看起来很干净。一条蓝色括线横跨整条时间线,表示 gitleaks git 会读取包括第 3 次提交在内的每个补丁。
在第 200 次提交中删除文件,并不能把密钥从第 3 次提交的补丁中移除。gitleaks git 命令底层运行 git log -p,读取的是整段历史,而不只是 HEAD。来源:Gitleaks 文档。

在第 200 次提交中删除的 .env 文件,在第 3 次提交里依然完好无损。所以,一个打开时看着干净的仓库,仍可能藏着预发环境的 API 密钥、第三方服务的令牌,或是有人匆忙粘贴进去的数据库密码。

对前线部署工程师(FDE)来说,交接时最需要注意这一点。你在客户的仓库或自己的仓库里干了几周,然后把整段历史交给对方的工程团队。任何人克隆之后,都能读到历史上存在过的每一个补丁。

Gitleaks 正是为此而生。这是一款采用 MIT 许可证的开源工具,用于在 Git 仓库、文件和目录中查找密码、API 密钥和令牌。它由 Zach Rice 创建,目前也由他维护。

为什么要扫描历史,而不只是文件?

关键在于 Gitleaks 读取仓库的方式。它的 git 命令扫描本地仓库时,底层运行的是 git log -p,也就是逐一检查历史中的每个补丁。一个密钥即使已从文件中删除,只要还留在旧的 diff 里,就会被发现。

如果只需扫描一个不是 Git 仓库的目录,比如客户以压缩包形式发来的源码导出,可以用 dir 命令。这两个命令取代了在 v8.19.0 中弃用的 detect 和 protect。如果某篇旧教程还在用 detect,说明写法已经过时。

设想一次交接

假设你刚为一家物流客户完成了三个月的系统集成。第一周为了尽快出演示,你把预发环境的 API 密钥硬编码进了配置文件。两天后你把它改成环境变量,并删掉了那一行。在 HEAD 上,仓库一尘不染。

在把仓库推送到客户的 GitHub 组织之前,你在仓库目录下打开终端,以详细模式运行一次扫描,查看每条发现的细节:

gitleaks git -v

输出精确指向第一周的那次提交、那个配置文件和那串密钥。普通的代码评审几乎肯定会漏掉它,因为没人会回头重读三个月前的 diff。

下意识的反应是去删掉那次提交。别把这当成第一步。

发现了密钥,先做什么?

GitHub 关于删除敏感数据的文档说得很明确:第一步是吊销该密钥,或换成新的。道理很简单:密钥一旦进入过历史,就必须假定它已被复制,只有让它失效才能真正消除风险。

旧密钥失效之后,才轮到是否用 git-filter-repo 改写历史的问题。GitHub 提醒,一旦越过这一步,改写就无法撤销,而且必须与仓库的所有协作者协调。

在客户现场,协调意味着先通知对方团队,因为现有的每个克隆都会与新历史产生分歧。

在上面的例子里,合理的做法是:轮换预发环境的密钥,在交接文档中注明某个旧提交包含一个已停用的密钥,然后与客户一起决定历史是否需要清理。这个决定属于客户,不能由你一人拍板。

交接前的三个常见错误

大多数事故并非缺工具,而是步骤顺序错了。下表汇总了由 Gitleaks 的工作方式和 GitHub 的指引直接推出的几个错误。

错误 为什么危险 正确做法
只扫描 HEAD 上的文件 已删除的密钥仍留在旧补丁里,任何克隆者都能读到 运行 gitleaks git 遍历完整历史
先删提交,再吊销密钥 密钥可能已被复制,删除提交并不能让它失效 先吊销或轮换密钥
不通知客户团队就改写历史 改写无法撤销,现有克隆会产生分歧 运行 git-filter-repo 之前与客户团队达成一致

清理之后,保持仓库干净

旧的发现处理完后,你不希望它们在每次扫描时重新冒出来。基线可以解决这个问题:Gitleaks 会忽略已记录在基线中的旧发现,之后的扫描只报告新的泄露。

只需两步。第一次扫描把结果写入报告文件,这个文件就成为基线。之后运行时,让 Gitleaks 指向该基线,并把新发现写入另一个文件:

# 首次运行:将现有的全部发现保存为基线
gitleaks git --report-path gitleaks-report.json

# 后续运行:忽略已知发现,只记录新的泄露
gitleaks git --baseline-path gitleaks-report.json --report-path findings.json

按 Zach Rice 本人的说法,Gitleaks 最大的优势是它的配置系统,可以编写自己的规则。对 FDE 而言,当客户使用默认规则识别不了的内部令牌格式时,这一点就派上用场了。

假设客户的令牌由 acme_ 加 32 个字符组成。一个最简的 .gitleaks.toml 保留默认规则集,只新增一条规则:

[extend]
useDefault = true

[[rules]]
id = "acme-internal-token"
description = "客户内部令牌"
regex = '''acme_[a-z0-9]{32}'''
keywords = ["acme_"]

然后运行 gitleaks git -v --config .gitleaks.toml。正式使用前,先在一个放了假令牌的临时仓库里测试规则,确认正则能匹配到你想要的内容。

要从源头拦截泄露,可以把 Gitleaks 作为 pre-commit 钩子运行:把示例脚本 pre-commit.py 复制到 .git/hooks/ 目录即可。在团队层面,项目提供了一个 GitHub Action,用于扫描拉取请求和提交。pre-commit 钩子保护你自己的机器,Action 保护仓库里的其他所有人。

这套组合也值得写进简历。像“在向客户交接仓库前,搭建了 pre-commit 和 CI 密钥扫描,并为内部令牌编写了自定义规则”这样一句话,能让招聘经理看到:你把交出去的仓库视为带有风险的资产,而不只是一堆代码。

选工具前要知道的局限

项目当前的 README 宣布 Gitleaks 已功能完备:不再接受新功能,今后的版本只包含安全修复。2026 年 3 月,Rice 推出了 Betterleaks,可直接替代 Gitleaks,现有的 CLI 参数和配置文件无需改动即可使用。

所以今天投入的精力不会白费。上面的扫描命令、基线和规则文件都能直接迁移到 Betterleaks。如果客户从零开始,值得问一句他们想统一使用哪个工具。

交接仓库,就是交接它的过去。交接前跑一次 gitleaks git -v,远比事后接到客户安全团队的电话划算。

这篇文章对你有帮助吗?

6 个信源
路线图上的下一篇 · 阶段 5: 部署上线客户的云账单,应该先出现在 PR 里Infracost 在部署前于 CI 中估算成本变化,但只有设为必需状态检查,才能阻止合并。