> ## Content Index
> Fetch the complete content index at: https://secblog.reedcloudsec.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# OSS Spotlight: Gitleaks
- URL: https://secblog.reedcloudsec.com/oss-spotlight-gitleaks/
- Published: 2026-09-29T21:58:42.000Z
- Updated: 2026-09-29T21:58:42.000Z
- Description: An open-source git secrets scanner, why entropy-based detection still misses secrets leaked outside git entirely, and why the project itself is winding down new feature work.
- Author: Marselis A. Reed
- Tags: OSS & Tooling Spotlight

*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:

```toml
[[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"]
```

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

That's the same class of finding as this week's Weekly Roundup's [JadePuffer item](https://secblog.reedcloudsec.com/secblog-weekly-issue-005/) — 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

```shell
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:

```yaml
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](https://github.com/gitleaks/gitleaks?ref=secblog.reedcloudsec.com) · [Gitleaks-Action](https://github.com/gitleaks/gitleaks-action?ref=secblog.reedcloudsec.com) · [Betterleaks](https://github.com/betterleaks/betterleaks?ref=secblog.reedcloudsec.com)