OSS Spotlight: Gitleaks

An open-source secrets scanner for the exact mistake this newsletter keeps flagging: a credential that should never have reached a repository in the first place.

Gitleaks scans git repositories, directories, and piped input for hardcoded secrets — API keys, tokens, passwords, private keys — before or after they're committed. It's MIT licensed, sits at just under 30,000 stars on GitHub, and its detection engine works the way its own docs describe it: "regex is (almost) all you need," pattern-matching known secret formats and using Shannon entropy to flag high-randomness strings that look like credentials even when they don't match a known pattern.

How it works

Every Gitleaks rule lives in a .gitleaks.toml config: a regex pattern, an entropy threshold, an optional file-path scope, and an allowlist for known-safe matches — by commit, by path, by a stopword list, or a same-line gitleaks:allow comment for one-off exceptions. Two scan modes matter for different moments in a workflow. gitleaks dir scans a directory's current state. gitleaks git walks the full commit history via git log -p — the mode that actually matters if a secret was ever committed and later deleted, since deleting a file doesn't delete it from history, and dir mode alone would miss it entirely.

A concrete example

A custom rule for an AWS access key, and a full-history scan that writes findings to a report instead of just printing them:

[[rules]]
id = "aws-access-key"
description = "AWS Access Key"
regex = '''(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}'''
tags = ["aws", "credential"]

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

That's the same class of finding as this week's Weekly Roundup's JadePuffer item — a credential exposed somewhere it shouldn't have been, then used for real damage once someone found it. Gitleaks is the tool that catches this before an attacker does, not after.

Getting started

brew install gitleaks
# or: go install github.com/gitleaks/gitleaks/v8@latest
gitleaks git -v .

Then wire it into the two points where a leak is cheapest to catch. As a pre-commit hook, so a secret never leaves a developer's laptop:

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

And in CI, as the backstop for whatever the hook missed or was skipped past, using the project's own Gitleaks-Action for GitHub Actions.

The honest caveats

• The project is in maintenance mode. In the maintainer's own words: "Gitleaks is feature complete. I'm not merging new features into Gitleaks. Future releases will be security patches only." Development focus has shifted to a separate successor project, Betterleaks. That doesn't make Gitleaks unsafe to run today, but it does mean the built-in ruleset won't necessarily keep pace with new secret formats going forward — budget time to maintain your own custom rules, and keep an eye on Betterleaks as the project it's shifting toward.
• Entropy-based detection produces real false positives. Legitimate high-randomness strings — hashes, generated IDs, minified code — regularly trip the entropy check. Budget time for tuning the allowlist; don't expect clean output on the first run.
• A first full-history scan on a large, long-lived repository can surface a big backlog and take a while. Use --baseline-path to suppress already-known findings and focus review on what's new going forward, not to make the initial backlog disappear — someone still has to triage it once.
• It only sees what's committed to git. It does not catch a secret sitting in a GitHub issue, a comment, a Slack message, or a CI log — which is exactly where this week's JadePuffer credential surfaced. Gitleaks is necessary but not sufficient for the standard this newsletter keeps arguing for: secrets scanning that covers issues and comments continuously, not just code at merge time.

For a team already committed to "secrets should never be committed to a repository," Gitleaks is the tool that actually enforces it, rather than leaving it as a policy nobody checks.

Sources: Gitleaks on GitHub · Gitleaks-Action · Betterleaks