Secret scanning: find leaked keys in your code before attackers do
Secret scanning is software that searches your code and Git history for keys, passwords and tokens. You can run a scanner on your own machine before code leaves it, or let GitHub scan the repository after you push. On GitHub it is free for public repositories, and push protection, which blocks a push that contains a secret, is off by default at the repository level. When any scanner finds a key, revoke it first.
Keys leak in volume. In 2024, 23,770,171 new secrets were detected in public GitHub commits, up 25%. Of the secrets leaked in 2022, 70% are still valid. Automated scanners can locate publicly exposed secrets in minutes, and malicious actors can exploit them within hours.
01What a secret scanner looks for
A secret scanner reads files and commits and matches them against known formats of credentials: API keys, passwords, tokens and private keys. Some scanners also check whether a match is real. TruffleHog discovers, classifies, validates and analyzes secrets. It classifies over 800 secret types, and for each type it can log in to confirm whether the secret is live.
Attackers run scanners too. The payload of the Shai-Hulud attack, a malicious npm package, used TruffleHog to find secrets on the machines it reached. The story is on the Shai-Hulud page. A key in a file on your disk is findable by anyone who runs a scanner there.
02Local scanning and GitHub scanning
The two kinds catch different moments.
| On your machine | On GitHub | |
|---|---|---|
| When | Before commit or push, or any time you run it | On the repository you pushed, and as a push is attempted |
| Examples | TruffleHog, ggshield, git-secrets | GitHub secret scanning, push protection |
| Catches | Keys in files not yet pushed | Keys already pushed, or about to be |
Local scanning is the earlier line of defense. A pre-commit hook, a script Git runs before it records a commit, can reject a commit that contains a key. The usual advice is a pre-commit hook that rejects commits containing keys detected by your secret scanner. TruffleHog is available as a GitHub Action and a pre-commit hook. ggshield runs locally, in CI and as a pre-commit hook. CI is the automatic build and test system that runs when you push code.
03Four tools side by side
This is a description, not a ranking.
| Tool | Where it runs | What it does | What you need |
|---|---|---|---|
| GitHub secret scanning | On GitHub | Scans the entire Git history on all branches. Validity checks show whether a detected secret is still active | Free for public repositories. Organization-owned private repositories need GitHub Secret Protection on Team or Enterprise Cloud |
| TruffleHog | Your terminal, CI, pre-commit | Classifies over 800 secret types and can confirm a secret is live | brew install trufflehog on macOS |
| ggshield | Your terminal, CI, pre-commit | Command line tool from GitGuardian that detects secrets | A GitGuardian workspace and an API key to authenticate. brew install ggshield |
| git-secrets | Git hooks in each repository | Rejects commits matching prohibited patterns | brew install git-secrets, then hooks installed per repository |
GitGuardian itself and a longer comparison are on the GitGuardian alternatives page.
04Scan a repository yourself
Two commands are enough to start. For TruffleHog, install it with Homebrew. Then run this example, which scans a repository and shows only verified secrets, meaning secrets confirmed live:
brew install trufflehog
trufflehog git https://github.com/trufflesecurity/test_keys --results=verifiedThat scans a public test repository. TruffleHog has a sub-command for each source of data you may want to scan, including filesystem for files and folders on your Mac. The TruffleHog page walks through local repositories, folders and GitHub.
For ggshield, authenticate first with ggshield auth login, then scan the repository you are in:
ggshield auth login
ggshield secret scan repo .05Setting up scanning on GitHub
On a public repository, the scanner already runs for free. To turn it on in a repository where you have the option, open the repository Settings, click Advanced Security, and click Enable to the right of Secret Protection. Alerts then appear in the Security and quality tab. A private repository owned by a personal account is covered only on Enterprise Cloud with Managed Users or on Enterprise Server.
Push protection at the repository level is off by default, and a repository administrator, organization owner, security manager or enterprise owner can enable it. Push protection for your own account covers public repositories and is on by default. The bypass rules and the plan limits are on the GitHub secret scanning page.
06When a scanner finds a key
Consider any leaked secret immediately compromised. Do these in order:
- Revoke or rotate the key with its provider. This is the most important step.
- Check the provider's logs for use of the key.
- Only then think about rewriting history, which has side effects. The history cleanup page has the commands.
False alarms exist. Generic alerts, such as private keys and passwords, can have a higher rate of false positives or secrets used in tests. TruffleHog labels results as verified, unverified or unknown. A verified result was confirmed valid and active by API testing, so start there.
For the first hour after a leak, see what to do when a key leaked. If it went to a public repository, see a key exposed on GitHub.
07Keep fewer keys to find
The best scan is the one with nothing to report. Never put secret API keys in source code: bad actors continuously scan public repositories for Stripe API keys. Learn where to store API keys. If you want a refresher on the file that usually holds them, read what a .env file is.
08The short version
Use a local scanner or a pre-commit hook so a key never reaches Git. Keep GitHub scanning on as the second net. Revoke any key a scanner finds before you do anything else.
FAQ
What is secret scanning?
Software that searches code and Git history for credentials such as API keys, passwords and tokens. GitHub's version scans the entire Git history on all branches of a repository.
What is a secret scanner?
The tool that does the searching. Examples are TruffleHog, which discovers, classifies and validates secrets, and git-secrets, which rejects commits that match prohibited patterns.
Is GitHub secret scanning free?
For public repositories it runs automatically for free. Organization-owned private repositories need GitHub Secret Protection on Team or Enterprise Cloud. A private repository owned by a personal account is covered only on Enterprise Cloud with Managed Users or on Enterprise Server.
How do I use GitHub secret scanning?
On a repository with it enabled, alerts appear in the Security and quality tab. To turn it on, open the repository Settings, then Advanced Security, and click Enable to the right of Secret Protection. The page on GitHub secret scanning has the details.
How do I check for secrets in my GitHub repositories?
Read the alerts in the Security and quality tab of the repository. You can also scan a local clone with a tool such as TruffleHog.
What should I do when a scanner finds a key?
Revoke it with its provider first. Removing it from the code does not stop it being exploited.
Related guides
Sources
- GitHub docs, about secret scanning
- GitHub docs, about push protection
- GitHub docs, enabling secret scanning for your repository
- GitHub docs, remediating a leaked secret
- TruffleHog README
- ggshield getting started
- git-secrets README
- GitGuardian, State of Secrets Sprawl 2025
- Wiz, Shai-Hulud npm supply chain attack