Gitleaks 工具调研报告

brew install gitleaks

# 直接使用 Docker 运行
docker run --rm -it -v $(pwd):/path zricethezav/gitleaks:latest detect --source /path

go install github.com/gitleaks/gitleaks-next@latest
# 或旧版
go install github.com/zricethezav/gitleaks@latest

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.0
    hooks:
      - id: gitleaks

# 扫描本地 Git 仓库完整历史
gitleaks detect --source /path/to/repo

# 仅扫描未提交的变更（staged files）
gitleaks detect --source . --log-opts="--all"

# 扫描指定分支
gitleaks detect --source . --log-opts="--all -- main..HEAD"

# 扫描目录（非 git 仓库）
gitleaks detect --source /path/to/dir

# 从 stdin 读取
echo "AKIAIOSFODNN7EXAMPLE" | gitleaks detect --no-git

# 指定报告格式和输出路径
gitleaks detect --source . --report-path findings.json --report-format json

# 启用 SARIF 输出（GitHub Advanced Security 集成）
gitleaks detect --source . --report-format sarif --report-path findings.sarif

# 在输出中脱敏（隐藏发现的密钥）
gitleaks detect --source . --redact

# 设置退出码（发现密钥时返回指定码）
gitleaks detect --source . --exit-code 1

# 指定自定义规则文件
gitleaks detect --source . --config gitleaks.toml

# 忽略特定文件
gitleaks detect --source . --ignore-path "test/fixtures/*"

# 使用熵检测（额外发现未知模式的密钥）
gitleaks detect --source . --enable-entropy

# 限制扫描深度
gitleaks detect --source . --log-opts="--max-count=100"

# 保护 staged 文件（用于 pre-commit hook）
gitleaks protect --staged

# 保护未 staged 的变更
gitleaks protect

# 指定退出码
gitleaks protect --staged --exit-code 1

# .github/workflows/gitleaks.yml
name: Gitleaks Secret Scan

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 必须获取完整历史

      - name: Run Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # 启用 PR 评论（在 PR 中标注发现的密钥）
          GITLEAKS_ENABLE_COMMENTS: true

# .github/workflows/gitleaks.yml
name: Gitleaks Secret Scan

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    # 每周一凌晨 6 点全量扫描
    - cron: '0 6 * * 1'

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Download Gitleaks config
        run: |
          curl -LO https://raw.githubusercontent.com/gitleaks/gitleaks/master/configs/gitleaks.toml

      - name: Run Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_CONFIG: gitleaks.toml
          GITLEAKS_ENABLE_COMMENTS: true

# PR 场景下，gitleaks-action 默认只扫描 PR 引入的新变更
# 使用 fetch-depth: 0 确保能正确计算 diff

# .gitlab-ci.yml
stages:
  - security

gitleaks:
  stage: security
  image: zricethezav/gitleaks:latest
  script:
    # 扫描当前分支的提交
    - gitleaks detect --source . --report-path gitleaks-report.json --report-format json --exit-code 0
  artifacts:
    paths:
      - gitleaks-report.json
    when: always
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'

# .gitlab-ci.yml
gitleaks:
  stage: security
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks detect --source . --config gitleaks.toml --report-format json

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.0
    hooks:
      - id: gitleaks
        name: gitleaks (protect staged)
        args: ["protect", "--staged", "--verbose"]
        stages: [pre-commit]

# 安装 pre-commit 框架
pip install pre-commit

# 安装 git hook
pre-commit install

# 手动运行检查
pre-commit run --all-files

#!/bin/sh
# .git/hooks/pre-commit

# 使用 Docker 运行（无需本地安装 gitleaks）
docker run --rm -it \
  -v "$(pwd):/path" \
  zricethezav/gitleaks:latest \
  protect --staged --source /path --verbose

if [ $? -ne 0 ]; then
  echo "Secret detected! Please remove the secret before committing."
  exit 1
fi

