42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
# Gitleaks 使用笔记
|
|
|
|
Gitleaks 是扫描疑似密钥的命令行工具，不需要部署 Docker。它通过规则匹配识别令牌、云平台凭据、私钥等；命中不代表凭据仍有效，未命中也不代表绝对安全。
|
|
|
|
## Linux 安装
|
|
|
|
从 [官方 Releases](https://github.com/gitleaks/gitleaks/releases/latest) 下载对应架构的 Linux 压缩包：`uname -m` 为 `x86_64` 时选 `linux_x64`，为 `aarch64` 时选 `linux_arm64`。核对下载页提供的校验和，解压后安装：
|
|
|
|
```sh
|
|
sudo install -m 0755 gitleaks /usr/local/bin/gitleaks
|
|
gitleaks version
|
|
```
|
|
|
|
## 提交前自动检测
|
|
|
|
在目标 Git 仓库中检查 `.git/hooks/pre-commit` 是否已存在；若存在，将下面的检测命令并入现有脚本，**不要覆盖**。新建时内容为：
|
|
|
|
```sh
|
|
#!/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`，不要直接忽略未知来源的命中。
|