使用 TruffleHog 扫描代码仓库中的敏感信息

Feb 6, 2026 · 2 min read

不小心将 API 密钥提交到代码仓库?你并不孤单。每天都有成千上万的凭证通过 git 泄露——即使开发者认为已经删除了它们,这些敏感信息往往仍然存在于提交历史中。TruffleHog 敏感信息扫描提供了一种直接的方法,可以在代码仓库中的 API 密钥暴露成为安全事件之前检测到它们。

本文介绍 TruffleHog 的工作原理、如何在本地和 CI 环境中扫描 git 仓库中的敏感信息,以及如何解读扫描结果以便有效地确定修复优先级。

核心要点

TruffleHog 扫描整个 git 历史记录,而不仅仅是当前文件,能够发现隐藏在旧提交中的敏感信息
已验证的发现表示实时可利用的凭证,需要立即轮换
将 TruffleHog 集成到 CI 流水线可以在凭证泄露到生产环境之前阻止它们
当发现敏感信息时,首先轮换凭证,然后使用 BFG Repo-Cleaner 或 git-filter-repo 等工具从历史记录中删除

为什么敏感信息会出现在 Git 中

开发者的工作节奏很快。在调试过程中数据库密码被硬编码。AWS 密钥出现在配置文件中。这些错误时常发生,而 git 的不可变历史记录意味着即使是”已删除”的敏感信息仍然会保留在旧提交中。

风险是真实存在的:自动化机器人持续扫描公共代码仓库,暴露的凭证可能在推送后几分钟内就被利用。即使是私有仓库也不安全——单个被攻陷的开发者账户或配置错误的访问控制都可能暴露所有内容。

TruffleHog 如何检测敏感信息

TruffleHog 不是一个简单的 grep 工具。它使用基于检测器的扫描方式,内置了数百种针对特定凭证类型的模式:AWS 密钥、GitHub 令牌、Stripe API 密钥、数据库连接字符串等。

检测方法结合了:

模式匹配:针对已知敏感信息格式调优的正则表达式检测器
上下文分析:检查周围的代码以减少噪音
可选验证:针对实际 API 测试凭证以确认其是否处于活动状态

这种分层方法意味着比仅基于熵的扫描器产生更少的误报。当 TruffleHog 标记某些内容时,通常值得调查。

扫描本地代码仓库

要在本地扫描 git 仓库中的敏感信息,将 TruffleHog 指向你的仓库:

trufflehog git file://.

这会扫描整个 git 历史记录——不仅仅是当前工作树。隐藏在旧提交中的敏感信息会与最近的一起被发现。

为了在开发过程中获得更快的反馈,你可以将扫描范围限制在最近的提交或特定分支。这使得在推送更改之前运行扫描变得实用。

理解已验证与未验证结果

TruffleHog 区分两种发现类型:

已验证:凭证已针对其 API 进行测试并确认处于活动状态
未验证:模式匹配已知的敏感信息格式,但无法进行验证或未尝试验证

已验证的发现需要立即采取行动——这些是可以立即被利用的实时凭证。未验证的发现仍然值得审查,但在分类大量结果集时,你可以将它们的优先级降低。

要将输出过滤为仅显示已验证的结果:

trufflehog git file://. --only-verified

将 TruffleHog GitHub Action 集成到 CI 中

手动运行扫描可以发现问题,但自动化可以预防问题。TruffleHog GitHub Action 直接集成到你的 CI 流水线中,扫描每个拉取请求和推送。

基本的工作流配置会扫描传入的更改,如果检测到敏感信息则构建失败。这创建了一个门控机制,在凭证泄露到达主分支之前——或者更糟糕的是到达生产环境之前——阻止它们。

该 Action 支持仅扫描差异(对 PR 检查更快)或完整的仓库历史记录(对定期审计有用)。大多数团队在每个 PR 上运行轻量级差异扫描,并每周安排一次全面的历史记录扫描。

超越 Git:其他扫描目标

虽然本文重点关注 git 工作流,但 TruffleHog 支持其他目标:文件系统、S3 存储桶和 Docker 镜像。对于大多数开发者来说,git 和文件系统扫描器涵盖了典型的使用场景。随着基础设施的增长,更广泛的功能变得相关。

发现敏感信息后该怎么办

发现敏感信息只是第一步。响应更重要:

立即轮换凭证——假设它已被泄露
使用 BFG Repo-Cleaner 或 git-filter-repo 等工具从 git 历史记录中删除它
审计受影响服务的访问日志以检查是否有未经授权的使用
更新你的工作流程以防止将来在源代码控制中泄露凭证

简单地删除文件并再次提交没有帮助。敏感信息会一直保留在历史记录中,直到你重写它。

结论

TruffleHog 最好作为预防性控制措施,而不仅仅是审计工具。在 CI 中尽早运行它,理想情况下在每个拉取请求上运行。越早发现泄露的凭证,影响范围就越小。

将自动化扫描与良好的习惯相结合:使用环境变量存储敏感信息,将敏感模式添加到 .gitignore,并考虑使用 pre-commit 钩子进行本地强制执行。

敏感信息扫描不会消除所有风险,但它大大缩短了从错误到发现之间的时间窗口。这通常是有惊无险和真正事件之间的区别。

常见问题

TruffleHog 默认扫描整个 git 历史记录,而不仅仅是当前工作树。这意味着即使在后续提交中删除了敏感信息,隐藏在旧提交中的敏感信息也会被发现。Git 的不可变历史记录保留了所有内容,因此全面扫描对于查找所有暴露的凭证至关重要。

已验证的发现意味着 TruffleHog 针对其实际 API 测试了凭证并确认它仍然处于活动状态。未验证的发现匹配已知的敏感信息模式但未经过验证。优先处理已验证的发现以立即采取行动,因为它们代表实时可利用的凭证。

删除文件并提交不会从历史记录中删除敏感信息。使用 BFG Repo-Cleaner 或 git-filter-repo 等工具重写 git 历史记录并从所有提交中清除凭证。重写后,强制推送到远程仓库,并让所有协作者重新克隆仓库。

可以,TruffleHog 可以作为 pre-commit 钩子运行以进行本地强制执行。这会在敏感信息到达远程仓库之前捕获它们。将 pre-commit 钩子与 CI 集成相结合以实现纵深防御,确保敏感信息在本地和流水线中都被阻止。

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.