detect-secrets is an aptly named module for (surprise, surprise) detecting
secrets within a code base.
However, unlike other similar packages that solely focus on finding secrets, this package is designed with the enterprise client in mind: providing a backwards compatible, systematic means of:
- Preventing new secrets from entering the code base,
- Detecting if such preventions are explicitly bypassed, and
- Providing a checklist of secrets to roll, and migrate off to a more secure storage.
This way, you create a separation of concern: accepting that there may currently be secrets hiding in your large repository (this is what we refer to as a baseline), but preventing this issue from getting any larger, without dealing with the potentially gargantuous effort of moving existing secrets away.
It does this by running periodic diff outputs against heuristically crafted regex statements, to identify whether any new secret has been committed. This way, it avoids the overhead of digging through all git history, as well as the need to scan the entire repository every time.
For a look at recent changes, please see the changelog.
Setting Up a Baseline
$ detect-secrets scan > .secrets.baseline
$ cat .pre-commit-config.yaml - repo: firstname.lastname@example.org:Yelp/detect-secrets rev: 0.10.1 hooks: - id: detect-secrets args: ['--baseline', '.secrets.baseline'] exclude: .*/tests/.*
Auditing a Baseline
$ detect-secrets audit .secrets.baseline
This is only applicable for upgrading baselines that have been created after version 0.9. For upgrading baselines lower than that version, just recreate it.
$ detect-secrets scan --update .secrets.baseline
detect-secrets is designed to be used as a git pre-commit hook, but you can also invoke
detect-secrets scan [path] directly (
path defaults to
. if not specified).
It should be noted that by default,
detect-secrets scan only operates on files that are tracked by git. So if you intend to scan files outside of a git repository, you will need to pass the
There are three components that you can setup, depending on your purposes. While all three are independent, you should pair the Secrets Baseline with either the client-side pre-commit hook, or the server-side secret scanner.
Client-side Pre-Commit Hook, that alerts developers when they attempt to enter a secret in the code base.
Server-side Secret Scanning, to periodically scan tracked repositories, and make sure developers didn't accidentally skip the pre-commit check.
Secrets Baseline, to whitelist pre-existing secrets in the repository, so that they won't be continuously caught through scan iterations.
Client-side Pre-commit Hook
See pre-commit for instructions to install the pre-commit framework. The example usage above has a sample installation configuration, with a whitelisted secrets baseline.
detect-secrets: This hook detects and prevents high entropy strings from entering the codebase.
Server-side Secret Scanning
Please see the detect-secrets-server repository for installation instructions.
$ pip install detect-secrets
Remember to initialize your baseline with the same plugin configurations as your pre-commit hook, and server-side secret scanner!
Another way of whitelisting secrets is through the inline comment
# pragma: whitelist secret.
API_KEY = "blah-blah-but-actually-not-secret" # pragma: whitelist secret def main(): print('hello world') if __name__ == '__main__' main()
This may be a convenient way for you to whitelist secrets, without having to regenerate the entire baseline again. Furthermore, this makes the whitelisted secrets easily searchable, auditable, and maintainable.
Current Supported Plugins
The current heuristic searches we implement out of the box include:
Base64HighEntropyString: checks for all strings matching the Base64 character set, and alerts if their Shannon entropy is above a certain limit.
HexHighEntropyString: checks for all strings matching the Hex character set, and alerts if their Shannon entropy is above a certain limit.
PrivateKeyDetector: checks to see if any private keys are committed.
BasicAuthDetector: checks to see if BasicAuth is used e.g.
KeywordDetector: checks to see if certain keywords are being used e.g.
See detect_secrets/ plugins for more details.
A Few Caveats
This is not meant to be a sure-fire solution to prevent secrets from entering the codebase. Only proper developer education can truly do that. This pre-commit hook merely implements several heuristics to try and prevent obvious cases of committing secrets.
Things that won't be prevented
- Multi-line secrets
- Default passwords that do not trigger the
paaassword = "paaassword")
One method that this package uses to find secrets is by searching for high entropy strings in the codebase. This is calculated through the Shannon entropy formula. If the entropy of a given string exceeds the preset amount, the string will be rejected as a potential secret.
This preset amount can be adjusted in several ways:
- Specifying it within the config file, for server scanning.
- Specifying it with command line flags (eg.
Lowering these limits will identify more potential secrets, but also create more false positives. Adjust these limits to suit your needs.