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. The scan flags 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 — matches regex rules plus entropy heuristics, and runs as a pre-commit hook or a CI step.
  • 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 readable by anyone who can clone the repository.
  • 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 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. None of the monitored repositories that removed a secret rewrote its history, so the removed secrets stayed readable in git history (Meli et al. 2019)1.
  • 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.

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. ↩↩