Skip to content

Software Quality

Secret scanning

Secret scanning searches a repository for committed credentials, matching each string against regex rules and scoring it for entropy. The scan covers the whole git history, because a key deleted from HEAD but live in an old commit is still leaked. Both signals are tuned for a low false-positive rate: the same empirical trade any linter makes, aimed at a security target.

What it catches

  • Credentials in the working tree. Hardcoded API keys, tokens, passwords and private keys, wherever a rule or an entropy threshold matches them.
  • Credentials only in history. A key removed in a later commit is still present in the objects an attacker can clone, so the current tree being clean says nothing.
  • Dead versus live secrets. A scanner that verifies a candidate against the issuing provider separates a credential still worth revoking from one already rotated.

What it does not catch: a credential that matches no rule and scores below the entropy threshold. Recall is bounded by the rule set, and verifying a candidate against its provider drops dead secrets without finding new ones.

Tools

  • gitleaks — fast, runs as a pre-commit hook or a CI step; regex rules plus entropy heuristics.
  • TruffleHog — adds verification: it tries the candidate credential against the provider's API to drop secrets that no longer work.

When to use, when not

Use:

  • On every repository that has ever held a credential, which in practice means every repository. The scan is cheap and the cost of a miss is a live key in public.
  • As a pre-commit hook and a CI step, so a leaked key is caught whether it is about to land or already has.
  • Over the whole history rather than the current tree, because that is where the durable leaks are.

Don't:

  • As the containment plan. A finding starts a rotation; it does not end an exposure, and a key that has been public is public.
  • As a reason to skip a secret manager. Scanning detects the mistake the design still permits.

Evidence

The target is well established; the tooling's effect on it is not.

  • The leaks are abundant and persistent. A six-month scan of live public GitHub commits plus a snapshot covering 13% of public repositories found secrets in over 100,000 repositories, with thousands of new unique secrets committed daily, and most of them remained available for weeks or longer (Meli et al. 2019)1 — the case for scanning history rather than HEAD.
  • Detection is not containment. The same study evaluated mitigations including automatic leakage detectors and found they "all fail to limit systemic large-scale secret exposure" (Meli et al. 2019)1.
  • No evidence on live verification. TruffleHog's provider-API check is a plausible way to cut false positives, and the adoption literature makes false-positive volume decisive (Bessey et al. 2010)2, but no study measures whether that verification step changes either the noise level or adoption.

Classification

  • Quality dimensions: Security.
  • Area: Committed credentials — API keys, tokens, passwords and private keys in the working tree and anywhere in a repository's history; pre-commit hooks and CI gates.
  • Guarantee: Empirical — pattern and entropy heuristics over the whole git history, tuned for false-positive rate; verification against the provider's API removes dead secrets.

Referenced by

References

  1. Meli, Michael, Matthew R. McNiece, and Bradley Reaves. 2019. "How Bad Can It Git? Characterizing Secret Leakage in Public GitHub Repositories." Proceedings of the 2019 Network and Distributed System Security Symposium (NDSS). https://doi.org/10.14722/ndss.2019.23418. ↩↩

  2. Bessey, Al, Ken Block, Ben Chelf, et al. 2010. "A Few Billion Lines of Code Later: Using Static Analysis to Find Bugs in the Real World." Communications of the ACM 53 (2): 66–75. https://doi.org/10.1145/1646353.1646374. ↩