gitleaks 安装与部署

安装与部署

装法按环境选一条即可，装完用 gitleaks version 确认。

macOS / Linux 用 Homebrew：
```
brew install gitleaks
gitleaks version
```
用 Go 直接安装（需要有 Go 工具链，模块路径中的 v8 是主版本号，安装命令以官方 README 为准）：
```
go install github.com/gitleaks/gitleaks/v8@latest
```
用 Docker 跑，适合不想在 runner 上装二进制的场景。注意必须挂载仓库目录并设置工作目录：
```
docker run --rm -v "$(pwd):/repo" -w /repo \
  zricethezav/gitleaks:latest git /repo --verbose
```
下载官方二进制，解压后放进 PATH。具体版本号与文件名以官方 Release 页面为准：
```
tar -xzf gitleaks_*_linux_x64.tar.gz
sudo mv gitleaks /usr/local/bin/
gitleaks version
```
全历史扫描仓库。这是排查存量泄露的主力命令。注意 --log-opts="--all" 让 git log 遍历全部分支：
```
# 当前工作目录所在仓库，扫全部历史
gitleaks git --log-opts="--all" --report-format json --report-path leaks.json

# 指定仓库路径
gitleaks git /path/to/repo --log-opts="--all" --redact

# 只扫工作区目录，不读 git 历史
gitleaks dir . --no-git
```
需要说明的是，gitleaks v8 在较新版本里把命令名从 detect 改成了 git，把目录扫描从 detect --no-git 拆成了 dir，protect 也有对应变化。旧版命令名与新版存在差异，实际使用时以官方文档和你安装的版本为准——写本文时这两种写法在不同版本上都还能见到。

配置 pre-commit hook，在提交真正落地之前拦住。用官方的 .pre-commit-config.yaml 最省事：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0   # 版本号以官方仓库 tag 为准
    hooks:
      - id: gitleaks

不想引入 pre-commit 框架的话，直接写一个 shell hook 也可以：

# .git/hooks/pre-commit
#!/bin/sh
gitleaks git --staged --redact --verbose
status=$?
if [ $status -ne 0 ]; then
  echo "检测到疑似密钥，提交已中止。请移除后重试。"
  exit 1
fi

CI 集成。GitHub Actions 与 GitLab CI 各一段，关键是把 git 历史拉全，否则扫不全：

# GitHub Actions
- uses: actions/checkout@v4
  with:
    fetch-depth: 0        # 必须，浅克隆会导致历史扫不全
- name: gitleaks
  run: gitleaks git --log-opts="--all" --redact \
       --report-format sarif --report-path results.sarif

# GitLab CI
gitleaks:
  image:
    name: zricethezav/gitleaks:latest
    entrypoint: [""]
  variables:
    GIT_DEPTH: "0"        # 全历史，覆盖默认的浅克隆
  script:
    - gitleaks git --log-opts="--all" --redact --verbose
        --report-format sarif --report-path gitleaks.sarif

常见报错与排查

现象	原因	处理
`command not found`	二进制不在 PATH，或 Docker 里命令名写成了 `gitleaks git` 而镜像入口点不对	确认安装路径；Docker 场景加 `entrypoint: [""]`
输出 `no leaks found`	正常结果，退出码为 0	没有发现泄露不代表一定安全，只代表当前规则集没命中
扫描大仓库超时	全历史提交数太多	用 `--log-opts` 限定时间范围（如 `--since=2024-01-01`），或按目录分批扫
历史扫不全	CI 默认浅克隆，只有最近一次提交	GitHub 设 `fetch-depth: 0`，GitLab 设 `GIT_DEPTH: "0"`
退出码非零但没看到报告	报告写进了文件，没打印到终端	加 `--verbose` 打印明细，或查看 `--report-path` 指定的文件
误报太多	规则阈值太松，或测试 fixture 被当成真实密钥	收紧规则、加 allowlist 排除测试路径，不要一刀切降低全局灵敏度

安装与部署

装法按环境选一条即可，装完用 gitleaks version 确认。

