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

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

原文: https://fdetimes.net/zh/tools/gitleaks-scan-git-history-secrets/

在第 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`，说明写法已经过时。

**要点:** 从文件中删掉一行，并不会把它从 Git 历史中删掉。

## 设想一次交接

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

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

```bash
gitleaks git -v
```

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

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

## 发现了密钥，先做什么？

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

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

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

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

## 交接前的三个常见错误

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

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

## 清理之后，保持仓库干净

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

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

```bash
# 首次运行：将现有的全部发现保存为基线
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` 保留默认规则集，只新增一条规则：

```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`，远比事后接到客户安全团队的电话划算。

**本周动手试试:**

- 在下一个要交接的仓库上运行 gitleaks git -v，记录每条发现及其处理状态
- 用首次扫描结果建立基线，再加上 --baseline-path 重新运行，确认只出现新的泄露
- 把 Gitleaks 的示例脚本 pre-commit.py 复制到你正在开发的仓库的 .git/hooks/ 目录中

## 信源

- [GitHub - gitleaks/gitleaks](https://github.com/gitleaks/gitleaks)

- [gitleaks README (master)](https://raw.githubusercontent.com/gitleaks/gitleaks/master/README.md)

- [Gitleaks](https://gitleaks.io)

- [Gitleaks: Open-source solution for detecting secrets in your code](https://www.helpnetsecurity.com/2024/06/27/gitleaks-open-source-solution-detecting-secrets-in-code/)

- [Betterleaks: Open-source secrets scanner](https://www.helpnetsecurity.com/2026/03/19/betterleaks-open-source-secrets-scanner/)

- [Removing sensitive data from a repository - GitHub Docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)
