detect-secrets

detect-secrets is Yelp’s enterprise-friendly secret scanner that uses a baseline approach to prevent new credential leaks. Unlike scanners that report all secrets, detect-secrets accepts existing secrets in a baseline file while blocking any new ones from being committed.

This pragmatic approach makes detect-secrets ideal for brownfield projects and large organizations that need immediate protection without requiring massive remediation efforts upfront.

What is detect-secrets?

detect-secrets scans git repositories and files to identify hardcoded credentials, API keys, and other secrets. The tool’s distinguishing feature is its baseline system: you create a baseline file containing hashes of all current secrets, then detect-secrets allows those secrets to pass while flagging anything new.

The scanner works by analyzing git diffs rather than scanning entire repositories on each run. This differential approach minimizes overhead and provides fast feedback in pre-commit hooks and CI pipelines. You see only what changed, not repeated warnings about historical issues.

detect-secrets uses a plugin architecture for secret detection. Each plugin targets specific secret patterns—AWS keys, private keys, Slack tokens, etc. You can enable built-in plugins or write custom regex-based detectors for proprietary credentials.

Key features

Baseline creation and auditing

The baseline file (.secrets.baseline) is a JSON document with hashes of every detected secret. When you re-scan, detect-secrets compares new findings against this baseline. Secrets already recorded pass through; new ones trigger failures. You commit this file to version control alongside your code.

The audit command supports diffing two baselines and generating statistical reports. You can label each finding, and those labels persist across re-scans — useful for tracking which secrets your team has reviewed versus which still need remediation.

27 built-in detectors

detect-secrets ships 27 built-in detectors across three detection strategies: regex-based rules for structured secrets like AWS keys and GitHub tokens, entropy detection for random-looking strings using Base64 and Hex analysis, and keyword detection that flags variable names tied to hardcoded credentials.

Pre-commit hook integration

Install detect-secrets as a pre-commit hook to scan staged changes before commits go through. If a developer tries to commit new secrets, the hook blocks the commit and shows the offending content. Only changes that match the baseline or contain no secrets can be committed.

The hook runs in seconds because it scans only staged changes, not the entire repository.

Inline allowlisting

Inline allowlisting lets developers suppress false positives directly in code with pragma comments. Add # pragma: allowlist secret to the end of a line, or // pragma: allowlist nextline secret before a line, to exclude specific findings.

You can also exclude files, lines, or secret values globally using --exclude-files, --exclude-lines, and --exclude-secrets regex flags.

Optional secret verification

detect-secrets can optionally verify discovered secrets by making network requests to the associated services. The --only-verified flag limits output to secrets confirmed as live credentials. This is off by default to avoid unexpected network traffic.

CI/CD integration

Run detect-secrets in CI pipelines to enforce secret policies on pull requests. The tool exits with a non-zero status code when new secrets are found, failing the build and preventing merges.

Configure CI to scan only the PR diff (fast) or the entire branch (comprehensive). Most teams scan diffs for quick feedback.

Getting started

When to use detect-secrets

detect-secrets fits best in enterprise environments with legacy codebases that already contain secrets. The baseline approach lets you prevent new leaks immediately while remediating old ones on your own schedule.

It’s a good pick if your team needs an audit trail of reviewed secrets, works in a regulated environment, or runs large monorepos where scanning speed matters.

For broader scanning beyond git repositories (Slack, S3, Docker images), look at TruffleHog. For simpler git-only scanning without baseline management, Gitleaks is a lighter option.

Frequently Asked Questions