Gitleaks Secret Scanning

验证：未记录
适用版本
未记录
验证范围
尚未登记验证记录。
本文缩写（英文全称与中文含义）
缩写 英文全称／名称 中文含义
API Application Programming Interface 应用程序编程接口
CI Continuous Integration 持续集成
CLI Command-Line Interface 命令行接口
CPU Central Processing Unit 中央处理器
CSV Comma-Separated Values 逗号分隔值格式
JSON JavaScript Object Notation 一种结构化数据格式
OS Operating System 操作系统
PR Pull Request 代码合并请求
SARIF Static Analysis Results Interchange Format 静态分析结果交换格式
SHA Secure Hash Algorithm 安全散列算法
SHA256 Secure Hash Algorithm 256-bit 256 位安全散列算法，常写为 SHA-256
TOML Tom’s Obvious, Minimal Language 一种配置文件格式

1. 用途#

Gitleaks 检查 Git 提交、文件和标准输入中的疑似密码、API key、token、私钥等。它依靠规则识别，不验证凭据是否仍有效，也不替代撤销和轮换。

本文示例固定 v8.30.1，使用 git、dir、stdin；旧教程中的 detect、protect 已弃用。官方当前说明项目已进入功能完成状态，后续主要提供安全修复。项目说明

2. 安装#

macOS：

brew install gitleaks
gitleaks version

Homebrew 安装其当前版本；团队 CI 和 hook 应固定经过验证的版本。其他系统从 Releases 下载对应 OS/CPU 的二进制，并校验 checksum。

3. 常用扫描#

在目标仓库根目录运行：

# 当前 checkout 的 Git 历史。
gitleaks git --redact .

# 本地所有可达 refs 的历史；不会自动获取服务器上的其他仓库或隐藏 refs。
gitleaks git --redact --log-opts='--all' .

# 当前文件，包括未提交内容；不扫描已经从工作区删除的历史内容。
gitleaks dir --redact .

# git add 后检查暂存区。
gitleaks git --pre-commit --staged --redact .

# 标准输入，例如生成的配置；用文件输入避免把真实密钥写入 shell history。
gitleaks stdin --redact < generated-config.txt

git 与 dir 覆盖范围不同，首次接入建议两者都跑；.gitignore 不是所有扫描模式通用的安全边界。子模块、外部制品和其他仓库需单独纳入扫描。

比较当前分支相对主分支新增的提交：

git fetch origin main
GITLEAKS_BASE=$(git merge-base origin/main HEAD)
gitleaks git --redact --log-opts="$GITLEAKS_BASE..HEAD" .

这里是提交范围扫描；分支名按项目调整，浅克隆需先补齐所需历史。最终文件不再包含密钥，也可能在新增提交历史中被检测到。

4. 报告与退出码#

报告放在仓库外，避免被误提交或再次扫描：

GITLEAKS_REPORT_DIR=$(mktemp -d)
gitleaks git --redact --report-format json --report-path "$GITLEAKS_REPORT_DIR/findings.json" .

支持 JSON、SARIF、CSV、JUnit 等报告格式。默认发现泄露时返回 1，无发现返回 0；非零也可能来自执行错误，要结合错误信息判断，不能统一当作“发现密钥”。

排查优先看 RuleID、File、StartLine、Commit、Fingerprint。启用 --redact，仍按敏感数据管理报告；文件路径、提交信息等也可能敏感。不要在 CI 中用 || true 或 --exit-code 0 隐藏失败。

5. 项目配置与误报#

仓库根目录 .gitleaks.toml 的最小配置：

title = "Repository secret scanning"

[extend]
useDefault = true

自定义配置需显式继承默认规则，否则可能只剩自定义检测。可用 --config .gitleaks.toml 指定配置路径。

方式 适用场景 要求
修正示例内容 文档、测试样例看起来像真实密钥 优先改用明显占位符
.gitleaksignore 个别已确认误报 复制报告里的准确 Fingerprint，记录原因
gitleaks:allow 注释 单行明确的测试样例 仅用于已确认无效的内容，需代码审查
TOML allowlist 稳定、狭窄的规则例外 同时限定路径与内容，避免整目录放行
Baseline 分阶段治理历史问题 建立整改账本，不代表旧凭据已安全

精确 allowlist 示例，追加到上面的 TOML：

[[allowlists]]
description = "Documented invalid fixture only"
condition = "AND"
paths = ['''^testdata/invalid-token\.txt$''']
regexTarget = "secret"
regexes = ['''^EXAMPLE_NOT_A_REAL_TOKEN$''']

AND 要求路径和内容都符合。不要整仓排除 docs/、.env、测试目录或 Terraform 文件。配置格式

6. 历史基线#

先审查扫描报告并处理真实密钥，再把批准保留的历史发现作为 baseline。以下两个命令使用同一版本、规则、扫描范围和脱敏选项：

GITLEAKS_BASELINE_DIR=$(mktemp -d)

