enh(secu): manage invalid-revision range error

[sc979]

Description

What are your needs or what are you planning to do in this PR?

enh(secu): manage invalid-revision range error

Resolves the "Invalid revision range" failures on the gitleaks job by replacing
gitleaks/gitleaks-action with the gitleaks binary (reused from the runner or installed
and verified) driven by a script that resolves the scan range defensively
(authenticated re-fetch + retry), scans every commit of the analyzed branch that is
not already on the destination branch, and fails closed.

Includes SECU-1249 (#76, merged into
this branch): gitleaks install aligned on the centreon-ubuntu-26.04 runner images.

Tests

centreon/centreon-documentation#5710
centreon/centreon-documentation#5711
https://github.com/centreon/delivery-tooling/pull/443

Tasks covered

1. Invalid revision range: event SHAs missing from the clone are re-fetched with
   the job token (env-scoped git config, never on disk nor on a command line), with a
   5-attempt retry and live-tip fallbacks.
2. Quality gate on the branch's own commits: a PR scans base..head, whatever the
   destination is called; secrets already on the destination never fail it.
3. Shallow PR checkout (ci(secu): speed up dependency and gitleaks scans #74): only the base side is deepened until the range is
   trustworthy, so no shallow boundary is scanned as a root.
4. Supported events: pull_request and workflow_dispatch only (whole ref history
   on dispatch); pull_request_target rejected before checkout; any other event fails.
   security-checks.yml runs on these two events only.
5. Fail closed: leaks, gitleaks errors, unresolvable ranges and unsupported events
   fail the job; .gitattributes cannot hide file contents (--text).
6. Least privilege: the job token is scoped to contents: read.
7. gitleaks install (SECU-1249): same version rule as the runner images (latest
   release published at least 4 days ago, read from the public releases feed without
   any token), runner binary reused when it matches, release verified against its
   checksums file, 8.30.1 fallback when the feed cannot be resolved.
8. Docs: CLAUDE.md describes the workflow and the Ubuntu 26.04 runners from feat(ci): run the centreon scans on the sized ubuntu 26.04 runners #75.

Quality gate

Every non-merge commit of the analyzed branch is scanned. Only the commits already on
the destination branch are excluded, whether or not they are also on other branches
(load, performance or security test branches…), so no new secret can reach the
destination unnoticed.

Destination branch	Analyzed branch	Gate
1 or more secrets	0 secrets	✅ OK
any	1 or more secrets	❌ KO

The workflow assumes no branch name (main, develop, dev-YY.MM.x…): the
destination comes from the event itself.

Supported events: pull_request (the quality gate) and workflow_dispatch (mostly to
debug the pipeline). Org usage, checked on 2026-10-07: 73 of the 76 non-archived
repositories (centreon + quanta-computing) call gitleaks-analysis.yml@main through
secu-secret-scan.yml, on exactly these two events. In this repository,
security-checks.yml now runs on these two events only (its push and schedule
triggers are removed). centreon/.github has no caller, and
quanta-computing/cxm-zone-probe is empty.

The branch is rebased on main (after #75): it keeps the runners of #75,
actions/checkout v7.0.1 with persist-credentials: false (#69, #71) and the shallow PR
checkout from #74 (fetch-depth = PR commits + 2, full clone otherwise). The job token is
scoped to contents: read only: the script calls no GitHub API, so the
pull-requests: read added for the action in #72 is dropped.

Scan range per event

The range is passed to gitleaks as --log-opts and validated with git log first.
Every range carries --text, so a repository's .gitattributes (e.g. * -diff)
cannot hide file contents from the scan.

Event	Range
pull_request	base..head, --no-merges: every commit not on the PR base, including commits merged in from other branches (gitleaks-action's --first-parent skipped them), excluding the base commits merged into the PR. A PR with an unrelated history scans its own history
workflow_dispatch	the ref's whole history, --no-merges: no destination to exclude
pull_request_target	job always fails, from a first step that runs before checkout: the event is not compliant with our security posture (the scan script refuses it too)
any other event (push, schedule, merge_group…)	job fails: not supported

An empty range (e.g. a PR whose head is already on its base) passes with a notice,
without running gitleaks.

Shallow PR checkout (#74)

Pull requests are checked out with fetch-depth = PR commits + 2, which holds every PR
commit. When the base branch moved further than that since the PR forked, the base side
does not reach the shared history yet, and a shallow boundary commit looks parentless:
gitleaks would scan its whole tree and report every pre-existing secret. So, for
pull_request, the range is trusted only once base..head holds no parentless commit:

• only the base side is deepened (--depth = PR commits + 1 + 32, 64 … 1024 from the
  base SHA, through the same authenticated fetch), so the PR side is not fetched again;
  --unshallow is the last resort (e.g. unrelated histories);
• a deepen fetch that brings nothing stops the round, and the retry loop below takes over.

In the tests, with main 100 commits ahead of a 1-commit PR, 3 deepen rounds fetch
about 130 base commits, and the clone stays shallow. workflow_dispatch keeps a full
clone (depth 0).

Re-fetch when hashes changed after checkout

actions/checkout pins its refs and can't be re-run in a loop. When the event's SHAs
are missing from the clone, the step re-fetches and retries, up to 5 attempts with a
5/10/15/20 s backoff:

• pull_request → refs/pull/<n>/head, the base branch, and the event's head/base
  SHAs if still served. A head (or base) SHA force-pushed away falls back to the live
  PR tip (or base branch tip), with a ::warning::.
• workflow_dispatch → all branch heads and the dispatched SHA. If it was
  force-pushed away, falls back to the live tip of the branch, with a ::warning::
  (branches only: a tag never falls back to a same-name branch).

Failed fetches are logged as ::warning::. If the range is still unresolvable, the job
fails and points to those warnings.

Credentials stay unpersisted. persist-credentials: false is kept as a hardening
measure, so the clone holds no token. The re-fetches authenticate with the job token,
set on each git fetch process only through env-scoped git config
(GIT_CONFIG_COUNT / KEY_0 / VALUE_0): never written to .git/config, never on a
command line, masked in the logs, and not exported to the gitleaks process.

gitleaks install

Same rule as runners/base-ubuntu-26.04/Dockerfile in centreon-images (#390):

• GITLEAKS_VERSION: "latest" is the newest vX.Y.Z release published at least 4 days
  before the run, read from the public releases feed (releases.atom): no token, no
  GitHub API call. A version can still be pinned.
• If the feed cannot be resolved, GITLEAKS_FALLBACK_VERSION (8.30.1) is used, with a
  gitleaks-version-fallback warning, so the run is not blocked.
• If the runner's gitleaks version matches, the runner's binary is kept (the
  centreon-ubuntu-26.04-* runners ship it). Otherwise the release for the runner's
  architecture (x64 / arm64) is installed and verified against the release's
  checksums file; a checksum mismatch fails the job.

Runner requirements for the install step: curl, python3, GNU date, sha256sum,
tar (present on ubuntu-26.04 and the centreon-ubuntu-26.04 images; to check on
quanta-security).

Build outcome

Situation	Job
No secrets in the scanned commits (PR: even with secrets on the destination)	✅ success
No commit to scan	✅ success
Secrets found in the scanned commits (gitleaks exit 2)	❌ fail
gitleaks error (any other exit, e.g. a broken .gitleaks.toml)	❌ fail — fail closed, the scan did not complete
Range unresolvable after all retries	❌ fail
pull_request_target	❌ fail, before checkout
Other event (push, schedule…)	❌ fail

Test coverage

Both run: steps are extracted verbatim from the workflow and run with bash -e,
as GitHub does. The scan runs against throwaway repos whose remote is served over smart
HTTP and rejects any request without the job token: a runner-like full clone
(fetch-depth: 0, no persisted credentials, detached HEAD) with commits pushed after
the clone, and a shallow PR checkout (merge commit fetched at depth PR commits + 2, as
actions/checkout does, main 100 commits ahead of the fork point).

Area	Cases
Quality gate (real gitleaks 8.30.1)	PR: secrets on main and dev-26.10.x + clean branch → OK; branch leak → KO, only the branch's file reported; after merging main that brought a new secret → OK; unrelated history → OK when clean, KO when it leaks. Dispatch: whole history scanned (KO on any secret in it, OK on a clean orphan branch)
Range selection	PR: base commits excluded, merged-in side branch scanned, unrelated history scans its own commits; dispatch on a branch and on a tag; head / base / dispatched SHA missing from the clone → retry
Shallow PR checkout (real gitleaks)	clean PR with main 100 commits ahead → pass, 3 base-side deepen rounds, no boundary commit scanned, no unshallow; PR's own leak reported (not main's); main merged in → main's secret not reported; leaking side branch reported; unrelated history with secrets on base → unshallow, pass; deepen with an invalid token → fail closed, one fetch per attempt, token not in argv
Re-fetch (authenticated remote)	negative control without token; PR head pushed after checkout; PR head / PR base / dispatched SHA force-pushed away → live tips; head and ref both gone → clean failure, no garbage in variables; backoff 5/10/15/20 s; invalid token → ::warning:: + failure; tag dispatch with its SHA gone → no fallback to a same-name branch
Fetch depth step	PR → commits + 2; other events → 0; checkout uses it; step order (reject, depth, checkout, install, scan)
Token hygiene	not under .git/, not in any git argv, not in gitleaks' environment, base64 header masked
Events	push, schedule, merge_group → fail (unsupported); pull_request_target rejected by the first step (before checkout) and by the script; security-checks.yml triggers on PR and dispatch only
Exit codes (stub)	0 pass; 2 fail; 1 / 126 fail; empty range → pass without running gitleaks
Real gitleaks 8.30.1	.gitattributes * -diff doesn't hide a leak (PR and dispatch); broken .gitleaks.toml → job fails
Install step	latest resolution (pre-release tags and releases under 4 days skipped), runner binary kept when it matches (8.30.1 / v8.30.1) and replaced otherwise (8.31.0, missing, distro build), pinned version (no feed read), feed fallback to 8.30.1 with a warning, checksum mismatch / missing checksums file → fail, arm64 tarball, unsupported architecture → fail, no token sent

Result: 131 / 131 passed on the rebased branch. Release downloads are served by a
curl stub from the real 8.30.1 tarball and checksums file; the feed parser also returns
8.30.1 on the real feed.

Not covered: a real GitHub runner (the PR's own security-checks run calls
gitleaks-analysis.yml@main, not this branch).

🤖 Generated with Claude Code

[sc979]

✅ Automated Review — Passed

This PR was reviewed using the Centreon automated review skill.

Complexity: high — Recommended reviewers: 2

No blocking issues found. Ready for human review.

Security review: no findings.

Areas that deserve careful human attention:

• .github/workflows/gitleaks-analysis.yml — compute_range() (range selected per event) and refetch() (authenticated re-fetch with persist-credentials: false).
• The job fails closed: gitleaks errors, unresolvable ranges and unsupported events fail it, and pull_request_target always fails before checkout.
• This PR's own security-checks run calls gitleaks-analysis.yml@main, so CI does not exercise the new workflow. Every consumer picks it up on merge.