Secret scanning
Secret scanning
A secret that reaches git is leaked: deleting the file later leaves it in history, and a push hands it to everyone with read access. So the repo scans for secrets at the two points where one can get in, with betterleaks (from the gitleaks authors; same rules and config format).
| When | What | How |
|---|---|---|
git commit | the staged changes | scripts/git-hooks/pre-commit (make hooks.install; make init turns it on) |
make ci, and CI on every push | every tracked file | make check-secrets (scripts/check-secrets.sh) |
| on demand | the whole git history | make secrets.history |
| on demand | any folder as it is on disk, ignored files included | make secrets.scan DIR=path |
make betterleaks.install puts the pinned, checksummed binary in
~/.local/bin (Linux and macOS). CI installs the same version with the
same checksum (.github/workflows/ci.yml). Locally, a missing binary skips
the scan with a warning; in CI it fails.
When it fires
- It is a real secret. Take it out of the file, and rotate it: once typed into a tracked file it may already be in a commit, a stash or an editor backup. Never add a real secret to the allowlist.
- It is not a secret (a placeholder, a test value, a public key).
Read the line, then add a regex for it to
.betterleaks.tomlwith a description that says what it is. Prefer the narrowest match: a regex for that value or line, not a whole path or a disabled rule.
Output is always redacted (--redact), so a scan in CI logs or a shared
terminal does not print the value it found.
Encrypted env files still leak comments
dotenvx encrypt (and tools like it) encrypt the value of each
KEY=value line. A commented-out line is text to them and is left as it
is:
STRIPE_SECRET_KEY="encrypted:BE9..." # encrypted
# OLD_STRIPE_SECRET_KEY=sk_live_abc... # committed as plaintext
This put live-format keys into a repo's history once (2026-11-13, found
by the first history scan). Before encrypting an env file, delete the
commented-out assignments; make check-secrets and the hook catch the
ones that are left, because they scan the encrypted file like any other.
Updating betterleaks
Bump VERSION and the four checksums in scripts/betterleaks-install.sh
and the version and Linux x64 checksum in .github/workflows/ci.yml,
from the release's checksums.txt. Pick a release at least three days
old, the same rule bunfig.toml applies to packages
(dependency-release-age.md).