# 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](https://github.com/gitleaks/gitleaks)** — fast, runs as a pre-commit hook or a CI step; regex rules plus entropy heuristics. - **[TruffleHog](https://github.com/trufflesecurity/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)[^meli2019] — 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)[^meli2019]. - **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)[^bessey2010], 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 - [Static analysis](https://quality.stereobooster.com/static-analysis.md) · Methods ## References [^meli2019]: Meli, Michael, Matthew R. McNiece, and Bradley Reaves. 2019. "[How Bad Can It Git? Characterizing Secret Leakage in Public GitHub Repositories](https://www.ndss-symposium.org/wp-content/uploads/2019/02/ndss2019_04B-3_Meli_paper.pdf)." *Proceedings of the 2019 Network and Distributed System Security Symposium (NDSS)*. . [^bessey2010]: 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](https://web.stanford.edu/~engler/BLOC-coverity.pdf)." *Communications of the ACM* 53 (2): 66–75. .