decision: scheduled gitleaks sweep — drop it (rely on per-PR range) or scope it to main? (blocks #721)

[scottschreckengaust]

Decision needed: what to do with the scheduled full-history gitleaks sweep

Blocks/scopes #721. Splitting the decision out from the implementation because there's a real security trade-off that a reviewer/owner should ratify before code lands.

Background — how the three gitleaks tasks are wired today

Surface	Task invoked	Scope	Enforcement
PR gate (security-pr.yml, required check "Secrets, deps, and workflow scan")	security:secrets:range	commits in origin/$BASE..HEAD (the PR's own diff)	Blocks merge (#327/#330)
Scheduled weekly (security.yml → mise run security)	security:secrets (full)	all fetched refs (runner is fetch-depth: 0)	Files a failure issue; does not gate PRs
Local pre-push (hooks:pre-push:security → mise run security)	security:secrets (full)	all fetched refs	Local only

The problem (surfaced in #721 / #593)

The scheduled security:secrets runs bare gitleaks git . --no-banner --redact with no --log-opts, so it scans secrets across every fetched ref — including unmerged, no-PR branches. A stray/abandoned branch (e.g. an AWS account id in a doc on feat/agentcore-gateway-mcp, a 381-commit spike with no PR) reddens the mainline scheduled suite even though nothing reached main. Confirmed empirically:

gitleaks git . --no-banner --redact               → leaks found: 4  (all from an unmerged branch)
gitleaks git . --no-banner --redact --log-opts=HEAD → no leaks found (main history is clean)

The decision

The PR gate already uses the range scan and is a required check — no change needed there. The question is only about the scheduled/pre-push full sweep:

Option 1 — Remove the full sweep; rely solely on the per-PR range scan.

• ✅ Simplest. Nothing to scope; delete security:secrets from the scheduled security aggregate (and pre-push).
• ⚠️ Loses the historical backstop. The range gate only exists since feat(ci): require fast security scans on every PR — secrets/deps/workflow gate (#327) #330 and only scans each PR's diff going forward. A secret committed to main before feat(ci): require fast security scans on every PR — secrets/deps/workflow gate (#327) #330, or introduced via any non-PR path (direct push, admin merge, force-push, imported history), would never be re-audited. No safety net over main's full history.

Option 2 — Keep the full sweep, but scope it to the mainline (--log-opts="HEAD").

• ✅ Retains a full-history backstop over main (verified: scans main's 279-commit history and fail-closes on a planted mainline secret).
• ✅ Excludes other branches' unmerged history — kills the fix(ci): scheduled gitleaks sweep flags unmerged-branch history — scope to main + require per-PR secret check #721 false-positive class.
• ✅ One-line change; pre-push still scans the developer's own branch commits.
• ⚠️ A secret living only in unmerged branch history is no longer caught by the sweep — acceptable because the required per-PR range gate catches it at merge time, on the actual diff (where you want the gate to fire).
• 🪤 Gotcha discovered while prototyping: scope with HEAD, not a ref-pattern like --remotes=origin/main — the latter matches no ref in a plain worktree and walks 0 commits, silently turning the scan into a fail-open no-op. HEAD always walks the real checked-out history (which is main in the scheduled run).

Recommendation

Option 2. Unlike a redundant pin (where an in-path gate makes a floor pointless), the full sweep is not redundant with the range gate: the range gate is recent and diff-only, so it cannot see main's pre-#330 history or non-PR paths. Option 2 keeps that unique backstop while removing the false-positive drag. Option 1 trades away real coverage for marginal simplicity.

Whichever is chosen, #721 implements it

• Option 1 → drop security:secrets from the security aggregate (+ pre-push), update docs, note the coverage gap accepted.
• Option 2 → set security:secrets run to gitleaks git . --no-banner --redact --log-opts="HEAD", comment the rationale + the --remotes fail-open trap, keep :range and :staged unchanged.

Acceptance for THIS issue

• A maintainer/owner selects Option 1 or Option 2 (or a third approach) with a one-line rationale, so fix(ci): scheduled gitleaks sweep flags unmerged-branch history — scope to main + require per-PR secret check #721 can implement without re-litigating the trade-off.

References

#721 (implementation), #593 (failure symptom), #327 / #330 (required per-PR range gate), #335 / #336 (prior merge_group range-scoping — the other half of this split), ADR-003 (governance).

[scottschreckengaust]

Decision: Option 2 — scope the sweep to the mainline via --log-opts="HEAD"

Ratified by @scottschreckengaust (repo owner). Rationale, as this issue asks for:

The full sweep is not redundant with the range gate, so dropping it (Option 1) would give up real coverage. The range gate only exists since #330 and only ever sees each PR's own diff, so it cannot re-audit main's pre-#330 history or anything that arrived by a non-PR path (direct push, admin merge, imported history). Option 2 keeps that unique backstop while removing the false-positive drag.

Both directions verified empirically

This issue's recommendation rests on the sweep still fail-closing on a mainline secret. Confirmed against the real mise run security:secrets task (not a bare gitleaks call), with a detectable account id planted in a local commit:

scope	mainline history clean	planted secret
--log-opts="HEAD"	269 commits scanned. no leaks found (exit 0)	leaks found: 1, exit 1
--remotes=origin/main	0 commits scanned. no leaks found	0 commits scanned — fail-OPEN

The --remotes trap this issue documents reproduces exactly: 0 commits walked, silently green. Worth keeping in the task comment, which #721 now does.

One addition to the decision record: HEAD is not interchangeable with main

#721 offers --first-parent main or HEAD as equivalent options. They are equivalent on the scheduled surface (the runner checks out main, so HEAD is main), but they diverge on pre-push, and only HEAD is correct there:

--log-opts	secret in a developer's own unpushed commit
"HEAD"	exit 1 — blocks the push
"main"	exit 0 — push proceeds

main walks mainline only and therefore skips the commits being pushed, making the pre-push hook a no-op precisely when it should fire. Since security:secrets is shared by the scheduled sweep and hooks:pre-push:security (per this issue's own wiring table), the choice must satisfy both surfaces — HEAD does, main does not. Recommend this distinction be treated as part of the ratified decision, not an implementation detail.

Note for #721: Part 2 is already done

"Secrets, deps, and workflow scan" is already a required check on the main ruleset (id 14980587), so #721's "do not land Part 1 without Part 2" caveat is satisfied and Part 1 can ship alone.

Implementation in progress on fix/721-gitleaks-mainline-scope; this issue can close once that lands.

How this surfaced

Five rebased PR branches (#673, #674, #679, #680, #681) could not be pushed — the pre-push hook ran the unscoped sweep and failed on origin/feat/agentcore-gateway-mcp history (the same 381-commit no-PR spike branch named in #721). This is the local-surface half of the same bug: the pre-push gate was stricter than the merge gate, blocking pushes CI would have passed.