Gitleaks & ggshield Quick Reference Guide

Gitleaks

Gitleaks is a SAST tool for detecting hardcoded secrets like passwords, API keys, and tokens in git repositories.

Installation

# macOS
brew install gitleaks
 
# Go install
go install github.com/zricethezav/gitleaks/v8@latest
 
# Docker
docker pull zricethezav/gitleaks:latest

Essential Commands

Scan git repository:

gitleaks git
gitleaks git . -v
gitleaks git /path/to/repo

Scan directory (non-git aware):

gitleaks dir
gitleaks dir . -v
gitleaks dir /path/to/directory

Pre-commit protection:

gitleaks git --pre-commit
gitleaks git --pre-commit --staged

Scan specific commit range:

gitleaks git -v --log-opts="--all commitA..commitB"
gitleaks git --log-opts="HEAD~10..HEAD"
gitleaks git --log-opts="main..feature-branch"

Scan from stdin:

cat some_file | gitleaks stdin -v
echo "password=secret123" | gitleaks stdin

Configuration:

gitleaks git --config /path/to/gitleaks.toml
gitleaks dir . --config custom-config.toml

Baseline (ignore existing secrets):

# Create baseline
gitleaks git --report-path baseline.json
# Use baseline
gitleaks git --baseline-path baseline.json --report-path findings.json
gitleaks dir . --baseline-path baseline.json

Output formats:

gitleaks git --report-format json --report-path report.json
gitleaks git --report-format csv --report-path report.csv
gitleaks git --report-format sarif --report-path report.sarif
gitleaks dir . --report-format json --report-path report.json

Advanced options:

# Enable secret decoding
gitleaks git --max-decode-depth 2
 
# Scan only specific rules
gitleaks git --enable-rule="aws-access-token,github-pat"
 
# Redact secrets in output
gitleaks git --redact -v
 
# Skip large files
gitleaks dir . --max-target-megabytes 10

Docker usage:

# Git repository scan
docker run --rm -v $(pwd):/scan zricethezav/gitleaks:latest git /scan
 
# Directory scan
docker run --rm -v $(pwd):/scan zricethezav/gitleaks:latest dir /scan

Configuration

Create .gitleaks.toml in your repo root:

[extend]
useDefault = true
 
[[rules]]
description = "Custom API Key"
regex = '''custom-key-[a-zA-Z0-9]{32}'''
tags = ["api", "custom"]
 
[[rules.allowlists]]
description = "Allowlist for test files"
paths = ['''test/.*''']
regexes = ['''test-key-.*''']

Ignore Files

Create .gitleaksignore with fingerprints:

# Ignore specific findings by fingerprint
8ac8e8c4e76f08b23a09c3f89e1e2c4f9d8e3b7a

# Comments are supported
# This ignores a test API key
1234567890abcdef1234567890abcdef12345678

ggshield

GitGuardian’s CLI tool for detecting secrets in code, with real-time protection and policy management.

Installation

# pip
pip install ggshield
 
# macOS
brew install gitguardian/tap/ggshield
 
# Docker
docker pull gitguardian/ggshield:latest

Authentication

# Set API key
ggshield auth login
# or
export GITGUARDIAN_API_KEY="your-api-key"

Essential Commands

Scan current directory:

ggshield secret scan path .
ggshield secret scan path . --recursive

Scan specific files:

ggshield secret scan path file.py
ggshield secret scan path file1.js file2.py

Scan git repository:

ggshield secret scan repo .
ggshield secret scan repo https://github.com/user/repo.git

Pre-commit scanning:

ggshield secret scan pre-commit

Pre-push scanning:

ggshield secret scan pre-push

Pre-receive scanning:

ggshield secret scan pre-receive

Scan commit range:

ggshield secret scan commit-range HEAD~10..HEAD
ggshield secret scan commit-range main..feature-branch

CI/CD scanning:

ggshield secret scan ci

Docker container scanning:

ggshield secret scan docker nginx:latest

Archive scanning:

ggshield secret scan archive archive.tar.gz

Output Options

JSON output:

ggshield secret scan path . --json

Text output with details:

ggshield secret scan path . --text --verbose

Exit codes:

ggshield secret scan path . --exit-zero  # Always exit with 0

Ignore and Baseline

Create .gitguardian.yaml:

version: 2
paths-ignore:
  - tests/
  - "*.log"
  - node_modules/
 
matches-ignore:
  - match: "fake-secret-for-tests"
    name: "Test secret"

Ignore inline:

api_key = "sk-1234567890abcdef"  # ggignore

Git Hooks Setup

Pre-commit hook:

# Install pre-commit
pip install pre-commit
 
# Add to .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitguardian/ggshield
    rev: v1.25.0
    hooks:
      - id: ggshield
        language: python
        stages: [commit]

Manual git hook:

# .git/hooks/pre-commit
#!/bin/sh
ggshield secret scan pre-commit

Docker Usage

# Scan current directory
docker run --rm -v $(pwd):/scan gitguardian/ggshield secret scan path /scan
 
# With API key
docker run --rm -v $(pwd):/scan -e GITGUARDIAN_API_KEY=your-key gitguardian/ggshield secret scan path /scan

CI/CD Integration Examples

GitHub Actions (Gitleaks)

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

GitHub Actions (ggshield)

- name: GitGuardian scan
  uses: GitGuardian/ggshield-action@v1
  env:
    GITHUB_PUSH_BEFORE_SHA: ${{ github.event.before }}
    GITHUB_PUSH_BASE_SHA: ${{ github.event.repository.default_branch }}
    GITHUB_PULL_BASE_SHA: ${{ github.event.pull_request.base.sha }}
    GITHUB_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
    GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}

GitLab CI (Gitleaks)

gitleaks:
  stage: test
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks git --report-format json --report-path gl-secret-detection-report.json
  artifacts:
    reports:
      secret_detection: gl-secret-detection-report.json

Pre-commit Setup (Gitleaks)

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2
    hooks:
      - id: gitleaks

Quick Comparison

Feature	Gitleaks	ggshield
Free/Open Source	✅	✅ (Limited)
Custom Rules	✅	✅ (Pro)
Real-time Scanning	✅	✅
Historical Scan	✅	✅
Policy Management	Basic	Advanced
Cloud Dashboard	❌	✅
Team Management	❌	✅

Both tools are excellent for secret detection. Gitleaks is fully open source and self-contained, while ggshield offers more enterprise features with GitGuardian’s cloud platform integration.