feat!: migrate secret-scan from gitleaks to betterleaks

[nkg]

Why

betterleaks is gitleaks' successor, written from scratch by gitleaks' original author (Zach Rice) after he lost admin control of that repository and its name. It's MIT, he retains ownership, and it carries no license key requirement for org use — which is the same reason secret-scan.yml installed the OSS gitleaks binary rather than the paid official gitleaks-action.

BREAKING

The gitleaks-version input is replaced by betterleaks-version (default 1.8.1). A caller still passing gitleaks-version will fail validation.

Per the repo's precedent for breaking input changes, this bumps the major — docs move to @v3. release.yml derives the floating tag generically (v1.2.3 → v1), so a v3.0.0 tag creates v3 with no change needed there.

Compatibility

Verified against the actual v1.8.1 binary, not the docs:

• Every flag used here exists: --no-banner, --redact, --report-format=sarif, --report-path, --config, --exit-code, --log-opts, and git --staged --pre-commit
• Release tarballs are named identically in shape; both linux arches download and contain a top-level betterleaks binary (static ELF) — install step verified end-to-end
• Still reads .gitleaks.toml, GITLEAKS_CONFIG, .gitleaksignore (same fingerprint format) and gitleaks:allow comments as fallbacks, so existing consumer configs need no changes
• mise registry already carries betterleaks (via aqua, with cosign verification on install)
• Renovate keeps working: datasource=github-releases depName=betterleaks/betterleaks

Expect new findings

betterleaks reports ~98.6% recall on CredData vs gitleaks' ~70.4%. A repo that scanned clean may not any more. This repo was exactly that case:

scanner	full-history result	exit
gitleaks 8.30.1	no leaks found	0
betterleaks 1.8.1	leaks found: 1	1

The finding is a false positive — GRAFANA_ADMIN_PASSWORD=ci-validate, a documentation placeholder in examples/README.md:159 at commit 526db3a, matched by generic-password at low confidence.

Because such matches live in committed history, a betterleaks:allow comment on the current line can't clear them — the fingerprint has to be pinned. Hence the new .gitleaksignore. Note PR-diff mode is unaffected unless the offending line is touched, so this surprise lands on push/scheduled full-history runs, not on PRs.

Consumers hitting the same thing have two options, both verified:

• pin fingerprints in .gitleaksignore (preferred — keeps low-confidence detection on)
• set the new confidence: medium input (blunter; drops a whole tier)

Also changed

• mise.toml + lefthook.yml — local pre-commit/pre-push secret scans use betterleaks, so mise install on an existing clone swaps the binary
• SARIF artifact renamed gitleaks-sarif → betterleaks-sarif

Test plan

• actionlint clean
• yamllint .github/ .yamllint.yml clean (only pre-existing line-length warnings in claude-code-review.yml)
• Full-history scan green with .gitleaksignore (betterleaks git --redact --no-banner → exit 0)
• Staged/pre-commit mode green
• PR-diff mode (--log-opts=base..head) runs and writes SARIF
• Install step verified against both linux_x64 and linux_arm64 tarballs
• All pre-push hooks green

Not done

Betterleaks ships checksums.txt + a sigstore bundle and the install step still verifies nothing. Left out to keep this diff to the migration — worth a follow-up.

🤖 Generated with Claude Code

https://claude.ai/code/session_011c5RTvAwJB62bcvuARUqKr