zricethezav/gitleaks

Gitleaks 镜像文档

Gitleaks 是一款静态应用安全测试（SAST）工具，用于检测 Git 仓库中硬编码的密钥，如密码、API 密钥和令牌。它是一款易于使用的一体化解决方案，可检测代码中过去或现在存在的密钥。

快速开始

Gitleaks 可通过 Docker 安装使用，也可通过 Homebrew、源码编译等方式安装。以下是 Docker 部署方案示例：

Docker 安装

DockerHub

bash
docker pull zricethezav/gitleaks:latest
docker run -v ${本地待扫描文件夹路径}:/path zricethezav/gitleaks:latest [COMMAND] --source="/path" [OPTIONS]

ghrc.io

bash
docker pull ghcr.io/zricethezav/gitleaks:latest
docker run -v ${本地待扫描文件夹路径}:/path zricethezav/gitleaks:latest [COMMAND] --source="/path" [OPTIONS]

使用方法

Usage:
  gitleaks [command]

可用命令:
  completion  为指定 shell 生成自动补全脚本
  detect      检测代码中的密钥
  help        查看命令帮助
  protect     保护代码中的密钥
  version     显示 Gitleaks 版本

标志:
  -c, --config string          配置文件路径
                               优先级顺序:
                               1. --config/-c
                               2. (--source/-s)/.gitleaks.toml
                               若未设置 --config/-c 且不存在 .gitleaks.toml/gitleaks.toml，
                               则 .gitleaks.toml 将写入 (--source/-s)/.gitleaks.toml 供后续使用
      --exit-code string       检测到密钥时的退出码 (默认: 1)
  -h, --help                   查看帮助
  -l, --log-level string       日志级别 (debug, info, warn, error, fatal) (默认 "info")
      --redact                 从日志和标准输出中脱敏密钥
  -f, --report-format string   输出格式 (json, csv, sarif)
  -r, --report-path string     报告文件路径
  -s, --source string          源代码路径 (Git 仓库、目录、文件)
  -v, --verbose                显示详细扫描输出

使用 "gitleaks [command] --help" 查看命令详细信息。

主要命令

• detect: 用于扫描仓库、目录和文件，适用于开发者机器和 CI 环境。扫描 Git 仓库时，Gitleaks 会解析 git log -p 的输出；可使用 --no-git 选项扫描非 Git 文件/目录。
• protect: 用于检测 Git 仓库中未提交的更改，遵循“安全左移”原则，适用于开发者机器。扫描时解析 git diff 输出，--staged 标志可检查已 git add 的更改，适合作为预提交钩子使用。

验证检测结果

可使用 git log 命令验证 Gitleaks 检测到的密钥。示例输出:

json
{
    "Description": "AWS",
    "StartLine": 37,
    "EndLine": 37,
    "StartColumn": 19,
    "EndColumn": 38,
    "Context": "\t\t\"aws_secret= \"AKIAIMNOJVGFDXXXE4OA\"\":          true,",
    "Secret": "AKIAIMNOJVGFDXXXE4OA",
    "File": "checks_test.go",
    "Commit": "ec2fc9d6cb0954fb3b57201cf6133c48d8ca0d29",
    "Entropy": 0,
    "Author": "zricethezav",
    "Email": "thisispublicanyways@gmail.com",
    "Date": "2018-01-28 17:39:00 -0500 -0500",
    "Message": "[update] entropy check",
    "Tags": [],
    "RuleID": "aws-access-token"
}

验证命令格式:

bash
git log -L {StartLine,EndLine}:{File} {Commit}

示例:

bash
git log -L 37,37:checks_test.go ec2fc9d6cb0954fb3b57201cf6133c48d8ca0d29

预提交钩子

将示例 pre-commit.py 脚本复制到仓库的 .git/hooks/ 目录，即可将 Gitleaks 作为预提交钩子运行。

配置

Gitleaks 支持自定义密钥检测规则，配置文件为 TOML 格式:

toml
# Gitleaks 配置文件标题
title = "Gitleaks 配置"

# 定义密钥检测规则的数组
[[rules]]
# 规则唯一标识符
id = "示例规则-1"
# 规则简短描述
description = "示例规则 1"
# 用于检测密钥的 Golang 正则表达式（不支持前瞻断言）
regex = '''golang风格的正则表达式''' 
# 用于匹配路径的正则表达式，可单独使用或与 regex 配合
path = '''文件路径正则表达式''' 
# 元数据和报告标签
tags = ["标签1", "标签2"]
# 用于检查正则匹配组香农熵的索引
entropyGroup = 3
# 正则组需满足的最小香农熵值
entropy = 3.5
# 规则级允许列表，用于减少误报或忽略已知密钥的提交
[rules.allowlist]
description = "忽略提交A"
commits = [ "commit-A", "commit-B"]
paths = ['''文件路径正则表达式''']
regexes = ['''匹配已检测密钥的正则''']

# 全局允许列表，优先级高于规则级允许列表
[allowlist]
description = "忽略提交A"
commits = [ "commit-A", "commit-B"]
paths = ['''文件路径正则表达式''']
regexes = ['''匹配已检测密钥的正则''']

默认配置可参考 https://github.com/zricethezav/gitleaks/blob/v8/config/gitleaks.toml%E3%80%82

退出码

默认退出码:

• 0: 未检测到密钥
• 1: 检测到密钥或发生错误 可通过 --exit-code 标志自定义检测到密钥时的退出码。