gitleaks/gitleaks

Detect secrets and api keys in git repos or files to prevent security issues

Summary

Gitleaks is a Go-based CLI tool that scans git repositories, directories, and stdin input for hardcoded secrets like passwords, API keys, and tokens. It uses regex rules combined with entropy checks and produces detailed findings showing the file, line, commit, author, and a unique fingerprint per secret. Per the README, the project is marked "feature complete," with the maintainer shifting focus to Betterleaks and limiting future releases to security patches.

What it is useful for

Catching secrets before they ship or get cleaned up too late. The README shows it flagging strings like BUNDLE_ENTERPRISE__CONTRIBSYS__COM=cafebabe:deadbeef in a sidekiq-secret rule. Concrete use cases documented in the source:

• Scanning full git history, not just working trees, so old leaks surface even after files are removed.
• Running as a pre-commit hook so developers see a "Failed" message locally before pushing.
• CI/CD gating using the companion gitleaks-action GitHub Action or the binary directly.
• Triaging long histories with a baseline file so existing findings don't block new work.
• Decoding obfuscated secrets (percent, hex, base64) via --max-decode-depth, and scanning inside archives via --max-archive-depth.
• Outputting reports as JSON, CSV, JUnit, SARIF, or a custom template for downstream tooling.

How engineers can use it

Installation options from the README:

brew install gitleaks
# or
docker pull zricethezav/gitleaks:latest
# or, from source (Go required):
git clone https://github.com/gitleaks/gitleaks.git
cd gitleaks && make build

Common commands:

gitleaks dir -v path/to/folder     # scan files
gitleaks git -v path/to/repo       # scan git history
cat some_file | gitleaks -v stdin  # stream content
gitleaks git --log-opts="--all commitA..commitB"   # range of commits

Pre-commit setup: install pre-commit, then add to .pre-commit-config.yaml:

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

Run pre-commit autoupdate and pre-commit install. Skip with SKIP=gitleaks git commit ... when needed. Inline ignores use a # gitleaks:allow comment; repo-wide ignores use .gitleaksignore with finding fingerprints.

Baselines for big repos:

gitleaks git --report-path gitleaks-report.json
gitleaks git --baseline-path gitleaks-report.json --report-path findings.json

Configuration is TOML-based with custom regex rules, entropy thresholds, keywords, and allowlists. Precedence is --config flag → GITLEAKS_CONFIG env → GITLEAKS_CONFIG_TOML env → .gitleaks.toml in the target path.

Documented limitations: .gitleaksignore fingerprints and the v8.28.0 composite/proximity rules are marked experimental; Go's regex engine does not support lookaheads; the detect and protect commands were deprecated in v8.19.0. License is MIT.