#!/bin/sh
# .git/hooks/pre-commit
exec docker run --rm -v "$(pwd):/code" zricethezav/gitleaks:latest protect --staged --source /code --verbose

# 生成默认配置
gitleaks detect --source . --generate-config > gitleaks.toml

# gitleaks.toml
[extend]
# 可以继承默认规则或远程规则
useDefault = true

# 自定义规则
[[rules]]
id = "custom-api-key"
description = "Custom API Key Pattern"
regex = '''mycompany_[A-Za-z0-9]{32}'''
keywords = ["mycompany_"]

# 高熵值检测规则
[[rules]]
id = "high-entropy-base64"
description = "High Entropy Base64 String"
regex = '''[A-Za-z0-9+/]{40,}={0,2}'''
entropy = 4.5
keywords = []

# gitleaks.toml
[config]
# 熵阈值
entropy = 4.5

# 最大密钥长度（超过此长度不扫描）
maxTargetLength = 500

# 允许的文件扩展名
allowList = { extensions = [".md", ".txt"] }

# gitleaks.toml
[[rules]]
id = "aws-access-key"
description = "AWS Access Key"
regex = '''AKIA[0-9A-Z]{16}'''
keywords = ["AKIA"]

# 规则级 allowlist
[[rules.allowlists]]
description = "Ignore test keys"
regexes = ['''AKIAIOSFODNN7EXAMPLE''']  # 测试用示例密钥
paths = ['''test/fixtures/.*''']        # 测试文件
commits = ['''abc123def456''']          # 特定 commit

# 全局 allowlist
[allowlist]
description = "Global allowlist"
paths = [
  '''(.*?)(jpg|gif|png|svg)$''',       # 忽略图片文件
  '''node_modules''',                   # 忽略 node_modules
  '''vendor''',                         # 忽略 vendor 目录
  '''test/fixtures''',                  # 忽略测试 fixtures
]
regexes = [
  '''example''',                        # 忽略包含 "example" 的内容
  '''placeholder''',                    # 忽略占位符
  '''TODO''',                           # 忽略 TODO 注释
]

# 忽略特定路径
gitleaks detect --source . --ignore-path "test/fixtures/*"
gitleaks detect --source . --ignore-path ".env.example"

推荐方案：Gitleaks（pre-commit + GitHub Action）
成本：免费
配置复杂度：低

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.0
    hooks:
      - id: gitleaks
        args: ["protect", "--staged", "--verbose"]

推荐方案：Gitleaks（pre-commit）+ Gitleaks（CI）+ TruffleHog（定期全量扫描）
成本：免费
配置复杂度：中等

# 多层防御
# Layer 1: pre-commit 阻止提交
# Layer 2: CI/CD PR 扫描
# Layer 3: 定期 TruffleHog 全量扫描 + 活体验证

推荐方案：GitGuardian 或 TruffleHog 企业版
成本：付费
配置复杂度：中高

# 企业级需求：
# - 集中化仪表板
# - 实时 push protection
# - 密钥轮换工作流
# - 合规审计报告
# - 团队协作和告警

推荐方案：detect-secrets 基线机制 或 Gitleaks allowlist
成本：免费
配置复杂度：中

# 先用 detect-secrets 建立基线
detect-secrets scan > .secrets.baseline

# 或将已知密钥加入 Gitleaks allowlist

推荐方案：Gitleaks（SARIF 输出）
成本：免费

# GitHub 上 SARIF 输出直接集成到 Security 标签页
gitleaks detect --source . --report-format sarif --report-path results.sarif

# macOS
brew install gitleaks

# 验证安装
gitleaks --version

# 扫描当前仓库
gitleaks detect --source . --redact --verbose

# 创建 .pre-commit-config.yaml
cat > .pre-commit-config.yaml << 'EOF'
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.0
    hooks:
      - id: gitleaks
        args: ["protect", "--staged", "--verbose"]
EOF

# 安装
pip install pre-commit
pre-commit install