
Dependency-free secrets scanner for source code and git history that detects leaked API keys, tokens, and private keys, with redacted output and a drop-in GitLab CI job.
A small, dependency-free secrets scanner for source code and git history, with a drop-in GitLab CI job.
It finds leaked API keys, tokens, private keys and passwords before they reach production, including secrets that were committed once and "removed" later but are still sitting in history.
$ secretscan scan . --history
[HIGH ] url-credentials deploy.sh:1 (commit 79831acaf3, Dev <[email protected]>)
Credentials embedded in a URL: Fake********
[HIGH ] aws-access-key-id settings.py:1 (commit 79831acaf3, Dev <[email protected]>)
AWS access key ID: AKIA************
2 potential secret(s) found.
In that demo the AWS key was deleted from settings.py in a later commit. A plain file scan says the repo is
clean, but the key is still recoverable with git log -p, so it is still leaked.
password = "..." rule.changeme, ${API_KEY}, {{ vault_token }} and <your-password>.--rev-range base..HEAD scans only new commits..secretscanignore (gitignore-style globs) and inline # secretscan:ignore.--fail-on severity threshold.pip install git+https://gitlab.com/DaveyD347/secrets-scanner.git
# or, from a clone
pip install -e ".[dev]"
secretscan scan # scan the current directory's files
secretscan scan path/to/repo --history # files + entire git history
secretscan scan . --history-only # history only
secretscan scan . --rev-range origin/main..HEAD # only commits not yet on main
secretscan scan . --format json -o findings.json
secretscan scan . --fail-on high # only fail on high/critical
secretscan rules # list rules
| Exit code | Meaning |
|---|---|
| 0 | No findings at or above --fail-on |
| 1 | Findings at or above --fail-on |
| 2 | Usage error (bad path, not a git repo, ...) |
Add an inline marker:
EXAMPLE_KEY = "..." # secretscan:ignore
Or create .secretscanignore at the repo root:
# test fixtures
tests/fixtures/
*.lock
Add the reusable job to any project:
include:
- remote: "https://gitlab.com/DaveyD347/secrets-scanner/-/raw/main/templates/secretscan.gitlab-ci.yml"
The job clones full history (GIT_DEPTH: 0), scans only the new commits on merge request pipelines and the
whole history otherwise, fails the pipeline on findings, and uploads gl-secret-detection-report.json as a
secret_detection report. On GitLab Ultimate those findings appear in the merge request security widget and
the vulnerability report; on other tiers the report is still kept as a downloadable artifact. Set
SECRETSCAN_FAIL_ON to tune the threshold.
This repository's own .gitlab-ci.yml lints, tests on Python 3.10 to 3.13 with coverage,
and runs the scanner against its own history.
src/secretscan/rules.py) are regular expressions. The first capture group is the secret.
Generic rules also set a minimum entropy so password = "aaaaaaaaaaaa" doesn't fire..git, node_modules, virtualenvs, binaries (NUL byte sniff),
files over 2 MB and anything in .secretscanignore.git log --all --reverse -p --unified=0 and parses the diff stream, tracking the
current commit, file and new-side line number from each @@ hunk header. Only + lines are checked, so
a secret is reported once, at the commit that introduced it, rather than once for every later commit.pip install -e ".[dev]"
pytest
ruff check . && ruff format --check .
Test fixtures never contain real credentials. The fake tokens in tests/fakes.py are assembled from pieces at
runtime so that the repository itself contains no complete token-shaped strings. That keeps the CI self-scan
clean and avoids tripping GitLab push protection.
MIT