Betterleaks: A Secrets Scanner That Filters by Context, Not Just Regex

What Betterleaks Solves and Who It Is For

The project is written in Go and distributed as a small binary. The README claims portability across modern OS and architecture. The core value is not just finding secrets but filtering out the non-secrets, which the blog post titles hint at: 'Regex is all you need' and 'Rare Not Random'. That framing tells you the project is opinionated about detection methodology, not just a wrapper around existing tools.

The Detection Engine: Prefilters, Filters, and Expr

The filtering logic is written in Expr, a language that the README says is more expressive than the old CEL-based system. CEL configs are still accepted for compatibility, but new configs should use Expr. This is a deliberate trade-off: you get more power but you have to learn a new syntax. The README also describes multipart rules, where a primary rule declares component rules and reads their secrets through expressions like components['rule-id']?.secret. This allows detecting secrets that are split across multiple fields or files. The detection engine is the core of the project, and the blog posts linked in the README go deeper into how it works, but the README itself gives enough to understand the data flow: attributes in, prefilter, regex, filter, validation.

Scanning Sources: Git, Files, GitHub, GitLab, S3, and More

The source list is a differentiator. Most secrets scanners focus on git history or filesystem. Betterleaks extends to cloud and platform sources, which matters if you want to scan for leaked secrets across an entire org or a Hugging Face model repository. The README says it is easy to add new sources, but does not detail the interface. That is a gap you would need to check in the docs or source code.

Installation and Getting Started

A basic scan is one command: 'betterleaks git /path/to/repo -v --source-workers=16'. The -v flag is verbose, and --source-workers controls parallelism. The README mentions sane default parallelization, so you can adjust workers for large scans. For a filesystem scan, 'betterleaks dir /path/to/file/or/dir -v'. The config file is betterleaks.toml, and the README recommends maintaining your own config in production rather than extending the default upstream config. That is a maintenance point: you want stable rules across upgrades, and you want to review new upstream rules before adopting them. The README also points to a web playground at betterleaks.com/playground for testing rules.

Validation and Token Efficiency: Two Unusual Filters

Second, token efficiency filtering: the scanner uses BPE tokenization to measure how 'rare' or non-human a string is. The idea is that natural language text is common and thus has low token efficiency, while a real secret like a long random string is rare. This is a heuristic, and the README does not explain the threshold or how to tune it. It is a clever approach, but it could also filter out legitimate secrets that happen to look like prose, or keep false positives that are random-looking but not secrets. The blog post 'Rare Not Random' likely explains the math, but the README does not.

Limitations and When It Is the Wrong Tool

It is the wrong tool if you need a zero-config scanner that just reports matches. Betterleaks expects you to invest in config. It is also not ideal if you want to scan a single file quickly without setting up a config, though the dir command works for that. The README does not mention any built-in reporting or dashboard, so you would need to integrate with other tools for that.

Alternatives: Gitleaks and TruffleHog

Another alternative is TruffleHog, which also scans for secrets across git history and has its own verification mechanisms. TruffleHog uses a different approach: it looks for high-entropy strings and then verifies them against known APIs. Betterleaks relies on regex plus contextual filtering and validation. The difference is that TruffleHog is more automated with built-in verifiers, while Betterleaks gives you more control through Expr. The choice depends on whether you want to write custom logic (Betterleaks) or rely on pre-built verifiers (TruffleHog).

Maintenance, Upgrades, and License

Upgrade cost is moderate. Since the config format changed from CEL to Expr, you may need to migrate existing configs. The README says CEL is accepted for compatibility, but that is a temporary bridge. You should plan to rewrite rules in Expr eventually. The binary is small and portable, so deployment is easy, but the config is where the real work lies. The playground is a useful tool for testing rules before deploying them.

Editorial conclusion

Adopt Betterleaks if you need a secrets scanner that goes beyond regex matching, especially if you manage many repositories and want to filter false positives with contextual logic. Do not adopt it if you prefer a simple, out-of-the-box tool with minimal configuration, because Betterleaks expects you to write Expr filters and maintain your own config. Before adopting, verify that your team can handle Expr syntax, that your existing Gitleaks configs migrate cleanly (CEL is accepted but deprecated), and that the sources you need (like S3 or Hugging Face) are covered. Also, check the default config to see which rules are active and whether you need to adjust parallelization settings for your scan environment.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes