From ef693ffd97e3a4b6623577fa2d5d088dbfdd1992 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 18:44:40 -0500 Subject: [PATCH] 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 --- .gitea/workflows/reusable-secret-scan.yaml | 112 +++++++++++++++++++++ .gitea/workflows/secret-scan.yaml | 23 +++++ .gitleaks.toml | 11 ++ docs/ci-cd/secret-scanning.md | 103 +++++++++++++++++++ 4 files changed, 249 insertions(+) create mode 100644 .gitea/workflows/reusable-secret-scan.yaml create mode 100644 .gitea/workflows/secret-scan.yaml create mode 100644 .gitleaks.toml create mode 100644 docs/ci-cd/secret-scanning.md diff --git a/.gitea/workflows/reusable-secret-scan.yaml b/.gitea/workflows/reusable-secret-scan.yaml new file mode 100644 index 0000000..5a75bce --- /dev/null +++ b/.gitea/workflows/reusable-secret-scan.yaml @@ -0,0 +1,112 @@ +# Reusable secret scan (gitleaks). DevOps/software-infrastructure#57 (G9). +# Usage and policy: docs/ci-cd/secret-scanning.md. +# +# What it scans: +# push the pushed commits (before..sha); the current tree if the +# push created the branch or "before" can't be found +# pull_request the PR's commits (base..head) +# anything else the current tree only (not history) +# +# Repos are public and so are their Actions logs, so by default the log shows +# only how many possible secrets were found, never which file, line or rule. +# Run gitleaks locally to see details (the command is printed on failure). +# Full-history scans are done privately, not in CI. + +name: reusable-secret-scan + +on: + workflow_call: + inputs: + gitleaks-version: + description: gitleaks release to download. Change gitleaks-sha256 with it. + type: string + default: "8.30.1" + gitleaks-sha256: + description: SHA-256 of gitleaks__linux_x64.tar.gz from the release's checksums file. + type: string + default: "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb" + show-details: + description: Print rule, file and line (values stay redacted). Only for private repos. + type: boolean + default: false + +permissions: + contents: read + +jobs: + gitleaks: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + with: + fetch-depth: 0 + + - name: Scan for secrets + env: + GITLEAKS_VERSION: ${{ inputs.gitleaks-version }} + GITLEAKS_SHA256: ${{ inputs.gitleaks-sha256 }} + SHOW_DETAILS: ${{ inputs.show-details }} + EVENT: ${{ github.event_name }} + SHA: ${{ github.sha }} + BEFORE: ${{ github.event.before }} + BASE_SHA: ${{ github.event.pull_request.base.sha }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + run: | + set -euo pipefail + tmp="${RUNNER_TEMP:-/tmp}/secret-scan" + mkdir -p "$tmp" + + url="https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" + curl -fsSL --retry 3 -o "$tmp/gitleaks.tgz" "$url" + echo "${GITLEAKS_SHA256} $tmp/gitleaks.tgz" | sha256sum -c --quiet - + tar -xzf "$tmp/gitleaks.tgz" -C "$tmp" gitleaks + gl="$tmp/gitleaks" + + is_commit() { [ -n "$1" ] && ! [[ "$1" =~ ^0+$ ]] && git cat-file -e "$1^{commit}" 2>/dev/null; } + + scope=(dir .) + what="current tree" + case "$EVENT" in + pull_request|pull_request_target) + if is_commit "$BASE_SHA" && is_commit "$HEAD_SHA"; then + scope=(git "--log-opts=${BASE_SHA}..${HEAD_SHA}" .) + what="commits ${BASE_SHA:0:8}..${HEAD_SHA:0:8}" + fi ;; + push) + if is_commit "$BEFORE" && is_commit "$SHA"; then + scope=(git "--log-opts=${BEFORE}..${SHA}" .) + what="commits ${BEFORE:0:8}..${SHA:0:8}" + fi ;; + esac + + args=(--no-banner --no-color --redact=100 --exit-code=3 --log-level=error + --report-format=json --report-path="$tmp/report.json") + if [ "$SHOW_DETAILS" = "true" ]; then args+=(--verbose); fi + + echo "Scanning ${what} with gitleaks ${GITLEAKS_VERSION}" + set +e + "$gl" "${scope[@]}" "${args[@]}" >"$tmp/out.log" 2>&1 + rc=$? + set -e + + case "$rc" in + 0) + echo "No secrets found." ;; + 3) + n=$(grep -o '"RuleID"' "$tmp/report.json" | wc -l) + if [ "$SHOW_DETAILS" = "true" ]; then cat "$tmp/out.log"; fi + echo "::error::Secret scan found ${n} possible secret(s) in the ${what}." + echo "Details are not printed here because this log may be public." + echo "To see them, run gitleaks on your checkout, for example:" + img="ghcr.io/gitleaks/gitleaks:v${GITLEAKS_VERSION}" + echo " docker run --rm -v \"\$PWD:/repo\" ${img} ${scope[0]} --redact -v /repo" + echo "If it is a real secret, rotate it first: removing it from git does not make it safe." + echo "If it is a false positive, add an allowlist entry to .gitleaks.toml" + echo "(see docs/ci-cd/secret-scanning.md in DevOps/software-infrastructure)." + exit 1 ;; + *) + cat "$tmp/out.log" + echo "::error::gitleaks failed to run (exit ${rc})." + exit "$rc" ;; + esac diff --git a/.gitea/workflows/secret-scan.yaml b/.gitea/workflows/secret-scan.yaml new file mode 100644 index 0000000..5b2ebbb --- /dev/null +++ b/.gitea/workflows/secret-scan.yaml @@ -0,0 +1,23 @@ +# Secret scan for this repo. DevOps/software-infrastructure#57 (G9). +# +# Manual-only for now: the shared runner is still being stabilised (S3-S8, +# #36-#41). After S8 passes, replace the trigger with: +# +# push: +# branches: [main] +# pull_request: +# +# A manual run scans the current tree, not history. + +name: secret-scan + +on: + workflow_dispatch: + +concurrency: + group: secret-scan-${{ github.ref }} + cancel-in-progress: true + +jobs: + scan: + uses: ./.gitea/workflows/reusable-secret-scan.yaml diff --git a/.gitleaks.toml b/.gitleaks.toml new file mode 100644 index 0000000..bb32019 --- /dev/null +++ b/.gitleaks.toml @@ -0,0 +1,11 @@ +# gitleaks configuration. DevOps/software-infrastructure#57 (G9). +# Default rules, plus allowlists for known false positives. +# Policy and how to add an entry: docs/ci-cd/secret-scanning.md. + +[extend] +useDefault = true + +[[allowlists]] +description = "Helm checksum/* annotations are SHA-256 hashes of rendered manifests, not secrets" +regexTarget = "line" +regexes = ['''checksum/[A-Za-z0-9._-]+:\s*["']?[0-9a-f]{64}["']?\s*$'''] diff --git a/docs/ci-cd/secret-scanning.md b/docs/ci-cd/secret-scanning.md new file mode 100644 index 0000000..7e6d16c --- /dev/null +++ b/docs/ci-cd/secret-scanning.md @@ -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/: <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 |