Gitleaks 代码仓库密钥泄露扫描

FreeGuideOnline 最新 2026-07-10

bash brew install gitleaks


**Linux 用户**（通过脚本安装）：

```bash
# 下载并执行官方安装脚本
curl -sSfL https://git.io/install-gitleaks | sh -s -- -b /usr/local/bin

Windows 用户：

使用 scoop 安装：

scoop install gitleaks

或直接前往 GitHub Releases 下载对应架构的可执行文件。

使用 Docker 运行

如果你的开发环境已安装 Docker，可以直接使用官方镜像，无需本地安装：

docker run --rm -v $(pwd):/path zricethezav/gitleaks detect -v

在 Windows 环境下，请将 $(pwd) 替换为绝对路径，例如 -v C:\project:/path。

从源码编译（需要 Go 1.18+）

git clone https://github.com/gitleaks/gitleaks.git
cd gitleaks
make build

基础扫描命令

扫描当前仓库

在本地 Git 仓库目录中执行：

gitleaks detect

该命令会扫描仓库的完整历史、暂存区以及工作目录中的未跟踪文件。扫描结束后会输出发现泄露的路径、规则名称、匹配内容片段及 commit 信息。

扫描指定路径

如果只是扫描当前目录（不包含历史），可使用 --source 指定目录，并配合 --no-git 跳过 Git 历史：

gitleaks detect --source ./configs --no-git

这对于扫描配置文件目录或代码片段十分有用。

生成 JSON 格式报告

将结果导出为 JSON 文件，便于机器处理和集成：

gitleaks detect -f json -r report.json

忽略已被标记的密钥

有时早期 commit 已经标注意为“测试假凭证”或已撤销的密钥，但仍会触发告警。可通过在对应行添加注释 gitleaks:allow 令其跳过，或使用 .gitleaksignore 文件管理。

自定义规则配置

Gitleaks 使用 TOML 格式的配置文件定义检测规则，默认调用内置规则集。当需要添加公司内部密钥格式或放宽某些误报时，可创建自定义配置。

创建配置文件

生成默认配置模板，方便在此基础上修改：

gitleaks config set

这将在当前目录生成 .gitleaks.toml 文件，内容包含默认规则。

配置文件结构

一个典型的规则定义如下：

[[rules]]
id = "my-internal-api-key"
description = "Internal API key"
regex = '''(?i)(myapp_api_key|api_key)\s*=\s*[a-z0-9]{32}'''
keywords = ["myapp_api_key", "api_key"]

id：规则唯一标识
description：规则说明
regex：正则表达式，用于匹配泄露模式
keywords：辅助关键字，Gitleaks 会先基于关键字快速过滤，减少误报率

指定自定义配置文件扫描

gitleaks detect --config .gitleaks.toml

也可以在全局位置创建同名文件，Gitleaks 会自动加载。

集成到 CI/CD 管道

GitHub Actions 集成

创建 .github/workflows/gitleaks.yml：

name: Secret Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2
        with:
          config: .gitleaks.toml

fetch-depth: 0 确保拉取完整历史，否则无法扫描历史 commit。

GitLab CI 集成

在 .gitlab-ci.yml 中添加：

gitleaks:
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks detect -v --config .gitleaks.toml
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
    - if: $CI_MERGE_REQUEST_IID

通用流水线建议

将 Gitleaks 扫描作为 pre-commit hook，防止包含密钥的代码进入版本库。
在 CI 中配置为阻断性检查，发现有泄露时直接标记流水线失败。
定期对仓库执行全量扫描，尤其当规则库更新时重新扫描历史。
将扫描报告归档，便于审计和趋势分析。

忽略与误报处理

使用 `.gitleaksignore` 文件

在仓库根目录创建 .gitleaksignore，按以下格式添加需要忽略的发现：

commit_sha:path:line_number:rule_id

例如：

a1b2c3d4:config.go:20:generic-api-key

该记录可以通过 gitleaks detect --log-opts="--no-merges" 等命令的输出来构建，也可以从 JSON 报告中提取。

在代码内添加忽略标记

对于特定行，可在行末添加注释（支持的语言如 Go、Python、JavaScript 等）：

var dbPassword = "fake-password" // gitleaks:allow

默认情况下，Gitleaks 会识别这些注释并跳过该匹配。

调整规则阈值与白名单

在自定义配置中，可设置规则的 allowlist 进行更细粒度的控制：

[[rules]]
id = "generic-api-key"
regex = '''[a-z0-9]{32}'''
allowlist = { paths = ['''test/.*''', '''mock/.*'''] }

paths 使用正则表达式指定忽略的文件或目录路径。

高级用法与技巧

扫描前保护与预扫描

gitleaks protect 命令能扫描暂存区，适合作为 pre-commit hook 的基础。在 .git/hooks/pre-commit 中添加：

#!/bin/sh
gitleaks protect -v --staged

在提交前扫描，可避免敏感信息进入历史，是成本更低的防护方式。

定期批量扫描多个仓库

对于组织内的大量仓库，可编写脚本批量执行：

for repo in $(cat repos.txt); do
  git clone $repo
  cd $(basename $repo)
  gitleaks detect -f json -r ../reports/$(basename $repo).json
  cd ..
done

结合熵检测增强未知密钥发现

Gitleaks 内置了基于 Shannon 熵的检测，能够发现无明显模式的高熵字符串（如随机生成的令牌）。默认阈值通常为 4.0，可在规则中调整：

[allowlist]
description = "entropy suppression"

[[rules]]
id = "entropy-rule"
regex = '''.*'''
entropy = 4.5
keywords = ["secret", "password"]