# 若存在发现，此命令返回 1；先审查，不要自动吞掉所有错误。
gitleaks git --redact --log-opts='--all' --report-format json --report-path "$GITLEAKS_BASELINE_DIR/baseline.json" .

# 审批 baseline 后，只报告其中没有的新发现。
gitleaks git --redact --log-opts='--all' --baseline-path "$GITLEAKS_BASELINE_DIR/baseline.json" --report-format json --report-path "$GITLEAKS_BASELINE_DIR/new-findings.json" .

基线受控保存并指定负责人、处理期限。不要每次 CI 自动重建 baseline，否则新泄露会被一并忽略；改变规则、版本或重写历史后重新审核匹配结果。

7. 本地 Pre-commit#

使用 pre-commit 管理器，避免覆盖仓库已有 hook。安装工具后，将以下条目合并进 .pre-commit-config.yaml：

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1
    hooks:
      - id: gitleaks-system
brew install pre-commit
pre-commit install

# 暂存修改后检查；本 hook 使用本机安装的 gitleaks。
pre-commit run gitleaks-system

gitleaks-system 需要 PATH 中已有 Gitleaks，hook 的 rev 不会替你固定本机二进制版本。若希望 pre-commit 构建工具，可改用官方 id: gitleaks，需满足对应 Go 工具链要求。

该 hook 扫描暂存 diff，不等于完整历史扫描；pre-commit run --all-files 也不应当作全历史审计。本地 hook 可以被跳过，CI 仍需强制执行。官方 hook 定义

8. GitHub Actions#

保存为 .github/workflows/gitleaks.yml。示例在 GitHub 托管 Linux x64 runner 上下载固定版 CLI，校验 SHA256，并扫描 checkout 的完整可达 refs；不执行待检查仓库的构建脚本。

name: Gitleaks

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Install Gitleaks
        env:
          GITLEAKS_VERSION: 8.30.1
        run: |
          set -euo pipefail
          install_dir="$RUNNER_TEMP/gitleaks-tool"
          mkdir -p "$install_dir"
          cd "$install_dir"
          archive="gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
          checksums="gitleaks_${GITLEAKS_VERSION}_checksums.txt"
          release_url="https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}"
          curl -fsSLO "$release_url/$archive"
          curl -fsSLO "$release_url/$checksums"
          awk -v name="$archive" '$2 == name' "$checksums" > selected-checksum.txt
          test -s selected-checksum.txt
          sha256sum -c selected-checksum.txt
          tar -xzf "$archive" gitleaks
          echo "$install_dir" >> "$GITHUB_PATH"

      - name: Scan Git history
        run: gitleaks git --redact --log-opts='--all' .

团队将 scan 配成必需状态检查；生产工作流可进一步把 Action 固定到审核过的完整 commit SHA。为 .gitleaks.toml、.gitleaksignore、baseline 和 workflow 设置 CODEOWNERS，避免同一个 PR 静默放宽扫描策略。

不要用 pull_request_target 搭配执行不可信 PR 代码。此 CLI 流程不需要 Gitleaks Action license；如果改用 gitleaks/gitleaks-action，组织仓库需按该 Action 的许可要求配置 GITLEAKS_LICENSE，不要和开源 CLI 的许可混淆。官方 Action

9. Hands-on：验证能否拦截#

使用临时目录与专用测试规则，不使用真实凭据，也不向当前仓库添加假密钥：

GITLEAKS_LAB_DIR=$(mktemp -d)
cd "$GITLEAKS_LAB_DIR"

cat > lab.toml <<'EOF'
title = "Gitleaks lab"
[[rules]]
id = "lab-token"
description = "Synthetic token for testing only"
regex = '''LAB_TOKEN_[0-9]{8}'''
EOF

printf '%s\n' 'LAB_TOKEN_12345678' > sample.txt
gitleaks dir --config lab.toml --redact .

预期退出码 1，命中 lab-token。将测试文件改为普通文本后重跑：

printf '%s\n' 'ordinary text' > sample.txt
gitleaks dir --config lab.toml --redact .

预期退出码 0。实验配置只验证检测链路，不作为生产规则集；实验完成后返回原目录并删除该临时实验目录。

10. 发现真实密钥后的处理#

  1. 立即撤销或轮换凭据，核查权限范围与访问记录。
  2. 从代码、配置和产物中移除，改用 Secrets Manager、运行时注入或短期身份凭据。
  3. 检查 Git 历史、PR、CI 日志、报告和发布产物；需要重写历史时协调团队与分支保护。
  4. 重跑历史与文件扫描，确认新凭据没有再次进入仓库。

删除最新文件、添加 ignore 或建立 baseline 都不会让已泄露的凭据失效。

首次配置与跨平台文件变更 Forward

搜索文档

输入关键词，搜索所有文档。

↑ ↓ 选择 · Enter 打开 · Esc 关闭