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).

WhenWhatHow
git committhe staged changesscripts/git-hooks/pre-commit (make hooks.install; make init turns it on)
make ci, and CI on every pushevery tracked filemake check-secrets (scripts/check-secrets.sh)
on demandthe whole git historymake secrets.history
on demandany folder as it is on disk, ignored files includedmake 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

  1. 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.
  2. It is not a secret (a placeholder, a test value, a public key). Read the line, then add a regex for it to .betterleaks.toml with 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).