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:
@@ -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 |
|
||||
Reference in New Issue
Block a user