G9: reusable gitleaks secret scan, config and docs

Add a reusable workflow that downloads a pinned, checksum-verified gitleaks
and scans the pushed commits, the PR's commits, or the current tree. Logs
show only a count, never the rule, file, line or value, because the logs
are public. This repo's caller is manual-only until S8 passes.

.gitleaks.toml extends the default rules and allowlists Helm checksum/*
annotations. docs/ci-cd/secret-scanning.md covers usage, what to do when it
fails, and the policy for history scans (done privately, not in CI).

Tested locally by running the step verbatim in a container against
throwaway repos: a planted fake token fails on push, new-branch push and PR;
clean ranges, checksum annotations and this repo's tree pass; a bad
checksum fails; the value never appears in the output. actionlint and
yamllint pass.

Refs DevOps/software-infrastructure#57

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-14 18:44:40 -05:00
co-authored by Claude Opus 5.5
parent 1b197efc64
commit ef693ffd97
4 changed files with 249 additions and 0 deletions
+103
View File
@@ -0,0 +1,103 @@
# Secret scanning (G9)
Refs: DevOps/software-infrastructure#57.
CI runs [gitleaks](https://github.com/gitleaks/gitleaks) to stop new secrets
from being committed. Most eom.dev repos and their Actions logs are public, so
the check is built never to show a secret, or where one is, in a log.
## Files
| File | What it is |
|---|---|
| `.gitea/workflows/reusable-secret-scan.yaml` | Reusable workflow (`workflow_call`). Downloads a pinned gitleaks release, checks its SHA-256, and scans. |
| `.gitea/workflows/secret-scan.yaml` | This repo's caller. Manual-only until S8 (#41) passes, then `push` to `main` and `pull_request`. |
| `.gitleaks.toml` | This repo's config: gitleaks' default rules plus allowlists for known false positives. |
## What gets scanned
| Event | Scope |
|---|---|
| `push` | The pushed commits (`before..sha`). If the push created the branch, or `before` isn't in the clone, the current tree. |
| `pull_request` | The PR's commits (`base..head`). |
| Anything else (manual runs) | The current tree only. |
**CI doesn't scan full history.** A history scan of a public repo would put old
findings into a public log. History scans are done privately (see below).
## What the log shows
By default, only the number of possible secrets and the commit range or tree
that was scanned. It never shows the rule, file, line or value. The failure
message prints the command to run locally to see details:
```bash
docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:v8.30.1 git --redact -v /repo
```
`show-details: true` prints the rule, file and line (values stay redacted). Use
it only in private repos.
## Using it from another repo
Add a caller workflow and, if needed, a `.gitleaks.toml` at the repo root
(gitleaks picks it up from the scanned directory):
```yaml
name: secret-scan
on:
push:
branches: [main]
pull_request:
concurrency:
group: secret-scan-${{ github.ref }}
cancel-in-progress: true
jobs:
scan:
uses: DevOps/software-infrastructure/.gitea/workflows/reusable-secret-scan.yaml@main
```
Calling it from another repo hasn't been tried on this Gitea yet. G2 (#50)
checks how the runner resolves cross-repo `uses:` and from private repos, and
updates this section.
Inputs:
| Input | Default | Notes |
|---|---|---|
| `gitleaks-version` | `8.30.1` | Change `gitleaks-sha256` with it. |
| `gitleaks-sha256` | SHA-256 of the 8.30.1 linux x64 tarball | From the release's `checksums.txt`. Same value as `images/ci-tools/Dockerfile`. |
| `show-details` | `false` | See above. |
Once the CI tools image (G1, #49) is published, the job can run in it and skip
the download.
## If the check fails
1. Run the local command above to see what was found.
2. **If it's a real secret, rotate it first.** Deleting it from git, or
rewriting history, doesn't make it safe once it has been pushed to a public
repo. Then move it to the vault or an Actions secret.
3. **If it's a false positive**, add a narrow allowlist entry to the repo's
`.gitleaks.toml` with a `description` saying why it isn't secret. Prefer a
regex on the line or a path over disabling a rule. For a single known
finding, its fingerprint can go in `.gitleaksignore`. In a public repo that
names the file and commit, so use it only for false positives.
Never paste a finding into an issue, commit message, PR, or Discourse post.
## Known false positives
| Pattern | Why it isn't secret | Allowlisted in |
|---|---|---|
| Helm `checksum/<name>: <64 hex>` annotations | SHA-256 of a rendered manifest, used to restart pods on change | `.gitleaks.toml` here |
| Stripe `publishable-key="pk_..."` in HTML | Publishable keys are public by design | DevOps/www, when its caller is added |
## History scans
Done privately with the same gitleaks version, all refs, and `--redact`.
Results go only in the private assessment, never in public issues or logs.
| Date | Repos | Result |
|---|---|---|
| 2026-11-14 | ansible-role-{gitea,eom,www,dex,discourse,mcp-servers,prometheus,listmonk}, www, software-infrastructure | Done; results are in the private assessment |