detect-secrets scan: Build a Secrets Baseline
detect-secrets scan walks the repo for high-entropy strings and known secret patterns and writes the results to a .secrets.baseline file.
Yelp's detect-secrets takes a baseline-first approach: scan once to record every candidate, then audit and gate on anything new. It is the common pre-commit secrets tool.
What it does
detect-secrets scan runs entropy and regex plugins over tracked files and emits a JSON baseline listing each potential secret by file, line, and type. --baseline updates an existing file, surfacing only newly added candidates. It does not call out to providers; it is pattern/entropy based.
Common usage
# create the baseline
detect-secrets scan > .secrets.baseline
# update an existing baseline (only new candidates appear)
detect-secrets scan --baseline .secrets.baseline
# exclude paths
detect-secrets scan --exclude-files '.*\.lock$' > .secrets.baselineOptions
| Flag | What it does |
|---|---|
| --baseline <file> | Update this baseline instead of scanning fresh |
| --exclude-files <regex> | Skip files matching the regex |
| --exclude-lines <regex> | Skip lines matching the regex |
| --all-files | Scan all files, not just git-tracked ones |
| --disable-plugin <name> | Turn off a detector, e.g. KeywordDetector |
| --slim | Smaller baseline without line-content snippets |
In CI
In CI, run detect-secrets scan --baseline .secrets.baseline and fail if the baseline would change (the pre-commit hook does this). Commit the .secrets.baseline so the diff-based gate is reproducible. It is entropy-based, so it has more false positives than verification tools; that is why it is paired with audit.
Common errors in CI
"The baseline file was modified" in the pre-commit hook means new candidates appeared; run scan and audit them. A flood of false positives usually means an unexcluded lockfile or minified bundle; add --exclude-files. "No plugins to scan with" means every plugin was disabled.