detect_secrets.md

Using the detect-secrets pre-commit hook

We use detect-secrets to check that no secrets are accidentally committed. The detect-secrets package does its best to prevent accidental committing of secrets, but it may miss things. Instead, focus on good software development practices! See the definition of a secret for further information.

Initial setup

This pre-commit hook requires you to generate a baseline file if one is not already present within the root directory. To create the baseline file, run the following at the root of the repository:

detect-secrets scan > .secrets.baseline

Next, audit the baseline that has been generated by running:

detect-secrets audit .secrets.baseline

When you run this command, you'll enter an interactive console. This will present you with a list of high-entropy string and/or anything which could be a secret. It will then ask you to verify whether this is the case. This allows the hook to remember false positives in the future, and alert you to new secrets.

Definition of a "secret" according to detect-secrets

The detect-secrets documentation, as of January 2021, says it works:

...by running periodic diff outputs against heuristically crafted [regular expression] statements, to identify whether any new secret has been committed.

This means it uses regular expression patterns to scan your code changes for anything that looks like a secret according to the patterns. By definition, there are only a limited number of patterns, so the detect-secrets package cannot detect every conceivable type of secret.

To understand what types of secrets will be detected, read the detect-secrets documentation on caveats, and the list of supported plugins. Also, you should use secret variable names with words that will trip the KeywordDetector plugin; see the [DENYLIST variable for the full list of words][detect-secrets-keyword-detector].

If pre-commit detects secrets during commit

If pre-commit detects any secrets when you try to create a commit, it will detail what it found and where to go to check the secret.

If the detected secret is a false positive, there are two options to resolve this, and prevent your commit from being blocked:

• inline allowlisting of false positives (recommended); or
• updating the .secrets.baseline to include the false positives.

In either case, if an actual secret is detected (or a combination of actual secrets and false positives), first remove the actual secret. Then following either of these processes.

Inline allowlisting (recommended)

To exclude a false positive, add a pragma comment such as:

secret = "Password123"  # pragma: allowlist secret

or

#  pragma: allowlist nextline secret
secret = "Password123"

If the detected secret is actually a secret (or other sensitive information), remove the secret and re-commit; there is no need to add any pragma comments.

If your commit contains a mixture of false positives and actual secrets, remove the actual secrets first before adding pragma comments to the false positives.

Updating .secrets.baseline

To exclude a false positive, you can also update the .secrets.baseline by repeating the same two commands as in the initial setup.

During auditing, if the detected secret is actually a secret (or other sensitive information), remove the secret and re-commit. There is no need to update the .secrets.baseline file in this case.

If your commit contains a mixture of false positives and actual secrets, remove the actual secrets first before updating and auditing the .secrets.baseline file.

---

Credit: This document has been adapted from the govukcookiecutter.