Gitleaks

Gitleaks Secret Detection

When to Use Gitleaks

Ideal scenarios:

• Scanning for hardcoded secrets in source code
• Auditing git history for leaked credentials
• Pre-commit hooks to prevent secret commits
• CI/CD pipeline secret detection
• Finding API keys, passwords, tokens, private keys
• Compliance requirements for credential management

Complements other tools:

• Use before manual code review to catch obvious secrets
• Combine with SARIF Issue Reporter for detailed analysis
• Use alongside Application Inspector for comprehensive security audit

When NOT to Use

Do NOT use this skill for:

• Code vulnerability detection (use Semgrep or CodeQL)
• Dependency scanning (use OSV-Scanner or Depscan)
• IaC security analysis (use KICS)
• Technology profiling (use Application Inspector)
• Finding secrets in binary files or compiled code

Installation

# Homebrew (macOS/Linux)
brew install gitleaks

# Binary download
wget https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks-linux-amd64
chmod +x gitleaks-linux-amd64
sudo mv gitleaks-linux-amd64 /usr/local/bin/gitleaks

# Docker
docker pull ghcr.io/gitleaks/gitleaks:latest

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

# Verify
gitleaks version

Core Workflow

1. Quick Scan

# Scan current directory (git repo)
gitleaks detect

# Scan specific directory
gitleaks detect --source /path/to/repo

# Scan uncommitted changes only
gitleaks protect

# Scan with no banner/color (for CI)
gitleaks detect --no-banner --no-color

2. SARIF Output

# Generate SARIF report
gitleaks detect \
  --report-format sarif \
  --report-path results.sarif

# With additional options
gitleaks detect \
  --source /path/to/repo \
  --report-format sarif \
  --report-path results.sarif \
  --no-banner \
  --no-color \
  --exit-code 0

# Redact secrets in output
gitleaks detect \
  --report-format sarif \
  --report-path results.sarif \
  --redact

3. Scan Git History

# Scan all commits
gitleaks detect --source /path/to/repo --verbose

# Scan specific commit range
gitleaks detect --log-opts="--since='2024-01-01'"

# Scan specific branch
gitleaks detect --source /path/to/repo --log-opts="origin/main"

4. Additional Formats

# JSON output
gitleaks detect --report-format json --report-path results.json

# CSV output
gitleaks detect --report-format csv --report-path results.csv

# JUnit XML
gitleaks detect --report-format junit --report-path results.xml

Configuration

Custom Config File

Create .gitleaks.toml:

title = "Gitleaks Configuration"

[extend]
# Extend default config
useDefault = true

[[rules]]
id = "custom-api-key"
description = "Custom API Key Pattern"
regex = '''(?i)api[_-]?key['\"]?\s*[:=]\s*['\"]([a-z0-9]{32,})'''
keywords = ["apikey", "api_key"]

[[rules]]
id = "slack-webhook"
description = "Slack Webhook URL"
regex = '''https://hooks\.slack\.com/services/T[a-zA-Z0-9_]{8,}/B[a-zA-Z0-9_]{8,}/[a-zA-Z0-9_]{24,}'''

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

[allowlist]
description = "Allowlist for false positives"
regexes = [
  '''EXAMPLE_API_KEY''',
  '''placeholder-secret''',
  '''test-token-123'''
]
paths = [
  '''.gitleaks.toml''',
  '''README.md''',
  '''docs/'''
]

Use Custom Config

gitleaks detect --config .gitleaks.toml

# With SARIF output
gitleaks detect \
  --config .gitleaks.toml \
  --report-format sarif \
  --report-path results.sarif

Ignoring False Positives

Inline Comments

# gitleaks:allow
api_key = "this-is-a-test-key-not-real"

password = "example-password"  # gitleaks:allow

.gitleaksignore File

Create .gitleaksignore:

# Ignore specific findings by fingerprint
fingerprint:abc123def456

# Ignore files
tests/fixtures/secrets.txt
docs/examples/*.py

# Ignore commits
commit:a1b2c3d4e5f6

Baseline Mode

# Create baseline of existing findings
gitleaks detect --report-path baseline.json --report-format json

# Scan only new findings
gitleaks detect --baseline-path baseline.json

CI/CD Integration (GitHub Actions)

name: Gitleaks

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 0 * * 0'  # Weekly

jobs:
  gitleaks:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for complete scan

      - name: Run Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}  # Optional: for Gitleaks Pro

      - name: Generate SARIF
        if: always()
        run: |
          gitleaks detect \
            --report-format sarif \
            --report-path gitleaks.sarif \
            --no-banner \
            --no-color \
            --exit-code 0

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: gitleaks.sarif
          category: gitleaks

      - name: Upload Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: gitleaks-results
          path: gitleaks.sarif

Pre-commit Hook

Install Pre-commit

# Install pre-commit
pip install pre-commit

# Create .pre-commit-config.yaml
cat > .pre-commit-config.yaml  .git/hooks/pre-commit 
- Documentation: 
- Default Rules: 
- SARIF Spec: 
- Pre-commit Hook:

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [igbuend](https://github.com/igbuend)
- **Source:** [igbuend/grimbard](https://github.com/igbuend/grimbard)
- **License:** MIT

Install and usage instructions live in the source repository linked above.