sec(gitleaks): a low-entropy defaulted credential passes both required secret gates (BACKLOG #1091)

[wshallwshall]

Two files, 185 insertions: .gitleaks.toml and a new tests/test_gitleaks_credential_rule.py. No engine source, no workflow files.

The defect is in the control, not in the tree

This is not a live exposure. There are zero deployments and the tracked values are dev defaults. The defect is that the control cannot see the class — so the next credential, added by someone who trusts the gate, lands exactly the same way.

Two required gates both miss it, for different reasons:

• bandit does not parse .yaml or .ps1 at all.
• gitleaks' generic rule is entropy-gated, so a low-entropy default like ${VAR:-changeme} scores below threshold and passes.

The new rule keys on the shape of a defaulted secret rather than on its randomness.

Why the rule is narrow, and the negative that forced it

.github/workflows/release.yml carries nine id-token: write lines. Those are GitHub permissions, not credentials.

A naive token\s*[:=] rule reddens a required gate nine times on its first run — which is how a security control gets switched off rather than fixed. The narrowness is the point.

Three things about the author's own work, two of which nearly shipped

1. The tests run the scanner rather than reading the config. A text assertion that a rule is present cannot distinguish a working rule from a regex matching nothing — the same defect #1313 found in the sdist leak gate. A config gitleaks refuses to load now fails loudly instead of reading as "no findings".

2. The allowlist test caught a real defect. gitleaks reports the first capture group as Secret and matches allowlist regexes against it, so the rule reported Secret: "password" — the key name. Useless in a report and it silently broke the allowlist. Fixed with a non-capturing group plus secretGroup; findings now carry the actual default value.

3. The rule blocked the commit that introduced it — the fixtures are the detected shape, the same class as #1086. Resolved with the narrowest exemption that works: a paths entry scoped to this rule and this file, so the file stays covered by every other rule. Verified narrow — the rule still fires on compose.yaml:158.

Verification

• 7 passed in tests/test_gitleaks_credential_rule.py; ruff format and check clean; all pre-commit hooks passed, including gitleaks itself.
• Measured both directions on gitleaks 8.30.1: fires on docker/compose.yaml:158 and on a fresh ${VAR:-changeme} in .yaml and .ps1; silent on ${VAR} with no fallback and on .github/workflows/.
• Differential against the real tree: adds exactly one finding.
• Independently screened here over all 185 added lines with positive controls firing first: zero real credential shapes.

Not run, and stated rather than discovered later: the full suite on this branch. CI is the first execution of it.

Not measured and not asserted: the repo config already reports one pre-existing hit at docs/testing/master-test-plan/09-engine-api.md:553 under generic-api-key. Whether that is live in the CI gate depends on how CI invokes gitleaks — git mode versus --no-git changes what is scanned. Out of scope here and unchecked.

Cut clean from origin/main at 5eb261de, 1 ahead, 0 behind. Touches no docs/BACKLOG.md, so it does not collide with #539, #542 or the residuals branch.

Co-Authored-By: Claude Opus 5 noreply@anthropic.com

🤖 Generated with Claude Code

[wshallwshall]

Closing. Superseded by a placement fix, not abandoned — and the red gate was correct throughout.

The decision, by the rule's author

A leaked secret is compromised the moment it is pushed — history is correct for it.
A defaulted credential is a property of the shipped artifact — fix the tip and it is gone.

So putting a tip-property lint inside a full-history secret scanner is not a tuning problem, it is a category error — and the permanently-red gate is that error reporting itself correctly. 12 of 14 historical revisions matching was never noise to be silenced; it was the scanner doing its job on a rule that does not belong to it.

Remedy: drop mefor-defaulted-credential from .gitleaks.toml and re-implement it tip-scoped, the way this repo already does its other lints. Every default gitleaks rule is untouched and still runs at fetch-depth: 0, which is right for them. Coverage moves surface, it does not move away.

What was measured on the way here

• The gate runs gitleaks detect with fetch-depth: 0 and no --no-git — full history, and the workflow comment says so.
• The tip is genuinely clean: 99650504 is an ancestor of the head and compose.yaml:156 reads POSTGRES_USER. The fix was never lost — I nearly reported that it was, and checked.
• The failing run was on the current head, not a stale job. I checked that too, having first read an older job's log.

That compose fix stands and was always the real defect. It carries into the rebuild.

One thing worth recording about how this was decided

The author's earlier candidate needed a gitleaks 8.30.1 feature test that was denied, and they refused to recommend a remedy on an unrun test. The placement fix removes the need for that answer entirely:

I am not routing around the denial; I stopped needing the answer.

My own --log-opts suggestion was withdrawn for the same reason one level up: it bounded the whole scan to narrow one rule, so its cost fell on the rules that were working.

Closing rather than parking, because a permanently-red PR reads as in-progress when it is superseded. #1091 remains open and the work continues on a rebuilt branch.