2.5 KiB
2.5 KiB
Gitleaks 使用笔记
Gitleaks 是扫描疑似密钥的命令行工具，不需要部署 Docker。它通过规则匹配识别令牌、云平台凭据、私钥等；命中不代表凭据仍有效，未命中也不代表绝对安全。
Linux 安装
从 官方 Releases 下载对应架构的 Linux 压缩包：uname -m 为 x86_64 时选 linux_x64，为 aarch64 时选 linux_arm64。核对下载页提供的校验和，解压后安装：
sudo install -m 0755 gitleaks /usr/local/bin/gitleaks
gitleaks version
提交前自动检测
在目标 Git 仓库中检查 .git/hooks/pre-commit 是否已存在；若存在，将下面的检测命令并入现有脚本，不要覆盖。新建时内容为：
#!/bin/sh
gitleaks git --staged --redact --verbose .
然后运行 chmod +x .git/hooks/pre-commit。正常流程是 git add <文件> → git commit -m "提交说明"：Git 自动执行 hook；发现疑似密钥时命令返回非零状态，提交被阻止。--redact 避免在终端输出完整密钥。若设置了 core.hooksPath，应在指定的 hook 目录配置，而非 .git/hooks/。
手动扫描与测试
在仓库目录下运行：
| 命令 | 检查范围 |
|---|---|
gitleaks git --staged --redact --verbose . |
本次暂存变更的新增内容，与上面的 hook 一致 |
gitleaks git --redact . |
Git 提交历史中的新增内容 |
gitleaks dir --redact . |
当前目录中的文件，包括尚未暂存的文件 |
手动运行第一条命令可以先确认工具正常工作；没有命中通常返回 0，发现疑似密钥或扫描出错返回 1。普通文件修改不会因为装了 Gitleaks 就被阻止。要验证自动拦截，只用无效的模拟令牌测试，并先确认手动扫描能命中；随后运行普通的 git commit，预期 hook 阻止提交。若扫描未命中，别贸然提交测试令牌；若意外提交成功，不要推送，先检查 hook 是否执行及暂存内容。
注意事项
--staged扫描的是暂存差异中的新增内容，不等于检查每个暂存文件的全部历史内容；未暂存的修改也不在其中。- 本地 hook 通常只对当前仓库有效，且可被
git commit --no-verify绕过；重要项目还应在 CI 中扫描。 - 发现真实凭据时，先从暂存内容中移除并修复；若已推送或暴露，应尽快轮换凭据。误报可审慎使用 allowlist 或
.gitleaksignore，不要直接忽略未知来源的命中。