macOS / Linux 用 Homebrew：

brew install gitleaks
gitleaks version

用 Go 直接安装（需要有 Go 工具链，模块路径中的 v8 是主版本号，安装命令以官方 README 为准）：

go install github.com/gitleaks/gitleaks/v8@latest

用 Docker 跑，适合不想在 runner 上装二进制的场景。注意必须挂载仓库目录并设置工作目录：

docker run --rm -v "$(pwd):/repo" -w /repo \
  zricethezav/gitleaks:latest git /repo --verbose

下载官方二进制，解压后放进 PATH。具体版本号与文件名以官方 Release 页面为准：

tar -xzf gitleaks_*_linux_x64.tar.gz
sudo mv gitleaks /usr/local/bin/
gitleaks version

全历史扫描仓库。这是排查存量泄露的主力命令。注意 --log-opts="--all" 让 git log 遍历全部分支：

# 当前工作目录所在仓库，扫全部历史
gitleaks git --log-opts="--all" --report-format json --report-path leaks.json

# 指定仓库路径
gitleaks git /path/to/repo --log-opts="--all" --redact

# 只扫工作区目录，不读 git 历史
gitleaks dir . --no-git

需要说明的是，gitleaks v8 在较新版本里把命令名从 detect 改成了 git，把目录扫描从 detect --no-git 拆成了 dir，protect 也有对应变化。旧版命令名与新版存在差异，实际使用时以官方文档和你安装的版本为准——写本文时这两种写法在不同版本上都还能见到。

配置 pre-commit hook，在提交真正落地之前拦住。用官方的 .pre-commit-config.yaml 最省事：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0   # 版本号以官方仓库 tag 为准
    hooks:
      - id: gitleaks

不想引入 pre-commit 框架的话，直接写一个 shell hook 也可以：

# .git/hooks/pre-commit
#!/bin/sh
gitleaks git --staged --redact --verbose
status=$?
if [ $status -ne 0 ]; then
  echo "检测到疑似密钥，提交已中止。请移除后重试。"
  exit 1
fi

CI 集成。GitHub Actions 与 GitLab CI 各一段，关键是把 git 历史拉全，否则扫不全：

# GitHub Actions
- uses: actions/checkout@v4
  with:
    fetch-depth: 0        # 必须，浅克隆会导致历史扫不全
- name: gitleaks
  run: gitleaks git --log-opts="--all" --redact \
       --report-format sarif --report-path results.sarif

# GitLab CI
gitleaks:
  image:
    name: zricethezav/gitleaks:latest
    entrypoint: [""]
  variables:
    GIT_DEPTH: "0"        # 全历史，覆盖默认的浅克隆
  script:
    - gitleaks git --log-opts="--all" --redact --verbose
        --report-format sarif --report-path gitleaks.sarif

常见报错与排查

现象

原因

处理

command not found

二进制不在 PATH，或 Docker 里命令名写成了 gitleaks git 而镜像入口点不对

确认安装路径；Docker 场景加 entrypoint: [""]

输出 no leaks found

正常结果，退出码为 0

没有发现泄露不代表一定安全，只代表当前规则集没命中

扫描大仓库超时

全历史提交数太多

用 --log-opts 限定时间范围（如 --since=2024-01-01），或按目录分批扫

历史扫不全

CI 默认浅克隆，只有最近一次提交

GitHub 设 fetch-depth: 0，GitLab 设 GIT_DEPTH: "0"

退出码非零但没看到报告

报告写进了文件，没打印到终端

加 --verbose 打印明细，或查看 --report-path 指定的文件

误报太多

规则阈值太松，或测试 fixture 被当成真实密钥

收紧规则、加 allowlist 排除测试路径，不要一刀切降低全局灵敏度

gitleaks 安装与部署

安装与部署

常见报错与排查

OK 基地：让 AI 技术与人才成长真正连接

gitleaks 安装与部署

安装与部署

常见报错与排查

OK 基地：让 AI 技术与人才成长真正连接