From be96f4aa55671c24d3dafa7a0501de1afbf2c440 Mon Sep 17 00:00:00 2001 From: Jean-Paul van Ravensberg <14926452+DevSecNinja@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:00:32 +0100 Subject: [PATCH 1/5] feat(lint): add reusable secret-scan workflow that runs only gitleaks secret-scan.yml calls lint.yml (via the \$/ self-repository syntax) with gitleaks on and every other linter off, so secret-scan callers no longer keep a disable list that misses linters added to lint.yml later. tests/secret-scan-wrapper.py fails CI when the wrapper misses one. This repository's secret-scan caller now uses the wrapper. Closes #549 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/actionlint.yaml | 8 ++ .github/workflows/secret-scan-caller.yml | 16 +-- .github/workflows/secret-scan.yml | 63 +++++++++++ .mise.toml | 1 + docs/architecture.md | 89 +++++++++------- tests/secret-scan-wrapper.py | 127 +++++++++++++++++++++++ 6 files changed, 251 insertions(+), 53 deletions(-) create mode 100644 .github/actionlint.yaml create mode 100644 .github/workflows/secret-scan.yml create mode 100644 tests/secret-scan-wrapper.py diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml new file mode 100644 index 00000000..790fcd90 --- /dev/null +++ b/.github/actionlint.yaml @@ -0,0 +1,8 @@ +--- +# actionlint configuration: https://github.com/rhysd/actionlint/blob/main/docs/config.md +paths: + .github/workflows/secret-scan.yml: + ignore: + # actionlint (1.7.12) predates GitHub's `$/` self-repository syntax for + # reusable workflow calls (July 2026). Drop this once it supports it. + - 'reusable workflow call "\$/\.github/workflows/lint\.yml" at "uses" is not following the format' diff --git a/.github/workflows/secret-scan-caller.yml b/.github/workflows/secret-scan-caller.yml index 0a9dd08b..1acf347a 100644 --- a/.github/workflows/secret-scan-caller.yml +++ b/.github/workflows/secret-scan-caller.yml @@ -23,7 +23,8 @@ concurrency: jobs: gitleaks: # Local reference validates reusable workflow changes in this repository. - uses: ./.github/workflows/lint.yml + # secret-scan.yml runs only gitleaks and keeps every other linter off. + uses: ./.github/workflows/secret-scan.yml permissions: contents: read security-events: write @@ -31,16 +32,3 @@ jobs: # renovate: datasource=github-releases depName=jdx/mise mise-version: "2026.10.19" lint-config-dir: config-sync/files - # History findings only report; this fails the run when the scan or the - # code scanning upload fails, so a silent gap can't look green. - lint-fail-on-error: true - lint-dprint: false - lint-yamlfmt: false - lint-yamllint: false - lint-actionlint: false - lint-go: false - lint-shellcheck: false - lint-shfmt: false - lint-checkov: false - lint-trivy: false - lint-zizmor: false diff --git a/.github/workflows/secret-scan.yml b/.github/workflows/secret-scan.yml new file mode 100644 index 00000000..2c42c90f --- /dev/null +++ b/.github/workflows/secret-scan.yml @@ -0,0 +1,63 @@ +--- +name: Reusable — Secret scan + +# Runs only the gitleaks job of the reusable Lint workflow, with every other +# linter switched off here, so callers don't keep their own list of linters to +# disable and a linter added to lint.yml later never starts running in them. +# tests/secret-scan-wrapper.py fails when lint.yml gains a linter input this +# workflow doesn't turn off. gitleaks behaves exactly as in lint.yml (see +# docs/architecture.md): pull requests scan their own commits, other events +# scan the full history, public repositories send history findings to code +# scanning (category `gitleaks/history`) and private ones to the job summary. +on: + workflow_call: + inputs: + mise-version: + description: "mise version to install" + required: true + type: string + lint-config-dir: + description: "Directory containing an optional .gitleaks.toml" + required: false + type: string + default: "" + lint-fail-on-error: + description: "Fail when the scan or the code scanning upload fails (history findings only report)" + required: false + type: boolean + default: true + +permissions: + contents: read + +jobs: + gitleaks: + # `$/` (self-repository syntax) resolves to this workflow's own repository + # at the commit that is running, so a caller pinning secret-scan.yml@ + # gets lint.yml from that same commit, and this repository's caller tests + # local changes to both. `./` is workspace-relative, so it isn't + # guaranteed to resolve to this repository when another repository calls + # this workflow, and an `owner/repo/...@` pin would lag behind + # lint.yml. actionlint doesn't know `$/` yet: .github/actionlint.yaml + # ignores that one error. + uses: $/.github/workflows/lint.yml + permissions: + contents: read + # Full-history findings of public repositories go to code scanning. + security-events: write + with: + mise-version: ${{ inputs.mise-version }} + lint-config-dir: ${{ inputs.lint-config-dir }} + lint-fail-on-error: ${{ inputs.lint-fail-on-error }} + lint-gitleaks: true + lint-dprint: false + lint-yamlfmt: false + lint-yamllint: false + lint-actionlint: false + lint-go: false + lint-shellcheck: false + lint-shfmt: false + lint-checkov: false + lint-trivy: false + lint-zizmor: false + lint-config-drift: false diff --git a/.mise.toml b/.mise.toml index 9bd7dcc7..fabc4208 100644 --- a/.mise.toml +++ b/.mise.toml @@ -33,6 +33,7 @@ run = [ "bash ./tests/release-please-auth-contract.sh", "bash ./tests/automation-app-contract.sh", "uv run --script ./tests/app-key-confinement.py", + "uv run --script ./tests/secret-scan-wrapper.py", "bash ./tests/lint-job-modes-contract.sh", "bash ./tests/open-pr-push.sh", "bash ./tests/open-pr-api-commit.sh", diff --git a/docs/architecture.md b/docs/architecture.md index 97dbd4de..c86725b8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -114,45 +114,8 @@ on the event (v4.1.0+): Internal repositories, whose logs every enterprise member can read, and a failed visibility lookup count as public. Repositories whose Lint caller runs on pull requests only get the full-history - scan from a second caller, after each merge, weekly and on dispatch, with every - other linter off (this repository's `secret-scan-caller.yml`). A Lint caller - that also runs on push already scans the history there, so drop `push` below. - -```yaml -name: Secret scan -on: - push: - branches: ["main"] - schedule: - - cron: "23 5 * * 1" - workflow_dispatch: - -permissions: - contents: read - -jobs: - gitleaks: - uses: DevSecNinja/.github/.github/workflows/lint.yml@ # v4.1.0 - permissions: - contents: read - security-events: write - with: - # renovate: datasource=github-releases depName=jdx/mise - mise-version: "2026.10.19" - # Findings only report; fail the run if the scan or upload fails. - lint-fail-on-error: true - # upload-sarif: false # private repos without GitHub Advanced Security - lint-dprint: false - lint-yamlfmt: false - lint-yamllint: false - lint-actionlint: false - lint-go: false - lint-shellcheck: false - lint-shfmt: false - lint-checkov: false - lint-trivy: false - lint-zizmor: false -``` + scan from a second caller of [`secret-scan.yml`](#secret-scan-secret-scanyml), + after each merge, weekly and on dispatch. | Input | Description | | ----------------------- | ---------------------------------------------------------------------- | @@ -209,6 +172,54 @@ jobs: # lint-job-mode: auto # single | parallel ``` +### Secret scan (`secret-scan.yml`) + +Runs only the gitleaks job of `lint.yml` (v4.3.0+), for the full-history scan +of repositories whose Lint caller runs on pull requests only. The wrapper turns +every other linter off itself, so callers keep no list of linters to disable +and a linter added to `lint.yml` later never starts running in them +(`tests/secret-scan-wrapper.py` fails CI when the wrapper misses one). gitleaks +behaves exactly as described under [Lint](#lint-lintyml): history findings of +public repositories go to code scanning (category `gitleaks/history`) with a +count-only log, private repositories get the job summary. The wrapper calls +`lint.yml` with GitHub's `$/` self-repository syntax, so it always runs the +`lint.yml` of the commit you pin. A Lint caller that also runs on push already +scans the history there, so drop `push` below. + +```yaml +name: Secret scan +on: + push: + branches: ["main"] + schedule: + - cron: "23 5 * * 1" + workflow_dispatch: + +permissions: + contents: read + +jobs: + gitleaks: + uses: DevSecNinja/.github/.github/workflows/secret-scan.yml@ # v4.3.0 + permissions: + contents: read + # Public repositories upload history findings to code scanning. + security-events: write + with: + # renovate: datasource=github-releases depName=jdx/mise + mise-version: "2026.10.19" + # lint-config-dir: config-sync/files +``` + +| Input | Description | +| -------------------- | --------------------------------------------------------------------------------------------- | +| `mise-version` | **Required.** mise version to install. | +| `lint-config-dir` | Directory with an optional `.gitleaks.toml`. Default: `""`. | +| `lint-fail-on-error` | Fail when the scan or the code scanning upload fails (findings only report). Default: `true`. | + +Private repositories without GitHub Advanced Security need no extra input: +their history findings go to the job summary, not to code scanning. + ### Auto-fix formatting (`autofix.yml`) Runs dprint, yamlfmt, and shfmt in write mode, then commits and pushes any diff --git a/tests/secret-scan-wrapper.py b/tests/secret-scan-wrapper.py new file mode 100644 index 00000000..87dec4c8 --- /dev/null +++ b/tests/secret-scan-wrapper.py @@ -0,0 +1,127 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.9" +# dependencies = ["pyyaml==6.0.3"] +# /// +"""Keep the reusable secret-scan workflow down to gitleaks only. + +.github/workflows/secret-scan.yml calls lint.yml with gitleaks on and every +other linter off, so secret-scan callers don't keep their own disable list. +lint.yml linters default to on, so a linter input added there without being +turned off in the wrapper would silently start running in every secret-scan +caller. This test fails when: + +- lint.yml has a boolean `lint-*` linter input that the wrapper doesn't set to + a literal `false` (or `lint-gitleaks` isn't a literal `true`); +- the wrapper passes an input lint.yml doesn't declare; +- the wrapper doesn't call this repository's lint.yml with `$/`, or doesn't + pass its own inputs through. + +The checks also run against broken copies of the wrapper to prove they bite. +""" + +from __future__ import annotations + +import copy +import sys +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parent.parent +LINT = ROOT / ".github" / "workflows" / "lint.yml" +WRAPPER = ROOT / ".github" / "workflows" / "secret-scan.yml" + +LINT_REF = "$/.github/workflows/lint.yml" +# Boolean `lint-*` inputs of lint.yml that aren't linters. +NOT_LINTERS = {"lint-fail-on-error"} +# Wrapper inputs passed through to lint.yml unchanged. +PASS_THROUGH = ("mise-version", "lint-config-dir", "lint-fail-on-error") + + +def call_inputs(workflow: dict) -> dict: + # PyYAML (YAML 1.1) reads the `on` key as True. + triggers = workflow.get("on", workflow.get(True)) or {} + return (triggers.get("workflow_call") or {}).get("inputs") or {} + + +def check(lint: dict, wrapper: dict) -> list[str]: + problems: list[str] = [] + lint_inputs = call_inputs(lint) + linters = sorted( + name for name, spec in lint_inputs.items() + if name.startswith("lint-") and (spec or {}).get("type") == "boolean" and name not in NOT_LINTERS + ) + if "lint-gitleaks" not in linters: + problems.append("lint.yml has no boolean lint-gitleaks input") + + jobs = wrapper.get("jobs") or {} + calls = {job_id: job for job_id, job in jobs.items() if isinstance(job, dict) and job.get("uses") == LINT_REF} + if len(jobs) != 1 or len(calls) != 1: + problems.append(f"secret-scan.yml must have exactly one job, calling {LINT_REF}") + return problems + job_id, job = next(iter(calls.items())) + given = job.get("with") or {} + + for name in linters: + want = name == "lint-gitleaks" + if given.get(name) is not want: + problems.append(f"jobs.{job_id}.with.{name} must be {str(want).lower()}, got {given.get(name)!r}") + for name in sorted(set(given) - set(lint_inputs)): + problems.append(f"jobs.{job_id}.with.{name} is not an input of lint.yml") + + wrapper_inputs = call_inputs(wrapper) + for name in PASS_THROUGH: + if name not in wrapper_inputs: + problems.append(f"secret-scan.yml has no {name} input") + if given.get(name) != f"${{{{ inputs.{name} }}}}": + problems.append(f"jobs.{job_id}.with.{name} must pass through ${{{{ inputs.{name} }}}}") + if (wrapper_inputs.get("mise-version") or {}).get("required") is not True: + problems.append("secret-scan.yml must require mise-version (ADR 0001: callers own tool versions)") + return problems + + +def broken_copies(wrapper: dict): + """Yield (description, mutated wrapper) pairs that check() must reject.""" + job = next(iter(wrapper["jobs"])) + + def mutate(description, change): + broken = copy.deepcopy(wrapper) + change(broken["jobs"][job]) + return description, broken + + yield mutate("a linter left on", lambda j: j["with"].pop("lint-zizmor")) + yield mutate("a linter set by expression", lambda j: j["with"].update({"lint-trivy": "${{ false }}"})) + yield mutate("gitleaks off", lambda j: j["with"].update({"lint-gitleaks": False})) + yield mutate("gitleaks left to the default", lambda j: j["with"].pop("lint-gitleaks")) + yield mutate("an unknown input", lambda j: j["with"].update({"lint-typo": False})) + yield mutate("a workspace-relative call", lambda j: j.update({"uses": "./.github/workflows/lint.yml"})) + yield mutate("a hard-coded fail-on-error", lambda j: j["with"].update({"lint-fail-on-error": True})) + + +def main() -> int: + lint = yaml.safe_load(LINT.read_text(encoding="utf-8")) + wrapper = yaml.safe_load(WRAPPER.read_text(encoding="utf-8")) + failures = check(lint, wrapper) + + new_linter = copy.deepcopy(lint) + call_inputs(new_linter)["lint-newtool"] = {"type": "boolean", "default": True} + if not any("lint-newtool" in problem for problem in check(new_linter, wrapper)): + failures.append("self-test: a new lint.yml linter the wrapper doesn't turn off was not caught") + cases = list(broken_copies(wrapper)) + for description, broken in cases: + if not check(lint, broken): + failures.append(f"self-test: {description} was not caught") + + if failures: + print(f"✖ {len(failures)} secret-scan wrapper problem(s):", file=sys.stderr) + for failure in failures: + print(f" - {failure}", file=sys.stderr) + return 1 + print(f"✓ secret-scan.yml runs only gitleaks and turns off every other lint.yml linter; " + f"{len(cases) + 1} broken variants are caught.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) From efba4c48aa56aa45b89efa555b36aac0968af937 Mon Sep 17 00:00:00 2001 From: Jean-Paul van Ravensberg <14926452+DevSecNinja@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:19:41 +0100 Subject: [PATCH 2/5] feat(lint): replace secret-scan wrapper with a lint-gitleaks-only input Owner decision on #551: a flag on lint.yml instead of a wrapper workflow. lint-gitleaks-only (boolean, default false) skips every non-gitleaks linter job and the matching steps of the single-job mode. tests/lint-gitleaks-only.py reads the jobs and steps from lint.yml and fails when one doesn't honour the flag. secret-scan-caller.yml uses it instead of a disable list. The wrapper, its \$/ nested call and the actionlint ignore are gone. Closes #549 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/actionlint.yaml | 8 -- .github/workflows/lint.yml | 81 ++++++------ .github/workflows/secret-scan-caller.yml | 8 +- .github/workflows/secret-scan.yml | 63 --------- .mise.toml | 2 +- docs/architecture.md | 85 +++++------- tests/lint-gitleaks-only.py | 162 +++++++++++++++++++++++ tests/lint-job-modes-contract.sh | 9 +- tests/secret-scan-wrapper.py | 127 ------------------ tests/workflow-job-conditions.py | 5 + 10 files changed, 259 insertions(+), 291 deletions(-) delete mode 100644 .github/actionlint.yaml delete mode 100644 .github/workflows/secret-scan.yml create mode 100644 tests/lint-gitleaks-only.py delete mode 100644 tests/secret-scan-wrapper.py diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml deleted file mode 100644 index 790fcd90..00000000 --- a/.github/actionlint.yaml +++ /dev/null @@ -1,8 +0,0 @@ ---- -# actionlint configuration: https://github.com/rhysd/actionlint/blob/main/docs/config.md -paths: - .github/workflows/secret-scan.yml: - ignore: - # actionlint (1.7.12) predates GitHub's `$/` self-repository syntax for - # reusable workflow calls (July 2026). Drop this once it supports it. - - 'reusable workflow call "\$/\.github/workflows/lint\.yml" at "uses" is not following the format' diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index ffeba40b..9d77765a 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -53,6 +53,13 @@ on: required: false type: boolean default: true + lint-gitleaks-only: + description: >- + Run only gitleaks and skip every other linter, including linters added in later releases, whatever their + `lint-*` inputs say. For secret-scan callers; keep `lint-gitleaks` on. + required: false + type: boolean + default: false lint-go: description: "Run golangci-lint (Go linting)" required: false @@ -125,8 +132,8 @@ defaults: jobs: dprint: name: dprint - if: ${{ inputs.lint-dprint && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-dprint && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -168,8 +175,8 @@ jobs: yamlfmt: name: yamlfmt - if: ${{ inputs.lint-yamlfmt && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-yamlfmt && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -210,8 +217,8 @@ jobs: yamllint: name: yamllint - if: ${{ inputs.lint-yamllint && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-yamllint && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -252,8 +259,8 @@ jobs: actionlint: name: actionlint - if: ${{ inputs.lint-actionlint && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-actionlint && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -486,8 +493,8 @@ jobs: category: gitleaks/history go: name: go - if: ${{ inputs.lint-go && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-go && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == + 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 15 @@ -531,8 +538,8 @@ jobs: shellcheck: name: shellcheck - if: ${{ inputs.lint-shellcheck && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-shellcheck && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -587,8 +594,8 @@ jobs: shfmt: name: shfmt - if: ${{ inputs.lint-shfmt && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-shfmt && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -627,8 +634,8 @@ jobs: checkov: name: checkov - if: ${{ inputs.lint-checkov && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-checkov && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 15 @@ -682,8 +689,8 @@ jobs: trivy: name: trivy - if: ${{ inputs.lint-trivy && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-trivy && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 15 @@ -744,8 +751,8 @@ jobs: zizmor: name: zizmor - if: ${{ inputs.lint-zizmor && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-zizmor && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -784,8 +791,8 @@ jobs: config-drift: name: config drift - if: ${{ inputs.lint-config-drift && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-config-drift && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -880,7 +887,7 @@ jobs: - name: Check formatting with dprint id: dprint - if: ${{ inputs.lint-dprint }} + if: ${{ inputs.lint-dprint && !inputs.lint-gitleaks-only }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -907,7 +914,7 @@ jobs: - name: Check YAML formatting id: yamlfmt - if: ${{ inputs.lint-yamlfmt }} + if: ${{ inputs.lint-yamlfmt && !inputs.lint-gitleaks-only }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -933,7 +940,7 @@ jobs: - name: Run yamllint id: yamllint - if: ${{ inputs.lint-yamllint }} + if: ${{ inputs.lint-yamllint && !inputs.lint-gitleaks-only }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -959,7 +966,7 @@ jobs: - name: Run actionlint id: actionlint - if: ${{ inputs.lint-actionlint }} + if: ${{ inputs.lint-actionlint && !inputs.lint-gitleaks-only }} continue-on-error: true run: mise exec -- actionlint @@ -1158,7 +1165,7 @@ jobs: category: gitleaks/history - name: Check for Go version file id: go-version-file - if: ${{ inputs.lint-go }} + if: ${{ inputs.lint-go && !inputs.lint-gitleaks-only }} env: GO_VERSION_FILE: ${{ inputs.go-version-file }} run: |- @@ -1197,7 +1204,7 @@ jobs: - name: Run shellcheck id: shellcheck - if: ${{ inputs.lint-shellcheck }} + if: ${{ inputs.lint-shellcheck && !inputs.lint-gitleaks-only }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -1237,7 +1244,7 @@ jobs: - name: Run shfmt id: shfmt - if: ${{ inputs.lint-shfmt }} + if: ${{ inputs.lint-shfmt && !inputs.lint-gitleaks-only }} continue-on-error: true env: EXCLUDE_PATTERN: ${{ inputs.lint-shfmt-exclude }} @@ -1261,7 +1268,7 @@ jobs: - name: Run checkov id: checkov - if: ${{ inputs.lint-checkov }} + if: ${{ inputs.lint-checkov && !inputs.lint-gitleaks-only }} continue-on-error: true env: UPLOAD_SARIF: ${{ inputs.upload-sarif }} @@ -1275,7 +1282,7 @@ jobs: - name: Filter skipped checks from SARIF id: checkov-sarif-filter - if: ${{ inputs.lint-checkov && inputs.upload-sarif }} + if: ${{ inputs.lint-checkov && !inputs.lint-gitleaks-only && inputs.upload-sarif }} continue-on-error: true run: |- sarif="${RUNNER_TEMP}/results_sarif.sarif" @@ -1292,7 +1299,7 @@ jobs: - name: Upload checkov SARIF report id: checkov-sarif - if: ${{ inputs.lint-checkov && inputs.upload-sarif }} + if: ${{ inputs.lint-checkov && !inputs.lint-gitleaks-only && inputs.upload-sarif }} continue-on-error: true uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 with: @@ -1301,7 +1308,7 @@ jobs: - name: Run trivy id: trivy - if: ${{ inputs.lint-trivy }} + if: ${{ inputs.lint-trivy && !inputs.lint-gitleaks-only }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -1337,7 +1344,7 @@ jobs: - name: Upload trivy SARIF report id: trivy-sarif - if: ${{ inputs.lint-trivy && inputs.upload-sarif }} + if: ${{ inputs.lint-trivy && !inputs.lint-gitleaks-only && inputs.upload-sarif }} continue-on-error: true uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 with: @@ -1346,7 +1353,7 @@ jobs: - name: Run zizmor id: zizmor - if: ${{ inputs.lint-zizmor }} + if: ${{ inputs.lint-zizmor && !inputs.lint-gitleaks-only }} continue-on-error: true env: UPLOAD_SARIF: ${{ inputs.upload-sarif }} @@ -1360,7 +1367,7 @@ jobs: - name: Upload zizmor SARIF report id: zizmor-sarif - if: ${{ inputs.lint-zizmor && inputs.upload-sarif }} + if: ${{ inputs.lint-zizmor && !inputs.lint-gitleaks-only && inputs.upload-sarif }} continue-on-error: true uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 with: @@ -1369,7 +1376,7 @@ jobs: - name: Check config drift against central repo id: config-drift - if: ${{ inputs.lint-config-drift }} + if: ${{ inputs.lint-config-drift && !inputs.lint-gitleaks-only }} continue-on-error: true run: |- BASE_URL="https://raw.githubusercontent.com/DevSecNinja/.github/main/config-sync/files" diff --git a/.github/workflows/secret-scan-caller.yml b/.github/workflows/secret-scan-caller.yml index 1acf347a..4ec9a8c9 100644 --- a/.github/workflows/secret-scan-caller.yml +++ b/.github/workflows/secret-scan-caller.yml @@ -23,8 +23,7 @@ concurrency: jobs: gitleaks: # Local reference validates reusable workflow changes in this repository. - # secret-scan.yml runs only gitleaks and keeps every other linter off. - uses: ./.github/workflows/secret-scan.yml + uses: ./.github/workflows/lint.yml permissions: contents: read security-events: write @@ -32,3 +31,8 @@ jobs: # renovate: datasource=github-releases depName=jdx/mise mise-version: "2026.10.19" lint-config-dir: config-sync/files + # History findings only report; this fails the run when the scan or the + # code scanning upload fails, so a silent gap can't look green. + lint-fail-on-error: true + # Skips every other linter, including ones added to lint.yml later. + lint-gitleaks-only: true diff --git a/.github/workflows/secret-scan.yml b/.github/workflows/secret-scan.yml deleted file mode 100644 index 2c42c90f..00000000 --- a/.github/workflows/secret-scan.yml +++ /dev/null @@ -1,63 +0,0 @@ ---- -name: Reusable — Secret scan - -# Runs only the gitleaks job of the reusable Lint workflow, with every other -# linter switched off here, so callers don't keep their own list of linters to -# disable and a linter added to lint.yml later never starts running in them. -# tests/secret-scan-wrapper.py fails when lint.yml gains a linter input this -# workflow doesn't turn off. gitleaks behaves exactly as in lint.yml (see -# docs/architecture.md): pull requests scan their own commits, other events -# scan the full history, public repositories send history findings to code -# scanning (category `gitleaks/history`) and private ones to the job summary. -on: - workflow_call: - inputs: - mise-version: - description: "mise version to install" - required: true - type: string - lint-config-dir: - description: "Directory containing an optional .gitleaks.toml" - required: false - type: string - default: "" - lint-fail-on-error: - description: "Fail when the scan or the code scanning upload fails (history findings only report)" - required: false - type: boolean - default: true - -permissions: - contents: read - -jobs: - gitleaks: - # `$/` (self-repository syntax) resolves to this workflow's own repository - # at the commit that is running, so a caller pinning secret-scan.yml@ - # gets lint.yml from that same commit, and this repository's caller tests - # local changes to both. `./` is workspace-relative, so it isn't - # guaranteed to resolve to this repository when another repository calls - # this workflow, and an `owner/repo/...@` pin would lag behind - # lint.yml. actionlint doesn't know `$/` yet: .github/actionlint.yaml - # ignores that one error. - uses: $/.github/workflows/lint.yml - permissions: - contents: read - # Full-history findings of public repositories go to code scanning. - security-events: write - with: - mise-version: ${{ inputs.mise-version }} - lint-config-dir: ${{ inputs.lint-config-dir }} - lint-fail-on-error: ${{ inputs.lint-fail-on-error }} - lint-gitleaks: true - lint-dprint: false - lint-yamlfmt: false - lint-yamllint: false - lint-actionlint: false - lint-go: false - lint-shellcheck: false - lint-shfmt: false - lint-checkov: false - lint-trivy: false - lint-zizmor: false - lint-config-drift: false diff --git a/.mise.toml b/.mise.toml index fabc4208..cf9d9f51 100644 --- a/.mise.toml +++ b/.mise.toml @@ -33,7 +33,7 @@ run = [ "bash ./tests/release-please-auth-contract.sh", "bash ./tests/automation-app-contract.sh", "uv run --script ./tests/app-key-confinement.py", - "uv run --script ./tests/secret-scan-wrapper.py", + "uv run --script ./tests/lint-gitleaks-only.py", "bash ./tests/lint-job-modes-contract.sh", "bash ./tests/open-pr-push.sh", "bash ./tests/open-pr-api-commit.sh", diff --git a/docs/architecture.md b/docs/architecture.md index c86725b8..5fc46d67 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -114,8 +114,40 @@ on the event (v4.1.0+): Internal repositories, whose logs every enterprise member can read, and a failed visibility lookup count as public. Repositories whose Lint caller runs on pull requests only get the full-history - scan from a second caller of [`secret-scan.yml`](#secret-scan-secret-scanyml), - after each merge, weekly and on dispatch. + scan from a second caller, after each merge, weekly and on dispatch (this + repository's `secret-scan-caller.yml`). It sets `lint-gitleaks-only: true` + (v4.3.0+), which skips every other linter, including linters added to + `lint.yml` later, so the caller keeps no list of linters to turn off. A Lint + caller that also runs on push already scans the history there, so drop `push` + below. + +```yaml +name: Secret scan +on: + push: + branches: ["main"] + schedule: + - cron: "23 5 * * 1" + workflow_dispatch: + +permissions: + contents: read + +jobs: + gitleaks: + uses: DevSecNinja/.github/.github/workflows/lint.yml@ # v4.3.0 + permissions: + contents: read + security-events: write + with: + # renovate: datasource=github-releases depName=jdx/mise + mise-version: "2026.10.19" + # Findings only report; fail the run if the scan or upload fails. + lint-fail-on-error: true + # Run gitleaks and nothing else, now and after future linter additions. + lint-gitleaks-only: true + # upload-sarif: false # private repos without GitHub Advanced Security +``` | Input | Description | | ----------------------- | ---------------------------------------------------------------------- | @@ -131,6 +163,7 @@ on the event (v4.1.0+): | `lint-yamllint` | YAML linting (yamllint). Default: `true`. | | `lint-actionlint` | GitHub Actions linting. Default: `true`. | | `lint-gitleaks` | Secret scanning (gitleaks). Default: `true`. | +| `lint-gitleaks-only` | Run only gitleaks, skip all other linters. Default: `false`. v4.3.0+. | | `lint-go` | Go linting (golangci-lint). Default: `true`. | | `lint-shellcheck` | Shell linting (shellcheck). Default: `true`. | | `lint-shfmt` | Shell formatting (shfmt). Default: `true`. | @@ -172,54 +205,6 @@ jobs: # lint-job-mode: auto # single | parallel ``` -### Secret scan (`secret-scan.yml`) - -Runs only the gitleaks job of `lint.yml` (v4.3.0+), for the full-history scan -of repositories whose Lint caller runs on pull requests only. The wrapper turns -every other linter off itself, so callers keep no list of linters to disable -and a linter added to `lint.yml` later never starts running in them -(`tests/secret-scan-wrapper.py` fails CI when the wrapper misses one). gitleaks -behaves exactly as described under [Lint](#lint-lintyml): history findings of -public repositories go to code scanning (category `gitleaks/history`) with a -count-only log, private repositories get the job summary. The wrapper calls -`lint.yml` with GitHub's `$/` self-repository syntax, so it always runs the -`lint.yml` of the commit you pin. A Lint caller that also runs on push already -scans the history there, so drop `push` below. - -```yaml -name: Secret scan -on: - push: - branches: ["main"] - schedule: - - cron: "23 5 * * 1" - workflow_dispatch: - -permissions: - contents: read - -jobs: - gitleaks: - uses: DevSecNinja/.github/.github/workflows/secret-scan.yml@ # v4.3.0 - permissions: - contents: read - # Public repositories upload history findings to code scanning. - security-events: write - with: - # renovate: datasource=github-releases depName=jdx/mise - mise-version: "2026.10.19" - # lint-config-dir: config-sync/files -``` - -| Input | Description | -| -------------------- | --------------------------------------------------------------------------------------------- | -| `mise-version` | **Required.** mise version to install. | -| `lint-config-dir` | Directory with an optional `.gitleaks.toml`. Default: `""`. | -| `lint-fail-on-error` | Fail when the scan or the code scanning upload fails (findings only report). Default: `true`. | - -Private repositories without GitHub Advanced Security need no extra input: -their history findings go to the job summary, not to code scanning. - ### Auto-fix formatting (`autofix.yml`) Runs dprint, yamlfmt, and shfmt in write mode, then commits and pushes any diff --git a/tests/lint-gitleaks-only.py b/tests/lint-gitleaks-only.py new file mode 100644 index 00000000..d66b8da4 --- /dev/null +++ b/tests/lint-gitleaks-only.py @@ -0,0 +1,162 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.9" +# dependencies = ["pyyaml==6.0.3"] +# /// +"""Make `lint-gitleaks-only` skip every linter of lint.yml except gitleaks. + +Secret-scan callers set `lint-gitleaks-only: true` instead of turning each +other linter off, so a linter added to lint.yml later must honour the flag or +it silently starts running in all of them. Jobs and steps are read from +lint.yml, so new ones are checked without editing this test: + +- every job except `gitleaks` and the single-job `all-linters` must have + `!inputs.lint-gitleaks-only` as a top-level `&&` term of its `if:`; +- in `all-linters` (which also hosts gitleaks), every step with an `id:` or + whose `if:` reads a linter input must be a gitleaks step (top-level + `inputs.lint-gitleaks`), honour the flag the same way, or depend through a + top-level `steps.` term on a step that does. Shared setup steps are + listed in SHARED_STEPS. + +Broken copies of lint.yml are checked too, to prove the test bites. +""" + +from __future__ import annotations + +import copy +import re +import sys +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parent.parent +LINT = ROOT / ".github" / "workflows" / "lint.yml" + +FLAG = "lint-gitleaks-only" +HONOURS = f"!inputs.{FLAG}" +GITLEAKS = "inputs.lint-gitleaks" +EXEMPT_JOBS = {"gitleaks", "all-linters"} +# Steps every enabled linter needs, gitleaks included. +SHARED_STEPS = {"Install mise"} +# Boolean `lint-*` inputs that are options rather than linters. +NOT_LINTERS = {"lint-fail-on-error", FLAG} +TOKEN = re.compile(r"'(?:[^']|'')*'|&&|\|\||[()]|[^'()&|]+|.") +STEP_REF = re.compile(r"\bsteps\.([A-Za-z_][\w-]*)") + + +def call_inputs(workflow: dict) -> dict: + # PyYAML (YAML 1.1) reads the `on` key as True. + triggers = workflow.get("on", workflow.get(True)) or {} + return (triggers.get("workflow_call") or {}).get("inputs") or {} + + +def terms(condition) -> list[str]: + """Top-level `&&` terms of an `if:`, whitespace removed; one term when `||` is top-level.""" + text = str(condition or "").strip() + if text.startswith("${{") and text.endswith("}}"): + text = text[3:-2] + parts, current, depth, has_or = [], "", 0, False + for token in TOKEN.findall(text): + if token == "(": + depth += 1 + elif token == ")": + depth -= 1 + if depth == 0 and token == "&&": + parts.append(current) + current = "" + continue + has_or = has_or or (depth == 0 and token == "||") + current += token + parts.append(current) + if has_or: + parts = ["&&".join(parts)] + return [re.sub(r"\s+", "", part) for part in parts] + + +def check(lint: dict) -> list[str]: + problems: list[str] = [] + inputs = call_inputs(lint) + spec = inputs.get(FLAG) or {} + if spec.get("type") != "boolean" or spec.get("default") is not False: + problems.append(f"lint.yml must declare a boolean {FLAG} input defaulting to false") + linters = {name for name, s in inputs.items() + if name.startswith("lint-") and (s or {}).get("type") == "boolean" and name not in NOT_LINTERS} + other_linters = linters - {"lint-gitleaks"} + + jobs = lint.get("jobs") or {} + for job_id in sorted(set(EXEMPT_JOBS) - set(jobs)): + problems.append(f"lint.yml has no {job_id} job") + for job_id, job in jobs.items(): + if job_id not in EXEMPT_JOBS and HONOURS not in terms(job.get("if")): + problems.append(f"jobs.{job_id}.if must include `&& {HONOURS}` at its top level") + + allowed: set[str] = set() + for step in (jobs.get("all-linters") or {}).get("steps") or []: + name, step_id = step.get("name"), step.get("id") + condition = str(step.get("if") or "") + reads_linter = any(re.search(rf"\binputs\.{re.escape(n)}\b", condition) for n in other_linters) + if name in SHARED_STEPS or not (step_id or reads_linter): + continue + step_terms = terms(condition) + ok = (HONOURS in step_terms or GITLEAKS in step_terms + or any(ref in allowed for term in step_terms for ref in STEP_REF.findall(term))) + if ok: + allowed.add(step_id) + else: + problems.append(f"jobs.all-linters step {name!r} must include `&& {HONOURS}` at the top level of its if:") + return problems + + +def broken_copies(lint: dict): + """Yield (description, mutated lint.yml) pairs that check() must reject.""" + + def mutate(description, change): + broken = copy.deepcopy(lint) + change(broken["jobs"]) + return description, broken + + def step(jobs, step_id): + return next(s for s in jobs["all-linters"]["steps"] if s.get("id") == step_id) + + yield mutate("a job without the flag", + lambda j: j["dprint"].update({"if": "${{ inputs.lint-dprint }}"})) + yield mutate("a new job without the flag", + lambda j: j.update({"newtool": {"if": "${{ inputs.lint-newtool }}", "runs-on": "ubuntu-24.04"}})) + yield mutate("a new job without any if", + lambda j: j.update({"newtool": {"runs-on": "ubuntu-24.04"}})) + yield mutate("the flag only inside an || term", + lambda j: j["trivy"].update({"if": f"${{{{ inputs.lint-trivy || {HONOURS} }}}}"})) + yield mutate("a single-job step without the flag", + lambda j: step(j, "zizmor").update({"if": "${{ inputs.lint-zizmor }}"})) + yield mutate("a SARIF step without the flag", + lambda j: step(j, "trivy-sarif").update({"if": "${{ inputs.lint-trivy && inputs.upload-sarif }}"})) + yield mutate("a new single-job step without any if", + lambda j: j["all-linters"]["steps"].insert(-1, {"name": "Run newtool", "id": "newtool", "run": "x"})) + + +def main() -> int: + lint = yaml.safe_load(LINT.read_text(encoding="utf-8")) + failures = check(lint) + + no_flag = copy.deepcopy(lint) + call_inputs(no_flag).pop(FLAG, None) + if not any(f"declare a boolean {FLAG}" in problem for problem in check(no_flag)): + failures.append(f"self-test: a missing {FLAG} input was not caught") + cases = list(broken_copies(lint)) + for description, broken in cases: + if not check(broken): + failures.append(f"self-test: {description} was not caught") + + if failures: + print(f"✖ {len(failures)} {FLAG} problem(s):", file=sys.stderr) + for failure in failures: + print(f" - {failure}", file=sys.stderr) + return 1 + print(f"✓ {FLAG}: every lint.yml job and single-job step except gitleaks honours the flag; " + f"{len(cases) + 1} broken variants are caught.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/lint-job-modes-contract.sh b/tests/lint-job-modes-contract.sh index bcb7eb93..fd7cbff1 100755 --- a/tests/lint-job-modes-contract.sh +++ b/tests/lint-job-modes-contract.sh @@ -131,11 +131,14 @@ grep -Fq 'default: auto' <<<"${mode_input}" || fail "lint-job-mode must default grep -Fq 'required: false' <<<"${mode_input}" || fail "lint-job-mode must stay optional" # Exactly one mode runs: per-linter jobs carry the parallel guard, the -# combined job its negation. +# combined job its negation. Every linter except gitleaks also honours +# lint-gitleaks-only (tests/lint-gitleaks-only.py checks the single-job steps). for job in "${linter_jobs[@]}"; do condition="$(job_if "${job}")" - [ "${condition}" = "\${{ inputs.lint-${job} && ${parallel_guard} }}" ] || - fail "job ${job} must use: if: \${{ inputs.lint-${job} && ${parallel_guard} }} (found: ${condition})" + only=" && !inputs.lint-gitleaks-only" + [ "${job}" = gitleaks ] && only="" + [ "${condition}" = "\${{ inputs.lint-${job}${only} && ${parallel_guard} }}" ] || + fail "job ${job} must use: if: \${{ inputs.lint-${job}${only} && ${parallel_guard} }} (found: ${condition})" done condition="$(job_if "${combined_job}")" [ "${condition}" = "\${{ !${parallel_guard} }}" ] || diff --git a/tests/secret-scan-wrapper.py b/tests/secret-scan-wrapper.py deleted file mode 100644 index 87dec4c8..00000000 --- a/tests/secret-scan-wrapper.py +++ /dev/null @@ -1,127 +0,0 @@ -#!/usr/bin/env -S uv run --script -# /// script -# requires-python = ">=3.9" -# dependencies = ["pyyaml==6.0.3"] -# /// -"""Keep the reusable secret-scan workflow down to gitleaks only. - -.github/workflows/secret-scan.yml calls lint.yml with gitleaks on and every -other linter off, so secret-scan callers don't keep their own disable list. -lint.yml linters default to on, so a linter input added there without being -turned off in the wrapper would silently start running in every secret-scan -caller. This test fails when: - -- lint.yml has a boolean `lint-*` linter input that the wrapper doesn't set to - a literal `false` (or `lint-gitleaks` isn't a literal `true`); -- the wrapper passes an input lint.yml doesn't declare; -- the wrapper doesn't call this repository's lint.yml with `$/`, or doesn't - pass its own inputs through. - -The checks also run against broken copies of the wrapper to prove they bite. -""" - -from __future__ import annotations - -import copy -import sys -from pathlib import Path - -import yaml - -ROOT = Path(__file__).resolve().parent.parent -LINT = ROOT / ".github" / "workflows" / "lint.yml" -WRAPPER = ROOT / ".github" / "workflows" / "secret-scan.yml" - -LINT_REF = "$/.github/workflows/lint.yml" -# Boolean `lint-*` inputs of lint.yml that aren't linters. -NOT_LINTERS = {"lint-fail-on-error"} -# Wrapper inputs passed through to lint.yml unchanged. -PASS_THROUGH = ("mise-version", "lint-config-dir", "lint-fail-on-error") - - -def call_inputs(workflow: dict) -> dict: - # PyYAML (YAML 1.1) reads the `on` key as True. - triggers = workflow.get("on", workflow.get(True)) or {} - return (triggers.get("workflow_call") or {}).get("inputs") or {} - - -def check(lint: dict, wrapper: dict) -> list[str]: - problems: list[str] = [] - lint_inputs = call_inputs(lint) - linters = sorted( - name for name, spec in lint_inputs.items() - if name.startswith("lint-") and (spec or {}).get("type") == "boolean" and name not in NOT_LINTERS - ) - if "lint-gitleaks" not in linters: - problems.append("lint.yml has no boolean lint-gitleaks input") - - jobs = wrapper.get("jobs") or {} - calls = {job_id: job for job_id, job in jobs.items() if isinstance(job, dict) and job.get("uses") == LINT_REF} - if len(jobs) != 1 or len(calls) != 1: - problems.append(f"secret-scan.yml must have exactly one job, calling {LINT_REF}") - return problems - job_id, job = next(iter(calls.items())) - given = job.get("with") or {} - - for name in linters: - want = name == "lint-gitleaks" - if given.get(name) is not want: - problems.append(f"jobs.{job_id}.with.{name} must be {str(want).lower()}, got {given.get(name)!r}") - for name in sorted(set(given) - set(lint_inputs)): - problems.append(f"jobs.{job_id}.with.{name} is not an input of lint.yml") - - wrapper_inputs = call_inputs(wrapper) - for name in PASS_THROUGH: - if name not in wrapper_inputs: - problems.append(f"secret-scan.yml has no {name} input") - if given.get(name) != f"${{{{ inputs.{name} }}}}": - problems.append(f"jobs.{job_id}.with.{name} must pass through ${{{{ inputs.{name} }}}}") - if (wrapper_inputs.get("mise-version") or {}).get("required") is not True: - problems.append("secret-scan.yml must require mise-version (ADR 0001: callers own tool versions)") - return problems - - -def broken_copies(wrapper: dict): - """Yield (description, mutated wrapper) pairs that check() must reject.""" - job = next(iter(wrapper["jobs"])) - - def mutate(description, change): - broken = copy.deepcopy(wrapper) - change(broken["jobs"][job]) - return description, broken - - yield mutate("a linter left on", lambda j: j["with"].pop("lint-zizmor")) - yield mutate("a linter set by expression", lambda j: j["with"].update({"lint-trivy": "${{ false }}"})) - yield mutate("gitleaks off", lambda j: j["with"].update({"lint-gitleaks": False})) - yield mutate("gitleaks left to the default", lambda j: j["with"].pop("lint-gitleaks")) - yield mutate("an unknown input", lambda j: j["with"].update({"lint-typo": False})) - yield mutate("a workspace-relative call", lambda j: j.update({"uses": "./.github/workflows/lint.yml"})) - yield mutate("a hard-coded fail-on-error", lambda j: j["with"].update({"lint-fail-on-error": True})) - - -def main() -> int: - lint = yaml.safe_load(LINT.read_text(encoding="utf-8")) - wrapper = yaml.safe_load(WRAPPER.read_text(encoding="utf-8")) - failures = check(lint, wrapper) - - new_linter = copy.deepcopy(lint) - call_inputs(new_linter)["lint-newtool"] = {"type": "boolean", "default": True} - if not any("lint-newtool" in problem for problem in check(new_linter, wrapper)): - failures.append("self-test: a new lint.yml linter the wrapper doesn't turn off was not caught") - cases = list(broken_copies(wrapper)) - for description, broken in cases: - if not check(lint, broken): - failures.append(f"self-test: {description} was not caught") - - if failures: - print(f"✖ {len(failures)} secret-scan wrapper problem(s):", file=sys.stderr) - for failure in failures: - print(f" - {failure}", file=sys.stderr) - return 1 - print(f"✓ secret-scan.yml runs only gitleaks and turns off every other lint.yml linter; " - f"{len(cases) + 1} broken variants are caught.") - return 0 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/tests/workflow-job-conditions.py b/tests/workflow-job-conditions.py index 360d46e1..c1074bb2 100755 --- a/tests/workflow-job-conditions.py +++ b/tests/workflow-job-conditions.py @@ -400,6 +400,11 @@ def lint_context(*, mode="auto", private=False, has_repository=True, event_name= PER_LINTER - {"go", "trivy"}), ("public repo, config drift on", lint_context(config_drift=True), PER_LINTER | {"config-drift"}), ("invalid mode fails loudly in the single job", lint_context(mode="bogus"), SINGLE), + ("public repo, gitleaks only", lint_context(gitleaks_only=True, config_drift=True), {"gitleaks"}), + ("private repo, parallel, gitleaks only", lint_context(mode="parallel", private=True, gitleaks_only=True), + {"gitleaks"}), + ("private repo, gitleaks only (steps gated in the single job)", lint_context(private=True, gitleaks_only=True), + SINGLE), ] for name, context, expected in lint_scenarios: check("lint.yml", name, running_jobs(lint, context), expected) From 15f7f01382f7ca53a2500822269dc44eb4cf0427 Mon Sep 17 00:00:00 2001 From: Jean-Paul van Ravensberg <14926452+DevSecNinja@users.noreply.github.com> Date: Mon, 16 Nov 2026 21:24:41 +0100 Subject: [PATCH 3/5] test(lint): only accept predecessor terms that are false for skipped steps Addresses review: steps..outcome == 'skipped', negative output comparisons and references inside || no longer count as depending on a flag-honouring step. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- tests/lint-gitleaks-only.py | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/tests/lint-gitleaks-only.py b/tests/lint-gitleaks-only.py index d66b8da4..ad9f4735 100644 --- a/tests/lint-gitleaks-only.py +++ b/tests/lint-gitleaks-only.py @@ -14,9 +14,11 @@ `!inputs.lint-gitleaks-only` as a top-level `&&` term of its `if:`; - in `all-linters` (which also hosts gitleaks), every step with an `id:` or whose `if:` reads a linter input must be a gitleaks step (top-level - `inputs.lint-gitleaks`), honour the flag the same way, or depend through a - top-level `steps.` term on a step that does. Shared setup steps are - listed in SHARED_STEPS. + `inputs.lint-gitleaks`), honour the flag the same way, or have a top-level + term that is false whenever an allowed predecessor step was skipped + (`steps..outputs. == ''` or + `steps..outcome == 'success'`). Shared setup steps are listed in + SHARED_STEPS. Broken copies of lint.yml are checked too, to prove the test bites. """ @@ -42,7 +44,9 @@ # Boolean `lint-*` inputs that are options rather than linters. NOT_LINTERS = {"lint-fail-on-error", FLAG} TOKEN = re.compile(r"'(?:[^']|'')*'|&&|\|\||[()]|[^'()&|]+|.") -STEP_REF = re.compile(r"\bsteps\.([A-Za-z_][\w-]*)") +# A whole `&&` term that is false whenever step was skipped: one of its +# outputs equals a non-empty literal, or it succeeded. +SKIPS_WITH = re.compile(r"^steps\.([A-Za-z_][\w-]*)\.(?:outputs\.[\w-]+=='(?:[^']|'')+'|(?:outcome|conclusion)=='success')$") def call_inputs(workflow: dict) -> dict: @@ -100,7 +104,7 @@ def check(lint: dict) -> list[str]: continue step_terms = terms(condition) ok = (HONOURS in step_terms or GITLEAKS in step_terms - or any(ref in allowed for term in step_terms for ref in STEP_REF.findall(term))) + or any((m := SKIPS_WITH.match(term)) and m.group(1) in allowed for term in step_terms)) if ok: allowed.add(step_id) else: @@ -133,6 +137,15 @@ def step(jobs, step_id): lambda j: step(j, "trivy-sarif").update({"if": "${{ inputs.lint-trivy && inputs.upload-sarif }}"})) yield mutate("a new single-job step without any if", lambda j: j["all-linters"]["steps"].insert(-1, {"name": "Run newtool", "id": "newtool", "run": "x"})) + for description, condition in ( + ("a step running when its predecessor was skipped", "${{ steps.setup-go.outcome == 'skipped' }}"), + ("a step on a negative output comparison", "${{ steps.go-version-file.outputs.exists != 'false' }}"), + ("a step on an empty-output comparison", "${{ steps.go-version-file.outputs.exists == '' }}"), + ("a predecessor reference inside ||", "${{ steps.setup-go.outcome == 'success' || inputs.lint-go }}"), + ("a predecessor reference inside a parenthesised ||", + "${{ (steps.setup-go.outcome == 'success' || always()) && inputs.golangci-lint-version != '' }}"), + ): + yield mutate(description, lambda j, c=condition: step(j, "go").update({"if": c})) def main() -> int: From 9623a902878889c9a2701795410bd3e4e727bc36 Mon Sep 17 00:00:00 2001 From: Jean-Paul van Ravensberg <14926452+DevSecNinja@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:41:10 +0100 Subject: [PATCH 4/5] feat(lint): replace lint-gitleaks-only with a lint-only list Owner decision on #551: lint-only takes a comma-separated list of linters (e.g. lint-only: gitleaks) instead of a gitleaks-only boolean. Only the listed linters run, so linters added to lint.yml later stay off. A listed linter still needs its lint-* input on. Expressions have no split or trim, so each condition matches the name with commas or spaces on either side; a lint-only job validates the list whenever it is set and fails the run on an unknown or disabled name. tests/lint-only.py checks every linter job and single-job step honours the list and that the validator's names match the jobs. Closes #549 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/lint.yml | 190 ++++++++++++---- .github/workflows/secret-scan-caller.yml | 2 +- .mise.toml | 2 +- docs/architecture.md | 21 +- tests/lint-gitleaks-only.py | 175 -------------- tests/lint-job-modes-contract.sh | 10 +- tests/lint-only.py | 278 +++++++++++++++++++++++ tests/workflow-job-conditions.py | 20 +- 8 files changed, 463 insertions(+), 235 deletions(-) delete mode 100644 tests/lint-gitleaks-only.py create mode 100644 tests/lint-only.py diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 9d77765a..61ad545a 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -28,6 +28,14 @@ on: required: false type: boolean default: false + lint-only: + description: >- + Comma-separated linters to run, e.g. `gitleaks` or `gitleaks, trivy` (names as in the `lint-*` inputs). Every + other linter is skipped, including linters added in later releases. A listed linter still needs its `lint-*` + input on. Empty (default): run every enabled linter. An unknown or disabled name fails the run. + required: false + type: string + default: "" lint-dprint: description: "Run dprint (Markdown formatting)" required: false @@ -53,13 +61,6 @@ on: required: false type: boolean default: true - lint-gitleaks-only: - description: >- - Run only gitleaks and skip every other linter, including linters added in later releases, whatever their - `lint-*` inputs say. For secret-scan callers; keep `lint-gitleaks` on. - required: false - type: boolean - default: false lint-go: description: "Run golangci-lint (Go linting)" required: false @@ -132,8 +133,10 @@ defaults: jobs: dprint: name: dprint - if: ${{ inputs.lint-dprint && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-dprint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',dprint,') || contains(format(',{0},', + inputs.lint-only), ',dprint ') || contains(format(',{0},', inputs.lint-only), ' dprint,') || contains(format(',{0},', + inputs.lint-only), ' dprint ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -175,7 +178,9 @@ jobs: yamlfmt: name: yamlfmt - if: ${{ inputs.lint-yamlfmt && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + if: ${{ inputs.lint-yamlfmt && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',yamlfmt,') || + contains(format(',{0},', inputs.lint-only), ',yamlfmt ') || contains(format(',{0},', inputs.lint-only), ' yamlfmt,') + || contains(format(',{0},', inputs.lint-only), ' yamlfmt ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -217,7 +222,9 @@ jobs: yamllint: name: yamllint - if: ${{ inputs.lint-yamllint && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + if: ${{ inputs.lint-yamllint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',yamllint,') || + contains(format(',{0},', inputs.lint-only), ',yamllint ') || contains(format(',{0},', inputs.lint-only), ' yamllint,') + || contains(format(',{0},', inputs.lint-only), ' yamllint ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -259,7 +266,9 @@ jobs: actionlint: name: actionlint - if: ${{ inputs.lint-actionlint && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + if: ${{ inputs.lint-actionlint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',actionlint,') + || contains(format(',{0},', inputs.lint-only), ',actionlint ') || contains(format(',{0},', inputs.lint-only), ' actionlint,') + || contains(format(',{0},', inputs.lint-only), ' actionlint ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -281,8 +290,10 @@ jobs: gitleaks: name: gitleaks - if: ${{ inputs.lint-gitleaks && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) - }} + if: ${{ inputs.lint-gitleaks && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',gitleaks,') || + contains(format(',{0},', inputs.lint-only), ',gitleaks ') || contains(format(',{0},', inputs.lint-only), ' gitleaks,') + || contains(format(',{0},', inputs.lint-only), ' gitleaks ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -493,8 +504,10 @@ jobs: category: gitleaks/history go: name: go - if: ${{ inputs.lint-go && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == - 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-go && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',go,') || contains(format(',{0},', + inputs.lint-only), ',go ') || contains(format(',{0},', inputs.lint-only), ' go,') || contains(format(',{0},', inputs.lint-only), + ' go ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 15 @@ -538,7 +551,9 @@ jobs: shellcheck: name: shellcheck - if: ${{ inputs.lint-shellcheck && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + if: ${{ inputs.lint-shellcheck && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',shellcheck,') + || contains(format(',{0},', inputs.lint-only), ',shellcheck ') || contains(format(',{0},', inputs.lint-only), ' shellcheck,') + || contains(format(',{0},', inputs.lint-only), ' shellcheck ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -594,8 +609,10 @@ jobs: shfmt: name: shfmt - if: ${{ inputs.lint-shfmt && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-shfmt && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',shfmt,') || contains(format(',{0},', + inputs.lint-only), ',shfmt ') || contains(format(',{0},', inputs.lint-only), ' shfmt,') || contains(format(',{0},', + inputs.lint-only), ' shfmt ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -634,7 +651,9 @@ jobs: checkov: name: checkov - if: ${{ inputs.lint-checkov && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + if: ${{ inputs.lint-checkov && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',checkov,') || + contains(format(',{0},', inputs.lint-only), ',checkov ') || contains(format(',{0},', inputs.lint-only), ' checkov,') + || contains(format(',{0},', inputs.lint-only), ' checkov ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -689,8 +708,10 @@ jobs: trivy: name: trivy - if: ${{ inputs.lint-trivy && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-trivy && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',trivy,') || contains(format(',{0},', + inputs.lint-only), ',trivy ') || contains(format(',{0},', inputs.lint-only), ' trivy,') || contains(format(',{0},', + inputs.lint-only), ' trivy ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 15 @@ -751,8 +772,10 @@ jobs: zizmor: name: zizmor - if: ${{ inputs.lint-zizmor && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-zizmor && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',zizmor,') || contains(format(',{0},', + inputs.lint-only), ',zizmor ') || contains(format(',{0},', inputs.lint-only), ' zizmor,') || contains(format(',{0},', + inputs.lint-only), ' zizmor ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -791,7 +814,9 @@ jobs: config-drift: name: config drift - if: ${{ inputs.lint-config-drift && !inputs.lint-gitleaks-only && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode + if: ${{ inputs.lint-config-drift && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',config-drift,') + || contains(format(',{0},', inputs.lint-only), ',config-drift ') || contains(format(',{0},', inputs.lint-only), ' config-drift,') + || contains(format(',{0},', inputs.lint-only), ' config-drift ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -837,6 +862,53 @@ jobs: echo "" echo "All config files match the central repository." + lint-only: + # Checks the `lint-only` list whenever it is set, in both job modes. No + # continue-on-error: a typo or a disabled linter would otherwise skip that + # linter without a trace. The linter conditions match a name with spaces + # or commas on either side (expressions have no split or trim), so this + # accepts only names, commas and spaces. tests/lint-only.py keeps `known` + # equal to the linter jobs. + name: lint-only + if: ${{ inputs.lint-only != '' }} + runs-on: ubuntu-24.04 + timeout-minutes: 5 + permissions: {} + steps: + - name: Validate lint-only + env: + LINT_ONLY: ${{ inputs.lint-only }} + INPUTS: ${{ toJSON(inputs) }} + run: |- + known="dprint yamlfmt yamllint actionlint gitleaks go shellcheck shfmt checkov trivy zizmor config-drift" + if [[ "${LINT_ONLY}" =~ [^a-z0-9,\ -] ]]; then + echo "::error::lint-only must be a comma-separated list of lowercase linter names (got '${LINT_ONLY}')." + exit 1 + fi + status=0 + listed=0 + IFS=, read -ra entries <<<"${LINT_ONLY}" + for entry in "${entries[@]}"; do + name="${entry// /}" + [ -n "${name}" ] || continue + listed=$((listed + 1)) + if [[ "${entry}" =~ [a-z0-9-]\ +[a-z0-9-] ]]; then + echo "::error::lint-only entry '${entry}' holds more than one name; separate names with commas." + status=1 + elif [[ " ${known} " != *" ${name} "* ]]; then + echo "::error::lint-only lists unknown linter '${name}'. Known linters: ${known// /, }." + status=1 + elif [ "$(jq -r --arg key "lint-${name}" '.[$key]' <<<"${INPUTS}")" != true ]; then + echo "::error::lint-only lists '${name}', but lint-${name} is false, so it would not run." + status=1 + fi + done + if [ "${listed}" -eq 0 ]; then + echo "::error::lint-only is set but lists no linter." + status=1 + fi + exit "${status}" + all-linters: # Single-job mode (`lint-job-mode: single`, or `auto` on a private # repository). Every enabled linter runs as a step of this one job, so a @@ -887,7 +959,9 @@ jobs: - name: Check formatting with dprint id: dprint - if: ${{ inputs.lint-dprint && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-dprint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',dprint,') || + contains(format(',{0},', inputs.lint-only), ',dprint ') || contains(format(',{0},', inputs.lint-only), ' dprint,') + || contains(format(',{0},', inputs.lint-only), ' dprint ')) }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -914,7 +988,9 @@ jobs: - name: Check YAML formatting id: yamlfmt - if: ${{ inputs.lint-yamlfmt && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-yamlfmt && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',yamlfmt,') + || contains(format(',{0},', inputs.lint-only), ',yamlfmt ') || contains(format(',{0},', inputs.lint-only), ' yamlfmt,') + || contains(format(',{0},', inputs.lint-only), ' yamlfmt ')) }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -940,7 +1016,9 @@ jobs: - name: Run yamllint id: yamllint - if: ${{ inputs.lint-yamllint && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-yamllint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',yamllint,') + || contains(format(',{0},', inputs.lint-only), ',yamllint ') || contains(format(',{0},', inputs.lint-only), ' yamllint,') + || contains(format(',{0},', inputs.lint-only), ' yamllint ')) }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -966,13 +1044,17 @@ jobs: - name: Run actionlint id: actionlint - if: ${{ inputs.lint-actionlint && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-actionlint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',actionlint,') + || contains(format(',{0},', inputs.lint-only), ',actionlint ') || contains(format(',{0},', inputs.lint-only), ' + actionlint,') || contains(format(',{0},', inputs.lint-only), ' actionlint ')) }} continue-on-error: true run: mise exec -- actionlint - name: Run gitleaks id: gitleaks - if: ${{ inputs.lint-gitleaks }} + if: ${{ inputs.lint-gitleaks && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',gitleaks,') + || contains(format(',{0},', inputs.lint-only), ',gitleaks ') || contains(format(',{0},', inputs.lint-only), ' gitleaks,') + || contains(format(',{0},', inputs.lint-only), ' gitleaks ')) }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -1091,7 +1173,9 @@ jobs: fi - name: Report gitleaks findings - if: ${{ !cancelled() && inputs.lint-gitleaks }} + if: ${{ !cancelled() && inputs.lint-gitleaks && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), + ',gitleaks,') || contains(format(',{0},', inputs.lint-only), ',gitleaks ') || contains(format(',{0},', inputs.lint-only), + ' gitleaks,') || contains(format(',{0},', inputs.lint-only), ' gitleaks ')) }} env: SCAN_MODE: ${{ steps.gitleaks.outputs.mode }} FINDINGS_ARTIFACT: gitleaks-findings-${{ job.check_run_id }} @@ -1165,7 +1249,9 @@ jobs: category: gitleaks/history - name: Check for Go version file id: go-version-file - if: ${{ inputs.lint-go && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-go && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',go,') || contains(format(',{0},', + inputs.lint-only), ',go ') || contains(format(',{0},', inputs.lint-only), ' go,') || contains(format(',{0},', inputs.lint-only), + ' go ')) }} env: GO_VERSION_FILE: ${{ inputs.go-version-file }} run: |- @@ -1204,7 +1290,9 @@ jobs: - name: Run shellcheck id: shellcheck - if: ${{ inputs.lint-shellcheck && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-shellcheck && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',shellcheck,') + || contains(format(',{0},', inputs.lint-only), ',shellcheck ') || contains(format(',{0},', inputs.lint-only), ' + shellcheck,') || contains(format(',{0},', inputs.lint-only), ' shellcheck ')) }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -1244,7 +1332,9 @@ jobs: - name: Run shfmt id: shfmt - if: ${{ inputs.lint-shfmt && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-shfmt && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',shfmt,') || + contains(format(',{0},', inputs.lint-only), ',shfmt ') || contains(format(',{0},', inputs.lint-only), ' shfmt,') + || contains(format(',{0},', inputs.lint-only), ' shfmt ')) }} continue-on-error: true env: EXCLUDE_PATTERN: ${{ inputs.lint-shfmt-exclude }} @@ -1268,7 +1358,9 @@ jobs: - name: Run checkov id: checkov - if: ${{ inputs.lint-checkov && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-checkov && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',checkov,') + || contains(format(',{0},', inputs.lint-only), ',checkov ') || contains(format(',{0},', inputs.lint-only), ' checkov,') + || contains(format(',{0},', inputs.lint-only), ' checkov ')) }} continue-on-error: true env: UPLOAD_SARIF: ${{ inputs.upload-sarif }} @@ -1282,7 +1374,9 @@ jobs: - name: Filter skipped checks from SARIF id: checkov-sarif-filter - if: ${{ inputs.lint-checkov && !inputs.lint-gitleaks-only && inputs.upload-sarif }} + if: ${{ inputs.lint-checkov && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',checkov,') + || contains(format(',{0},', inputs.lint-only), ',checkov ') || contains(format(',{0},', inputs.lint-only), ' checkov,') + || contains(format(',{0},', inputs.lint-only), ' checkov ')) && inputs.upload-sarif }} continue-on-error: true run: |- sarif="${RUNNER_TEMP}/results_sarif.sarif" @@ -1299,7 +1393,9 @@ jobs: - name: Upload checkov SARIF report id: checkov-sarif - if: ${{ inputs.lint-checkov && !inputs.lint-gitleaks-only && inputs.upload-sarif }} + if: ${{ inputs.lint-checkov && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',checkov,') + || contains(format(',{0},', inputs.lint-only), ',checkov ') || contains(format(',{0},', inputs.lint-only), ' checkov,') + || contains(format(',{0},', inputs.lint-only), ' checkov ')) && inputs.upload-sarif }} continue-on-error: true uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 with: @@ -1308,7 +1404,9 @@ jobs: - name: Run trivy id: trivy - if: ${{ inputs.lint-trivy && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-trivy && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',trivy,') || + contains(format(',{0},', inputs.lint-only), ',trivy ') || contains(format(',{0},', inputs.lint-only), ' trivy,') + || contains(format(',{0},', inputs.lint-only), ' trivy ')) }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -1344,7 +1442,9 @@ jobs: - name: Upload trivy SARIF report id: trivy-sarif - if: ${{ inputs.lint-trivy && !inputs.lint-gitleaks-only && inputs.upload-sarif }} + if: ${{ inputs.lint-trivy && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',trivy,') || + contains(format(',{0},', inputs.lint-only), ',trivy ') || contains(format(',{0},', inputs.lint-only), ' trivy,') + || contains(format(',{0},', inputs.lint-only), ' trivy ')) && inputs.upload-sarif }} continue-on-error: true uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 with: @@ -1353,7 +1453,9 @@ jobs: - name: Run zizmor id: zizmor - if: ${{ inputs.lint-zizmor && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-zizmor && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',zizmor,') || + contains(format(',{0},', inputs.lint-only), ',zizmor ') || contains(format(',{0},', inputs.lint-only), ' zizmor,') + || contains(format(',{0},', inputs.lint-only), ' zizmor ')) }} continue-on-error: true env: UPLOAD_SARIF: ${{ inputs.upload-sarif }} @@ -1367,7 +1469,9 @@ jobs: - name: Upload zizmor SARIF report id: zizmor-sarif - if: ${{ inputs.lint-zizmor && !inputs.lint-gitleaks-only && inputs.upload-sarif }} + if: ${{ inputs.lint-zizmor && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',zizmor,') || + contains(format(',{0},', inputs.lint-only), ',zizmor ') || contains(format(',{0},', inputs.lint-only), ' zizmor,') + || contains(format(',{0},', inputs.lint-only), ' zizmor ')) && inputs.upload-sarif }} continue-on-error: true uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 with: @@ -1376,7 +1480,9 @@ jobs: - name: Check config drift against central repo id: config-drift - if: ${{ inputs.lint-config-drift && !inputs.lint-gitleaks-only }} + if: ${{ inputs.lint-config-drift && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',config-drift,') + || contains(format(',{0},', inputs.lint-only), ',config-drift ') || contains(format(',{0},', inputs.lint-only), + ' config-drift,') || contains(format(',{0},', inputs.lint-only), ' config-drift ')) }} continue-on-error: true run: |- BASE_URL="https://raw.githubusercontent.com/DevSecNinja/.github/main/config-sync/files" diff --git a/.github/workflows/secret-scan-caller.yml b/.github/workflows/secret-scan-caller.yml index 4ec9a8c9..9f0baa18 100644 --- a/.github/workflows/secret-scan-caller.yml +++ b/.github/workflows/secret-scan-caller.yml @@ -35,4 +35,4 @@ jobs: # code scanning upload fails, so a silent gap can't look green. lint-fail-on-error: true # Skips every other linter, including ones added to lint.yml later. - lint-gitleaks-only: true + lint-only: gitleaks diff --git a/.mise.toml b/.mise.toml index cf9d9f51..3a3e7fbe 100644 --- a/.mise.toml +++ b/.mise.toml @@ -33,7 +33,7 @@ run = [ "bash ./tests/release-please-auth-contract.sh", "bash ./tests/automation-app-contract.sh", "uv run --script ./tests/app-key-confinement.py", - "uv run --script ./tests/lint-gitleaks-only.py", + "uv run --script ./tests/lint-only.py", "bash ./tests/lint-job-modes-contract.sh", "bash ./tests/open-pr-push.sh", "bash ./tests/open-pr-api-commit.sh", diff --git a/docs/architecture.md b/docs/architecture.md index 5fc46d67..87b96c54 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -115,8 +115,8 @@ on the event (v4.1.0+): failed visibility lookup count as public. Repositories whose Lint caller runs on pull requests only get the full-history scan from a second caller, after each merge, weekly and on dispatch (this - repository's `secret-scan-caller.yml`). It sets `lint-gitleaks-only: true` - (v4.3.0+), which skips every other linter, including linters added to + repository's `secret-scan-caller.yml`). It sets `lint-only: gitleaks` + (v4.4.0+), which skips every other linter, including linters added to `lint.yml` later, so the caller keeps no list of linters to turn off. A Lint caller that also runs on push already scans the history there, so drop `push` below. @@ -135,7 +135,7 @@ permissions: jobs: gitleaks: - uses: DevSecNinja/.github/.github/workflows/lint.yml@ # v4.3.0 + uses: DevSecNinja/.github/.github/workflows/lint.yml@ # v4.4.0 permissions: contents: read security-events: write @@ -145,7 +145,7 @@ jobs: # Findings only report; fail the run if the scan or upload fails. lint-fail-on-error: true # Run gitleaks and nothing else, now and after future linter additions. - lint-gitleaks-only: true + lint-only: gitleaks # upload-sarif: false # private repos without GitHub Advanced Security ``` @@ -156,6 +156,7 @@ jobs: | `go-version-file` | Go version file for setup-go. Default: `go.mod`. | | `lint-config-dir` | Optional linter config directory. Default: `""`. | | `lint-fail-on-error` | Fail when a linter fails. Default: `false`. | +| `lint-only` | Run only these linters, e.g. `gitleaks` (see below). Default: `""`. | | `lint-job-mode` | `auto`, `single`, or `parallel` (see above). Default: `auto`. v3.3.0+. | | `upload-sarif` | Upload checkov/trivy/zizmor SARIF to code scanning. Default: `true`. | | `lint-dprint` | Markdown formatting (dprint). Default: `true`. | @@ -163,7 +164,6 @@ jobs: | `lint-yamllint` | YAML linting (yamllint). Default: `true`. | | `lint-actionlint` | GitHub Actions linting. Default: `true`. | | `lint-gitleaks` | Secret scanning (gitleaks). Default: `true`. | -| `lint-gitleaks-only` | Run only gitleaks, skip all other linters. Default: `false`. v4.3.0+. | | `lint-go` | Go linting (golangci-lint). Default: `true`. | | `lint-shellcheck` | Shell linting (shellcheck). Default: `true`. | | `lint-shfmt` | Shell formatting (shfmt). Default: `true`. | @@ -172,6 +172,17 @@ jobs: | `lint-zizmor` | Actions security scan (zizmor). Default: `true`. | | `lint-config-drift` | Config-drift check. Default: `false`. | +**Running only some linters (v4.4.0+).** `lint-only` takes a comma-separated +list of linter names, the `lint-*` input names without the prefix (`dprint`, +`gitleaks`, `config-drift`, …); spaces around the commas are fine. Only the +listed linters run, and linters added to `lint.yml` later stay off, which the +`lint-*: false` switches can't promise. A listed linter still needs its +`lint-*` input on (`config-drift` also needs `lint-config-drift: true`). A +`lint-only` job checks the list whenever it is set and fails the run on an +unknown name, a disabled linter or an empty list, whatever +`lint-fail-on-error` says, so a typo can't silently skip a scan. That job is +billed like any other. + **Example caller:** ```yaml diff --git a/tests/lint-gitleaks-only.py b/tests/lint-gitleaks-only.py deleted file mode 100644 index ad9f4735..00000000 --- a/tests/lint-gitleaks-only.py +++ /dev/null @@ -1,175 +0,0 @@ -#!/usr/bin/env -S uv run --script -# /// script -# requires-python = ">=3.9" -# dependencies = ["pyyaml==6.0.3"] -# /// -"""Make `lint-gitleaks-only` skip every linter of lint.yml except gitleaks. - -Secret-scan callers set `lint-gitleaks-only: true` instead of turning each -other linter off, so a linter added to lint.yml later must honour the flag or -it silently starts running in all of them. Jobs and steps are read from -lint.yml, so new ones are checked without editing this test: - -- every job except `gitleaks` and the single-job `all-linters` must have - `!inputs.lint-gitleaks-only` as a top-level `&&` term of its `if:`; -- in `all-linters` (which also hosts gitleaks), every step with an `id:` or - whose `if:` reads a linter input must be a gitleaks step (top-level - `inputs.lint-gitleaks`), honour the flag the same way, or have a top-level - term that is false whenever an allowed predecessor step was skipped - (`steps..outputs. == ''` or - `steps..outcome == 'success'`). Shared setup steps are listed in - SHARED_STEPS. - -Broken copies of lint.yml are checked too, to prove the test bites. -""" - -from __future__ import annotations - -import copy -import re -import sys -from pathlib import Path - -import yaml - -ROOT = Path(__file__).resolve().parent.parent -LINT = ROOT / ".github" / "workflows" / "lint.yml" - -FLAG = "lint-gitleaks-only" -HONOURS = f"!inputs.{FLAG}" -GITLEAKS = "inputs.lint-gitleaks" -EXEMPT_JOBS = {"gitleaks", "all-linters"} -# Steps every enabled linter needs, gitleaks included. -SHARED_STEPS = {"Install mise"} -# Boolean `lint-*` inputs that are options rather than linters. -NOT_LINTERS = {"lint-fail-on-error", FLAG} -TOKEN = re.compile(r"'(?:[^']|'')*'|&&|\|\||[()]|[^'()&|]+|.") -# A whole `&&` term that is false whenever step was skipped: one of its -# outputs equals a non-empty literal, or it succeeded. -SKIPS_WITH = re.compile(r"^steps\.([A-Za-z_][\w-]*)\.(?:outputs\.[\w-]+=='(?:[^']|'')+'|(?:outcome|conclusion)=='success')$") - - -def call_inputs(workflow: dict) -> dict: - # PyYAML (YAML 1.1) reads the `on` key as True. - triggers = workflow.get("on", workflow.get(True)) or {} - return (triggers.get("workflow_call") or {}).get("inputs") or {} - - -def terms(condition) -> list[str]: - """Top-level `&&` terms of an `if:`, whitespace removed; one term when `||` is top-level.""" - text = str(condition or "").strip() - if text.startswith("${{") and text.endswith("}}"): - text = text[3:-2] - parts, current, depth, has_or = [], "", 0, False - for token in TOKEN.findall(text): - if token == "(": - depth += 1 - elif token == ")": - depth -= 1 - if depth == 0 and token == "&&": - parts.append(current) - current = "" - continue - has_or = has_or or (depth == 0 and token == "||") - current += token - parts.append(current) - if has_or: - parts = ["&&".join(parts)] - return [re.sub(r"\s+", "", part) for part in parts] - - -def check(lint: dict) -> list[str]: - problems: list[str] = [] - inputs = call_inputs(lint) - spec = inputs.get(FLAG) or {} - if spec.get("type") != "boolean" or spec.get("default") is not False: - problems.append(f"lint.yml must declare a boolean {FLAG} input defaulting to false") - linters = {name for name, s in inputs.items() - if name.startswith("lint-") and (s or {}).get("type") == "boolean" and name not in NOT_LINTERS} - other_linters = linters - {"lint-gitleaks"} - - jobs = lint.get("jobs") or {} - for job_id in sorted(set(EXEMPT_JOBS) - set(jobs)): - problems.append(f"lint.yml has no {job_id} job") - for job_id, job in jobs.items(): - if job_id not in EXEMPT_JOBS and HONOURS not in terms(job.get("if")): - problems.append(f"jobs.{job_id}.if must include `&& {HONOURS}` at its top level") - - allowed: set[str] = set() - for step in (jobs.get("all-linters") or {}).get("steps") or []: - name, step_id = step.get("name"), step.get("id") - condition = str(step.get("if") or "") - reads_linter = any(re.search(rf"\binputs\.{re.escape(n)}\b", condition) for n in other_linters) - if name in SHARED_STEPS or not (step_id or reads_linter): - continue - step_terms = terms(condition) - ok = (HONOURS in step_terms or GITLEAKS in step_terms - or any((m := SKIPS_WITH.match(term)) and m.group(1) in allowed for term in step_terms)) - if ok: - allowed.add(step_id) - else: - problems.append(f"jobs.all-linters step {name!r} must include `&& {HONOURS}` at the top level of its if:") - return problems - - -def broken_copies(lint: dict): - """Yield (description, mutated lint.yml) pairs that check() must reject.""" - - def mutate(description, change): - broken = copy.deepcopy(lint) - change(broken["jobs"]) - return description, broken - - def step(jobs, step_id): - return next(s for s in jobs["all-linters"]["steps"] if s.get("id") == step_id) - - yield mutate("a job without the flag", - lambda j: j["dprint"].update({"if": "${{ inputs.lint-dprint }}"})) - yield mutate("a new job without the flag", - lambda j: j.update({"newtool": {"if": "${{ inputs.lint-newtool }}", "runs-on": "ubuntu-24.04"}})) - yield mutate("a new job without any if", - lambda j: j.update({"newtool": {"runs-on": "ubuntu-24.04"}})) - yield mutate("the flag only inside an || term", - lambda j: j["trivy"].update({"if": f"${{{{ inputs.lint-trivy || {HONOURS} }}}}"})) - yield mutate("a single-job step without the flag", - lambda j: step(j, "zizmor").update({"if": "${{ inputs.lint-zizmor }}"})) - yield mutate("a SARIF step without the flag", - lambda j: step(j, "trivy-sarif").update({"if": "${{ inputs.lint-trivy && inputs.upload-sarif }}"})) - yield mutate("a new single-job step without any if", - lambda j: j["all-linters"]["steps"].insert(-1, {"name": "Run newtool", "id": "newtool", "run": "x"})) - for description, condition in ( - ("a step running when its predecessor was skipped", "${{ steps.setup-go.outcome == 'skipped' }}"), - ("a step on a negative output comparison", "${{ steps.go-version-file.outputs.exists != 'false' }}"), - ("a step on an empty-output comparison", "${{ steps.go-version-file.outputs.exists == '' }}"), - ("a predecessor reference inside ||", "${{ steps.setup-go.outcome == 'success' || inputs.lint-go }}"), - ("a predecessor reference inside a parenthesised ||", - "${{ (steps.setup-go.outcome == 'success' || always()) && inputs.golangci-lint-version != '' }}"), - ): - yield mutate(description, lambda j, c=condition: step(j, "go").update({"if": c})) - - -def main() -> int: - lint = yaml.safe_load(LINT.read_text(encoding="utf-8")) - failures = check(lint) - - no_flag = copy.deepcopy(lint) - call_inputs(no_flag).pop(FLAG, None) - if not any(f"declare a boolean {FLAG}" in problem for problem in check(no_flag)): - failures.append(f"self-test: a missing {FLAG} input was not caught") - cases = list(broken_copies(lint)) - for description, broken in cases: - if not check(broken): - failures.append(f"self-test: {description} was not caught") - - if failures: - print(f"✖ {len(failures)} {FLAG} problem(s):", file=sys.stderr) - for failure in failures: - print(f" - {failure}", file=sys.stderr) - return 1 - print(f"✓ {FLAG}: every lint.yml job and single-job step except gitleaks honours the flag; " - f"{len(cases) + 1} broken variants are caught.") - return 0 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/tests/lint-job-modes-contract.sh b/tests/lint-job-modes-contract.sh index fd7cbff1..574c92da 100755 --- a/tests/lint-job-modes-contract.sh +++ b/tests/lint-job-modes-contract.sh @@ -131,14 +131,12 @@ grep -Fq 'default: auto' <<<"${mode_input}" || fail "lint-job-mode must default grep -Fq 'required: false' <<<"${mode_input}" || fail "lint-job-mode must stay optional" # Exactly one mode runs: per-linter jobs carry the parallel guard, the -# combined job its negation. Every linter except gitleaks also honours -# lint-gitleaks-only (tests/lint-gitleaks-only.py checks the single-job steps). +# combined job its negation. The `lint-only` match in between is checked by +# tests/lint-only.py. for job in "${linter_jobs[@]}"; do condition="$(job_if "${job}")" - only=" && !inputs.lint-gitleaks-only" - [ "${job}" = gitleaks ] && only="" - [ "${condition}" = "\${{ inputs.lint-${job}${only} && ${parallel_guard} }}" ] || - fail "job ${job} must use: if: \${{ inputs.lint-${job}${only} && ${parallel_guard} }} (found: ${condition})" + [[ "${condition}" == "\${{ inputs.lint-${job} && "*" && ${parallel_guard} }}" ]] || + fail "job ${job} must use: if: \${{ inputs.lint-${job} && && ${parallel_guard} }} (found: ${condition})" done condition="$(job_if "${combined_job}")" [ "${condition}" = "\${{ !${parallel_guard} }}" ] || diff --git a/tests/lint-only.py b/tests/lint-only.py new file mode 100644 index 00000000..4d70ddf5 --- /dev/null +++ b/tests/lint-only.py @@ -0,0 +1,278 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.9" +# dependencies = ["pyyaml==6.0.3"] +# /// +"""Make every linter of lint.yml honour the `lint-only` input. + +`lint-only: gitleaks` runs gitleaks and skips every other linter, so +secret-scan callers keep no list of linters to turn off. A linter added to +lint.yml later must honour the list too, or it silently starts running in all +of them. Jobs and steps are read from lint.yml, so new ones are checked +without editing this test: + +- every linter job (all jobs except `all-linters` and the `lint-only` + validation job) needs a boolean `lint-` input, and its `if:` needs + `inputs.lint-` and the generated match for its own name (MATCH) as + top-level `&&` terms; +- in the single-job `all-linters`, every step with an `id:` or whose `if:` + reads a linter input needs both terms for one linter, or a top-level term + that is false whenever an allowed predecessor step was skipped + (`steps..outputs. == ''` or + `steps..outcome == 'success'`); SHARED_STEPS are exempt; +- the `lint-only` job runs whenever the input is set, can't be ignored by + `continue-on-error`, and its `known` names equal the linter jobs. + +The validation script is also run with bash against sample lists, and the +match expression is checked to agree with it. Broken copies of lint.yml are +checked too, to prove the test bites. +""" + +from __future__ import annotations + +import copy +import json +import os +import re +import shutil +import subprocess +import sys +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parent.parent +LINT = ROOT / ".github" / "workflows" / "lint.yml" + +INPUT = "lint-only" +VALIDATOR = "lint-only" +NOT_LINTERS = {"all-linters", VALIDATOR} +# Steps every enabled linter needs. +SHARED_STEPS = {"Install mise"} +TOKEN = re.compile(r"'(?:[^']|'')*'|&&|\|\||[()]|[^'()&|]+|.") +# A whole `&&` term that is false whenever step was skipped. +SKIPS_WITH = re.compile( + r"^steps\.([A-Za-z_][\w-]*)\.(?:outputs\.[\w-]+=='(?:[^']|'')+'|(?:outcome|conclusion)=='success')$") +KNOWN = re.compile(r'^known="([^"]*)"$', re.M) +BORDERS = ((",", ","), (",", " "), (" ", ","), (" ", " ")) + + +def match(name: str) -> str: + """The condition that is true when `lint-only` is empty or lists `name`. + + Expressions have no split or trim, so the list is padded with commas and + the name matched with a comma or space on either side.""" + hay = "format(',{0},', inputs.lint-only)" + return ("(inputs.lint-only == '' || " + + " || ".join(f"contains({hay}, '{a}{name}{b}')" for a, b in BORDERS) + ")") + + +def match_value(name: str, value: str) -> bool: + """What match(name) evaluates to (contains() is case-insensitive).""" + hay = f",{value},".lower() + return value == "" or any(f"{a}{name}{b}" in hay for a, b in BORDERS) + + +def squash(text: str) -> str: + return re.sub(r"\s+", "", text) + + +def call_inputs(workflow: dict) -> dict: + # PyYAML (YAML 1.1) reads the `on` key as True. + triggers = workflow.get("on", workflow.get(True)) or {} + return (triggers.get("workflow_call") or {}).get("inputs") or {} + + +def terms(condition) -> list[str]: + """Top-level `&&` terms of an `if:`, whitespace removed; one term when `||` is top-level.""" + text = str(condition or "").strip() + if text.startswith("${{") and text.endswith("}}"): + text = text[3:-2] + parts, current, depth, has_or = [], "", 0, False + for token in TOKEN.findall(text): + if token == "(": + depth += 1 + elif token == ")": + depth -= 1 + if depth == 0 and token == "&&": + parts.append(current) + current = "" + continue + has_or = has_or or (depth == 0 and token == "||") + current += token + parts.append(current) + if has_or: + parts = ["&&".join(parts)] + return [squash(part) for part in parts] + + +def honours(step_terms: list[str], name: str) -> bool: + return f"inputs.lint-{name}" in step_terms and squash(match(name)) in step_terms + + +def check(lint: dict) -> list[str]: + problems: list[str] = [] + inputs = call_inputs(lint) + spec = inputs.get(INPUT) or {} + if spec.get("type") != "string" or spec.get("default") != "": + problems.append(f"lint.yml must declare a string {INPUT} input defaulting to ''") + + jobs = lint.get("jobs") or {} + for job_id in sorted(NOT_LINTERS - set(jobs)): + problems.append(f"lint.yml has no {job_id} job") + linters = sorted(set(jobs) - NOT_LINTERS) + for name in linters: + if (inputs.get(f"lint-{name}") or {}).get("type") != "boolean": + problems.append(f"jobs.{name} has no boolean lint-{name} input") + if not honours(terms((jobs[name] or {}).get("if")), name): + problems.append(f"jobs.{name}.if must include `inputs.lint-{name} && {match(name)}` at its top level") + + validator = jobs.get(VALIDATOR) or {} + if squash(str(validator.get("if"))) != squash("${{ inputs.lint-only != '' }}"): + problems.append(f"jobs.{VALIDATOR}.if must be ${{{{ inputs.lint-only != '' }}}}") + if "continue-on-error" in validator: + problems.append(f"jobs.{VALIDATOR} must not set continue-on-error") + known = KNOWN.search(validator_script(lint) or "") + if not known: + problems.append(f"jobs.{VALIDATOR} must define known=\"...\" in its script") + elif sorted(known.group(1).split()) != linters: + problems.append(f"jobs.{VALIDATOR} known names {sorted(known.group(1).split())} must equal the " + f"linter jobs {linters}") + + allowed: set[str] = set() + for step in (jobs.get("all-linters") or {}).get("steps") or []: + name, step_id = step.get("name"), step.get("id") + condition = str(step.get("if") or "") + reads_linter = any(re.search(rf"\binputs\.lint-{re.escape(n)}\b", condition) for n in linters) + if name in SHARED_STEPS or not (step_id or reads_linter): + continue + step_terms = terms(condition) + ok = (any(honours(step_terms, n) for n in linters) + or any((m := SKIPS_WITH.match(term)) and m.group(1) in allowed for term in step_terms)) + if ok: + allowed.add(step_id) + else: + problems.append(f"jobs.all-linters step {name!r} must include `inputs.lint- && " + f"` at the top level of its if:") + return problems + + +def validator_script(lint: dict) -> str | None: + steps = ((lint.get("jobs") or {}).get(VALIDATOR) or {}).get("steps") or [] + return next((s.get("run") for s in steps if s.get("run")), None) + + +# (lint-only value, input overrides, accepted) +VALIDATION_CASES = [ + ("gitleaks", {}, True), + (" gitleaks , trivy ", {}, True), + ("gitleaks,trivy,", {}, True), + ("gitleaks, zizmor", {}, True), + ("config-drift", {"lint-config-drift": True}, True), + ("gitleak", {}, False), + ("gitleaks trivy", {}, False), + ("GitLeaks", {}, False), + ("gitleaks\ntrivy", {}, False), + ("gitleaks;trivy", {}, False), + (",", {}, False), + (" ", {}, False), + ("config-drift", {}, False), + ("trivy", {"lint-trivy": False}, False), +] + + +def check_validator(lint: dict) -> list[str]: + bash = shutil.which("bash") + script = validator_script(lint) + if not script: + return [f"jobs.{VALIDATOR} has no run script"] + if not bash or not shutil.which("jq"): + return ["bash and jq are needed to run the validator"] if os.environ.get("CI") else [] + defaults = {name: spec.get("default") for name, spec in call_inputs(lint).items()} + linters = sorted(set(lint.get("jobs") or {}) - NOT_LINTERS) + problems = [] + for value, overrides, accepted in VALIDATION_CASES: + env = {**os.environ, "LINT_ONLY": value, "INPUTS": json.dumps({**defaults, INPUT: value, **overrides})} + result = subprocess.run([bash, "-c", script], env=env, capture_output=True, text=True) + if (result.returncode == 0) != accepted: + problems.append(f"validator {'rejects' if accepted else 'accepts'} lint-only {value!r}: " + f"{result.stdout.strip() or result.stderr.strip()}") + if accepted: + names = {part.strip() for part in value.split(",")} - {""} + for name in linters: + if match_value(name, value) != (name in names): + problems.append(f"the job condition for {name} disagrees with the validator on {value!r}") + return problems + + +def broken_copies(lint: dict): + """Yield (description, mutated lint.yml) pairs that check() must reject.""" + + def mutate(description, change): + broken = copy.deepcopy(lint) + change(broken["jobs"]) + return description, broken + + def step(jobs, step_id): + return next(s for s in jobs["all-linters"]["steps"] if s.get("id") == step_id) + + def set_known(jobs, names): + run = jobs[VALIDATOR]["steps"][0]["run"] + jobs[VALIDATOR]["steps"][0]["run"] = KNOWN.sub(f'known="{names}"', run, count=1) + + yield mutate("a job without the match", lambda j: j["dprint"].update({"if": "${{ inputs.lint-dprint }}"})) + yield mutate("a job matching another linter's name", + lambda j: j["dprint"].update({"if": f"${{{{ inputs.lint-dprint && {match('trivy')} }}}}"})) + yield mutate("a new job without the match", + lambda j: j.update({"newtool": {"if": "${{ inputs.lint-newtool }}", "runs-on": "ubuntu-24.04"}})) + yield mutate("a new job without any if", lambda j: j.update({"newtool": {"runs-on": "ubuntu-24.04"}})) + yield mutate("the match only inside an || term", + lambda j: j["trivy"].update({"if": f"${{{{ inputs.lint-trivy || {match('trivy')} }}}}"})) + yield mutate("a single-job step without the match", + lambda j: step(j, "zizmor").update({"if": "${{ inputs.lint-zizmor }}"})) + yield mutate("a SARIF step without the match", + lambda j: step(j, "trivy-sarif").update({"if": "${{ inputs.lint-trivy && inputs.upload-sarif }}"})) + yield mutate("a new single-job step without any if", + lambda j: j["all-linters"]["steps"].insert(-1, {"name": "Run newtool", "id": "newtool", "run": "x"})) + yield mutate("a validator that can be ignored", lambda j: j[VALIDATOR].update({"continue-on-error": True})) + yield mutate("a validator that doesn't always run", + lambda j: j[VALIDATOR].update({"if": "${{ inputs.lint-only != '' && inputs.lint-fail-on-error }}"})) + yield mutate("a known list missing a linter", lambda j: set_known(j, "gitleaks trivy")) + for description, condition in ( + ("a step running when its predecessor was skipped", "${{ steps.setup-go.outcome == 'skipped' }}"), + ("a step on a negative output comparison", "${{ steps.go-version-file.outputs.exists != 'false' }}"), + ("a step on an empty-output comparison", "${{ steps.go-version-file.outputs.exists == '' }}"), + ("a predecessor reference inside ||", "${{ steps.setup-go.outcome == 'success' || inputs.lint-go }}"), + ("a predecessor reference inside a parenthesised ||", + "${{ (steps.setup-go.outcome == 'success' || always()) && inputs.golangci-lint-version != '' }}"), + ): + yield mutate(description, lambda j, c=condition: step(j, "go").update({"if": c})) + + +def main() -> int: + lint = yaml.safe_load(LINT.read_text(encoding="utf-8")) + failures = check(lint) + check_validator(lint) + + no_input = copy.deepcopy(lint) + call_inputs(no_input).pop(INPUT, None) + if not any(f"declare a string {INPUT}" in problem for problem in check(no_input)): + failures.append(f"self-test: a missing {INPUT} input was not caught") + cases = list(broken_copies(lint)) + for description, broken in cases: + if not check(broken): + failures.append(f"self-test: {description} was not caught") + + if failures: + print(f"✖ {len(failures)} {INPUT} problem(s):", file=sys.stderr) + for failure in failures: + print(f" - {failure}", file=sys.stderr) + return 1 + ran = f"{len(VALIDATION_CASES)} lists validated" if shutil.which("bash") and shutil.which("jq") else \ + "validator not run (no bash/jq)" + print(f"✓ {INPUT}: every lint.yml linter job and single-job step honours the list; {ran}; " + f"{len(cases) + 1} broken variants are caught.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/workflow-job-conditions.py b/tests/workflow-job-conditions.py index c1074bb2..64d22df4 100755 --- a/tests/workflow-job-conditions.py +++ b/tests/workflow-job-conditions.py @@ -266,6 +266,11 @@ def call(self, name, args): for index, arg in enumerate(args[1:]): result = result.replace("{" + str(index) + "}", "" if arg is None else str(arg)) return result + if name == "contains": + search, item = args + if isinstance(search, list): + return any(loose_equal(entry, item) for entry in search) + return str(item).lower() in ("" if search is None else str(search)).lower() raise ValueError(f"unsupported function {name}()") @@ -379,6 +384,7 @@ def lint_context(*, mode="auto", private=False, has_repository=True, event_name= inputs = {f"lint-{name}": True for name in ("dprint", "yamlfmt", "yamllint", "actionlint", "gitleaks", "go", "shellcheck", "shfmt", "checkov", "trivy", "zizmor")} inputs["lint-config-drift"] = False + inputs["lint-only"] = "" inputs["lint-job-mode"] = mode inputs.update({f"lint-{k.replace('_', '-')}": v for k, v in toggles.items()}) event = {"repository": {"private": private}} if has_repository else {"schedule": "0 0 * * 1"} @@ -400,11 +406,15 @@ def lint_context(*, mode="auto", private=False, has_repository=True, event_name= PER_LINTER - {"go", "trivy"}), ("public repo, config drift on", lint_context(config_drift=True), PER_LINTER | {"config-drift"}), ("invalid mode fails loudly in the single job", lint_context(mode="bogus"), SINGLE), - ("public repo, gitleaks only", lint_context(gitleaks_only=True, config_drift=True), {"gitleaks"}), - ("private repo, parallel, gitleaks only", lint_context(mode="parallel", private=True, gitleaks_only=True), - {"gitleaks"}), - ("private repo, gitleaks only (steps gated in the single job)", lint_context(private=True, gitleaks_only=True), - SINGLE), + ("public repo, lint-only gitleaks", lint_context(only="gitleaks", config_drift=True), {"gitleaks", "lint-only"}), + ("public repo, lint-only with spaces", lint_context(only=" gitleaks , trivy"), {"gitleaks", "trivy", "lint-only"}), + ("public repo, lint-only lists a disabled linter", lint_context(only="gitleaks,go", go=False), + {"gitleaks", "lint-only"}), + ("public repo, lint-only typo runs only the validation", lint_context(only="gitleak"), {"lint-only"}), + ("private repo, parallel, lint-only gitleaks", lint_context(mode="parallel", private=True, only="gitleaks"), + {"gitleaks", "lint-only"}), + ("private repo, lint-only gitleaks (steps gated in the single job)", lint_context(private=True, only="gitleaks"), + SINGLE | {"lint-only"}), ] for name, context, expected in lint_scenarios: check("lint.yml", name, running_jobs(lint, context), expected) From 6d930d5af4f16039caf53794f2cd03c94444a174 Mon Sep 17 00:00:00 2001 From: Jean-Paul van Ravensberg <14926452+DevSecNinja@users.noreply.github.com> Date: Tue, 17 Nov 2026 11:13:19 +0100 Subject: [PATCH 5/5] feat(lint): add lint-include workflow that runs only the linters a caller enables Owner decision on #551: keep lint.yml as the exclude mode and add a thin include-mode front end instead of a lint-only input. lint-include.yml redeclares every lint.yml input with each lint- linter defaulting to false and passes them all to lint.yml through the \$/ self-repository syntax (actionlint ignore tracked in #552). tests/lint-include.py fails CI when an input isn't declared, defaulted or forwarded correctly. The secret-scan caller uses it with lint-gitleaks: true. The lint-only input and its checks are removed. Closes #549 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/actionlint.yaml | 9 + .github/workflows/lint-include.yml | 160 +++++++++++++ .github/workflows/lint.yml | 185 +++------------ .github/workflows/secret-scan-caller.yml | 7 +- .mise.toml | 2 +- docs/architecture.md | 43 ++-- tests/lint-include.py | 157 +++++++++++++ tests/lint-job-modes-contract.sh | 7 +- tests/lint-only.py | 278 ----------------------- tests/workflow-job-conditions.py | 15 -- 10 files changed, 393 insertions(+), 470 deletions(-) create mode 100644 .github/actionlint.yaml create mode 100644 .github/workflows/lint-include.yml create mode 100644 tests/lint-include.py delete mode 100644 tests/lint-only.py diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml new file mode 100644 index 00000000..d3be07dc --- /dev/null +++ b/.github/actionlint.yaml @@ -0,0 +1,9 @@ +--- +# actionlint configuration: https://github.com/rhysd/actionlint/blob/main/docs/config.md +paths: + .github/workflows/lint-include.yml: + ignore: + # actionlint (1.7.12) predates GitHub's `$/` self-repository syntax for + # reusable workflow calls (July 2026). Drop this once it supports it + # (#552). + - 'reusable workflow call "\$/\.github/workflows/lint\.yml" at "uses" is not following the format' diff --git a/.github/workflows/lint-include.yml b/.github/workflows/lint-include.yml new file mode 100644 index 00000000..7dedcdf4 --- /dev/null +++ b/.github/workflows/lint-include.yml @@ -0,0 +1,160 @@ +--- +name: Reusable — Lint (include mode) + +# Include mode of the reusable Lint workflow: every linter is off unless the +# caller turns it on (`lint-gitleaks: true` runs gitleaks and nothing else). +# Linters added to lint.yml later stay off here until a caller enables them. +# lint.yml itself is the exclude mode: every linter on, `lint-: false` +# turns one off. This file only redeclares lint.yml's inputs, with every +# `lint-` linter defaulting to false, and passes them all through. +# tests/lint-include.py fails CI when an input of lint.yml is missing here, +# isn't passed through unchanged, or a linter doesn't default to false. +on: + workflow_call: + inputs: + mise-version: + description: "mise version to install" + required: true + type: string + golangci-lint-version: + description: "golangci-lint version to install (required only when Go linting runs)" + required: false + type: string + default: "" + go-version-file: + description: "Path to the Go version file" + required: false + type: string + default: "go.mod" + lint-config-dir: + description: "Directory containing optional linter config files" + required: false + type: string + default: "" + lint-fail-on-error: + description: "Fail the workflow when a linter fails" + required: false + type: boolean + default: false + lint-dprint: + description: "Run dprint (Markdown formatting)" + required: false + type: boolean + default: false + lint-yamlfmt: + description: "Run yamlfmt (YAML formatting)" + required: false + type: boolean + default: false + lint-yamllint: + description: "Run yamllint (YAML linting)" + required: false + type: boolean + default: false + lint-actionlint: + description: "Run actionlint (GitHub Actions linting)" + required: false + type: boolean + default: false + lint-gitleaks: + description: "Run gitleaks (secret scanning)" + required: false + type: boolean + default: false + lint-go: + description: "Run golangci-lint (Go linting)" + required: false + type: boolean + default: false + lint-shellcheck: + description: "Run shellcheck (shell linting)" + required: false + type: boolean + default: false + lint-shellcheck-exclude: + description: "Glob pattern for paths to exclude from shellcheck (passed to find -not -path)" + required: false + type: string + default: "" + lint-shfmt: + description: "Run shfmt (shell formatting)" + required: false + type: boolean + default: false + lint-shfmt-exclude: + description: "Glob pattern for paths to exclude from shfmt (passed to find -not -path)" + required: false + type: string + default: "" + lint-checkov: + description: "Run checkov (IaC security) — uploads SARIF" + required: false + type: boolean + default: false + lint-trivy: + description: "Run trivy fs (misconfig + secrets) — uploads SARIF" + required: false + type: boolean + default: false + lint-zizmor: + description: "Run zizmor (Actions security) — uploads SARIF" + required: false + type: boolean + default: false + lint-config-drift: + description: "Check local config files match central DevSecNinja/.github repo" + required: false + type: boolean + default: false + upload-sarif: + description: "Upload checkov/trivy/zizmor results to GitHub code scanning (requires GitHub Advanced Security). Set + false for private repos without GHAS to gate on exit codes with console output instead." + required: false + type: boolean + default: true + lint-job-mode: + description: "How linters are scheduled: auto (default), single or parallel. See lint.yml." + required: false + type: string + default: auto + +permissions: + contents: read + +jobs: + lint: + # `$/` (self-repository syntax) resolves to this workflow's own repository + # at the commit that is running, so a caller pinning lint-include.yml@ + # gets lint.yml from that same commit, and this repository's callers test + # local changes to both. `./` is workspace-relative, so it isn't + # guaranteed to resolve to this repository when another repository calls + # this workflow, and an `owner/repo/...@` pin would lag behind + # lint.yml. actionlint doesn't know `$/` yet: .github/actionlint.yaml + # ignores that one error (#552). + uses: $/.github/workflows/lint.yml + permissions: + contents: read + # checkov, trivy, zizmor and gitleaks history findings go to code scanning. + security-events: write + with: + mise-version: ${{ inputs.mise-version }} + golangci-lint-version: ${{ inputs.golangci-lint-version }} + go-version-file: ${{ inputs.go-version-file }} + lint-config-dir: ${{ inputs.lint-config-dir }} + lint-fail-on-error: ${{ inputs.lint-fail-on-error }} + lint-dprint: ${{ inputs.lint-dprint }} + lint-yamlfmt: ${{ inputs.lint-yamlfmt }} + lint-yamllint: ${{ inputs.lint-yamllint }} + lint-actionlint: ${{ inputs.lint-actionlint }} + lint-gitleaks: ${{ inputs.lint-gitleaks }} + lint-go: ${{ inputs.lint-go }} + lint-shellcheck: ${{ inputs.lint-shellcheck }} + lint-shellcheck-exclude: ${{ inputs.lint-shellcheck-exclude }} + lint-shfmt: ${{ inputs.lint-shfmt }} + lint-shfmt-exclude: ${{ inputs.lint-shfmt-exclude }} + lint-checkov: ${{ inputs.lint-checkov }} + lint-trivy: ${{ inputs.lint-trivy }} + lint-zizmor: ${{ inputs.lint-zizmor }} + lint-config-drift: ${{ inputs.lint-config-drift }} + upload-sarif: ${{ inputs.upload-sarif }} + lint-job-mode: ${{ inputs.lint-job-mode }} diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 61ad545a..ffeba40b 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -28,14 +28,6 @@ on: required: false type: boolean default: false - lint-only: - description: >- - Comma-separated linters to run, e.g. `gitleaks` or `gitleaks, trivy` (names as in the `lint-*` inputs). Every - other linter is skipped, including linters added in later releases. A listed linter still needs its `lint-*` - input on. Empty (default): run every enabled linter. An unknown or disabled name fails the run. - required: false - type: string - default: "" lint-dprint: description: "Run dprint (Markdown formatting)" required: false @@ -133,9 +125,7 @@ defaults: jobs: dprint: name: dprint - if: ${{ inputs.lint-dprint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',dprint,') || contains(format(',{0},', - inputs.lint-only), ',dprint ') || contains(format(',{0},', inputs.lint-only), ' dprint,') || contains(format(',{0},', - inputs.lint-only), ' dprint ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + if: ${{ inputs.lint-dprint && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -178,10 +168,8 @@ jobs: yamlfmt: name: yamlfmt - if: ${{ inputs.lint-yamlfmt && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',yamlfmt,') || - contains(format(',{0},', inputs.lint-only), ',yamlfmt ') || contains(format(',{0},', inputs.lint-only), ' yamlfmt,') - || contains(format(',{0},', inputs.lint-only), ' yamlfmt ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-yamlfmt && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -222,10 +210,8 @@ jobs: yamllint: name: yamllint - if: ${{ inputs.lint-yamllint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',yamllint,') || - contains(format(',{0},', inputs.lint-only), ',yamllint ') || contains(format(',{0},', inputs.lint-only), ' yamllint,') - || contains(format(',{0},', inputs.lint-only), ' yamllint ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-yamllint && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -266,10 +252,8 @@ jobs: actionlint: name: actionlint - if: ${{ inputs.lint-actionlint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',actionlint,') - || contains(format(',{0},', inputs.lint-only), ',actionlint ') || contains(format(',{0},', inputs.lint-only), ' actionlint,') - || contains(format(',{0},', inputs.lint-only), ' actionlint ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-actionlint && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -290,10 +274,8 @@ jobs: gitleaks: name: gitleaks - if: ${{ inputs.lint-gitleaks && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',gitleaks,') || - contains(format(',{0},', inputs.lint-only), ',gitleaks ') || contains(format(',{0},', inputs.lint-only), ' gitleaks,') - || contains(format(',{0},', inputs.lint-only), ' gitleaks ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-gitleaks && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -504,9 +486,7 @@ jobs: category: gitleaks/history go: name: go - if: ${{ inputs.lint-go && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',go,') || contains(format(',{0},', - inputs.lint-only), ',go ') || contains(format(',{0},', inputs.lint-only), ' go,') || contains(format(',{0},', inputs.lint-only), - ' go ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + if: ${{ inputs.lint-go && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -551,10 +531,8 @@ jobs: shellcheck: name: shellcheck - if: ${{ inputs.lint-shellcheck && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',shellcheck,') - || contains(format(',{0},', inputs.lint-only), ',shellcheck ') || contains(format(',{0},', inputs.lint-only), ' shellcheck,') - || contains(format(',{0},', inputs.lint-only), ' shellcheck ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-shellcheck && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -609,9 +587,7 @@ jobs: shfmt: name: shfmt - if: ${{ inputs.lint-shfmt && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',shfmt,') || contains(format(',{0},', - inputs.lint-only), ',shfmt ') || contains(format(',{0},', inputs.lint-only), ' shfmt,') || contains(format(',{0},', - inputs.lint-only), ' shfmt ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + if: ${{ inputs.lint-shfmt && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -651,10 +627,8 @@ jobs: checkov: name: checkov - if: ${{ inputs.lint-checkov && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',checkov,') || - contains(format(',{0},', inputs.lint-only), ',checkov ') || contains(format(',{0},', inputs.lint-only), ' checkov,') - || contains(format(',{0},', inputs.lint-only), ' checkov ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-checkov && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 15 @@ -708,9 +682,7 @@ jobs: trivy: name: trivy - if: ${{ inputs.lint-trivy && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',trivy,') || contains(format(',{0},', - inputs.lint-only), ',trivy ') || contains(format(',{0},', inputs.lint-only), ' trivy,') || contains(format(',{0},', - inputs.lint-only), ' trivy ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + if: ${{ inputs.lint-trivy && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -772,9 +744,7 @@ jobs: zizmor: name: zizmor - if: ${{ inputs.lint-zizmor && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',zizmor,') || contains(format(',{0},', - inputs.lint-only), ',zizmor ') || contains(format(',{0},', inputs.lint-only), ' zizmor,') || contains(format(',{0},', - inputs.lint-only), ' zizmor ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + if: ${{ inputs.lint-zizmor && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 @@ -814,10 +784,8 @@ jobs: config-drift: name: config drift - if: ${{ inputs.lint-config-drift && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',config-drift,') - || contains(format(',{0},', inputs.lint-only), ',config-drift ') || contains(format(',{0},', inputs.lint-only), ' config-drift,') - || contains(format(',{0},', inputs.lint-only), ' config-drift ')) && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode - == 'auto' && !github.event.repository.private)) }} + if: ${{ inputs.lint-config-drift && (inputs.lint-job-mode == 'parallel' || (inputs.lint-job-mode == 'auto' && !github.event.repository.private)) + }} continue-on-error: ${{ ! inputs.lint-fail-on-error }} runs-on: ubuntu-24.04 timeout-minutes: 10 @@ -862,53 +830,6 @@ jobs: echo "" echo "All config files match the central repository." - lint-only: - # Checks the `lint-only` list whenever it is set, in both job modes. No - # continue-on-error: a typo or a disabled linter would otherwise skip that - # linter without a trace. The linter conditions match a name with spaces - # or commas on either side (expressions have no split or trim), so this - # accepts only names, commas and spaces. tests/lint-only.py keeps `known` - # equal to the linter jobs. - name: lint-only - if: ${{ inputs.lint-only != '' }} - runs-on: ubuntu-24.04 - timeout-minutes: 5 - permissions: {} - steps: - - name: Validate lint-only - env: - LINT_ONLY: ${{ inputs.lint-only }} - INPUTS: ${{ toJSON(inputs) }} - run: |- - known="dprint yamlfmt yamllint actionlint gitleaks go shellcheck shfmt checkov trivy zizmor config-drift" - if [[ "${LINT_ONLY}" =~ [^a-z0-9,\ -] ]]; then - echo "::error::lint-only must be a comma-separated list of lowercase linter names (got '${LINT_ONLY}')." - exit 1 - fi - status=0 - listed=0 - IFS=, read -ra entries <<<"${LINT_ONLY}" - for entry in "${entries[@]}"; do - name="${entry// /}" - [ -n "${name}" ] || continue - listed=$((listed + 1)) - if [[ "${entry}" =~ [a-z0-9-]\ +[a-z0-9-] ]]; then - echo "::error::lint-only entry '${entry}' holds more than one name; separate names with commas." - status=1 - elif [[ " ${known} " != *" ${name} "* ]]; then - echo "::error::lint-only lists unknown linter '${name}'. Known linters: ${known// /, }." - status=1 - elif [ "$(jq -r --arg key "lint-${name}" '.[$key]' <<<"${INPUTS}")" != true ]; then - echo "::error::lint-only lists '${name}', but lint-${name} is false, so it would not run." - status=1 - fi - done - if [ "${listed}" -eq 0 ]; then - echo "::error::lint-only is set but lists no linter." - status=1 - fi - exit "${status}" - all-linters: # Single-job mode (`lint-job-mode: single`, or `auto` on a private # repository). Every enabled linter runs as a step of this one job, so a @@ -959,9 +880,7 @@ jobs: - name: Check formatting with dprint id: dprint - if: ${{ inputs.lint-dprint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',dprint,') || - contains(format(',{0},', inputs.lint-only), ',dprint ') || contains(format(',{0},', inputs.lint-only), ' dprint,') - || contains(format(',{0},', inputs.lint-only), ' dprint ')) }} + if: ${{ inputs.lint-dprint }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -988,9 +907,7 @@ jobs: - name: Check YAML formatting id: yamlfmt - if: ${{ inputs.lint-yamlfmt && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',yamlfmt,') - || contains(format(',{0},', inputs.lint-only), ',yamlfmt ') || contains(format(',{0},', inputs.lint-only), ' yamlfmt,') - || contains(format(',{0},', inputs.lint-only), ' yamlfmt ')) }} + if: ${{ inputs.lint-yamlfmt }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -1016,9 +933,7 @@ jobs: - name: Run yamllint id: yamllint - if: ${{ inputs.lint-yamllint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',yamllint,') - || contains(format(',{0},', inputs.lint-only), ',yamllint ') || contains(format(',{0},', inputs.lint-only), ' yamllint,') - || contains(format(',{0},', inputs.lint-only), ' yamllint ')) }} + if: ${{ inputs.lint-yamllint }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -1044,17 +959,13 @@ jobs: - name: Run actionlint id: actionlint - if: ${{ inputs.lint-actionlint && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',actionlint,') - || contains(format(',{0},', inputs.lint-only), ',actionlint ') || contains(format(',{0},', inputs.lint-only), ' - actionlint,') || contains(format(',{0},', inputs.lint-only), ' actionlint ')) }} + if: ${{ inputs.lint-actionlint }} continue-on-error: true run: mise exec -- actionlint - name: Run gitleaks id: gitleaks - if: ${{ inputs.lint-gitleaks && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',gitleaks,') - || contains(format(',{0},', inputs.lint-only), ',gitleaks ') || contains(format(',{0},', inputs.lint-only), ' gitleaks,') - || contains(format(',{0},', inputs.lint-only), ' gitleaks ')) }} + if: ${{ inputs.lint-gitleaks }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -1173,9 +1084,7 @@ jobs: fi - name: Report gitleaks findings - if: ${{ !cancelled() && inputs.lint-gitleaks && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), - ',gitleaks,') || contains(format(',{0},', inputs.lint-only), ',gitleaks ') || contains(format(',{0},', inputs.lint-only), - ' gitleaks,') || contains(format(',{0},', inputs.lint-only), ' gitleaks ')) }} + if: ${{ !cancelled() && inputs.lint-gitleaks }} env: SCAN_MODE: ${{ steps.gitleaks.outputs.mode }} FINDINGS_ARTIFACT: gitleaks-findings-${{ job.check_run_id }} @@ -1249,9 +1158,7 @@ jobs: category: gitleaks/history - name: Check for Go version file id: go-version-file - if: ${{ inputs.lint-go && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',go,') || contains(format(',{0},', - inputs.lint-only), ',go ') || contains(format(',{0},', inputs.lint-only), ' go,') || contains(format(',{0},', inputs.lint-only), - ' go ')) }} + if: ${{ inputs.lint-go }} env: GO_VERSION_FILE: ${{ inputs.go-version-file }} run: |- @@ -1290,9 +1197,7 @@ jobs: - name: Run shellcheck id: shellcheck - if: ${{ inputs.lint-shellcheck && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',shellcheck,') - || contains(format(',{0},', inputs.lint-only), ',shellcheck ') || contains(format(',{0},', inputs.lint-only), ' - shellcheck,') || contains(format(',{0},', inputs.lint-only), ' shellcheck ')) }} + if: ${{ inputs.lint-shellcheck }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -1332,9 +1237,7 @@ jobs: - name: Run shfmt id: shfmt - if: ${{ inputs.lint-shfmt && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',shfmt,') || - contains(format(',{0},', inputs.lint-only), ',shfmt ') || contains(format(',{0},', inputs.lint-only), ' shfmt,') - || contains(format(',{0},', inputs.lint-only), ' shfmt ')) }} + if: ${{ inputs.lint-shfmt }} continue-on-error: true env: EXCLUDE_PATTERN: ${{ inputs.lint-shfmt-exclude }} @@ -1358,9 +1261,7 @@ jobs: - name: Run checkov id: checkov - if: ${{ inputs.lint-checkov && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',checkov,') - || contains(format(',{0},', inputs.lint-only), ',checkov ') || contains(format(',{0},', inputs.lint-only), ' checkov,') - || contains(format(',{0},', inputs.lint-only), ' checkov ')) }} + if: ${{ inputs.lint-checkov }} continue-on-error: true env: UPLOAD_SARIF: ${{ inputs.upload-sarif }} @@ -1374,9 +1275,7 @@ jobs: - name: Filter skipped checks from SARIF id: checkov-sarif-filter - if: ${{ inputs.lint-checkov && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',checkov,') - || contains(format(',{0},', inputs.lint-only), ',checkov ') || contains(format(',{0},', inputs.lint-only), ' checkov,') - || contains(format(',{0},', inputs.lint-only), ' checkov ')) && inputs.upload-sarif }} + if: ${{ inputs.lint-checkov && inputs.upload-sarif }} continue-on-error: true run: |- sarif="${RUNNER_TEMP}/results_sarif.sarif" @@ -1393,9 +1292,7 @@ jobs: - name: Upload checkov SARIF report id: checkov-sarif - if: ${{ inputs.lint-checkov && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',checkov,') - || contains(format(',{0},', inputs.lint-only), ',checkov ') || contains(format(',{0},', inputs.lint-only), ' checkov,') - || contains(format(',{0},', inputs.lint-only), ' checkov ')) && inputs.upload-sarif }} + if: ${{ inputs.lint-checkov && inputs.upload-sarif }} continue-on-error: true uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 with: @@ -1404,9 +1301,7 @@ jobs: - name: Run trivy id: trivy - if: ${{ inputs.lint-trivy && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',trivy,') || - contains(format(',{0},', inputs.lint-only), ',trivy ') || contains(format(',{0},', inputs.lint-only), ' trivy,') - || contains(format(',{0},', inputs.lint-only), ' trivy ')) }} + if: ${{ inputs.lint-trivy }} continue-on-error: true env: CONFIG_DIR: ${{ inputs.lint-config-dir }} @@ -1442,9 +1337,7 @@ jobs: - name: Upload trivy SARIF report id: trivy-sarif - if: ${{ inputs.lint-trivy && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',trivy,') || - contains(format(',{0},', inputs.lint-only), ',trivy ') || contains(format(',{0},', inputs.lint-only), ' trivy,') - || contains(format(',{0},', inputs.lint-only), ' trivy ')) && inputs.upload-sarif }} + if: ${{ inputs.lint-trivy && inputs.upload-sarif }} continue-on-error: true uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 with: @@ -1453,9 +1346,7 @@ jobs: - name: Run zizmor id: zizmor - if: ${{ inputs.lint-zizmor && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',zizmor,') || - contains(format(',{0},', inputs.lint-only), ',zizmor ') || contains(format(',{0},', inputs.lint-only), ' zizmor,') - || contains(format(',{0},', inputs.lint-only), ' zizmor ')) }} + if: ${{ inputs.lint-zizmor }} continue-on-error: true env: UPLOAD_SARIF: ${{ inputs.upload-sarif }} @@ -1469,9 +1360,7 @@ jobs: - name: Upload zizmor SARIF report id: zizmor-sarif - if: ${{ inputs.lint-zizmor && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',zizmor,') || - contains(format(',{0},', inputs.lint-only), ',zizmor ') || contains(format(',{0},', inputs.lint-only), ' zizmor,') - || contains(format(',{0},', inputs.lint-only), ' zizmor ')) && inputs.upload-sarif }} + if: ${{ inputs.lint-zizmor && inputs.upload-sarif }} continue-on-error: true uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 with: @@ -1480,9 +1369,7 @@ jobs: - name: Check config drift against central repo id: config-drift - if: ${{ inputs.lint-config-drift && (inputs.lint-only == '' || contains(format(',{0},', inputs.lint-only), ',config-drift,') - || contains(format(',{0},', inputs.lint-only), ',config-drift ') || contains(format(',{0},', inputs.lint-only), - ' config-drift,') || contains(format(',{0},', inputs.lint-only), ' config-drift ')) }} + if: ${{ inputs.lint-config-drift }} continue-on-error: true run: |- BASE_URL="https://raw.githubusercontent.com/DevSecNinja/.github/main/config-sync/files" diff --git a/.github/workflows/secret-scan-caller.yml b/.github/workflows/secret-scan-caller.yml index 9f0baa18..59a8534c 100644 --- a/.github/workflows/secret-scan-caller.yml +++ b/.github/workflows/secret-scan-caller.yml @@ -23,7 +23,9 @@ concurrency: jobs: gitleaks: # Local reference validates reusable workflow changes in this repository. - uses: ./.github/workflows/lint.yml + # Include mode: only the linters set to true run, so linters added to + # lint.yml later stay off here. + uses: ./.github/workflows/lint-include.yml permissions: contents: read security-events: write @@ -34,5 +36,4 @@ jobs: # History findings only report; this fails the run when the scan or the # code scanning upload fails, so a silent gap can't look green. lint-fail-on-error: true - # Skips every other linter, including ones added to lint.yml later. - lint-only: gitleaks + lint-gitleaks: true diff --git a/.mise.toml b/.mise.toml index 3a3e7fbe..00192f8b 100644 --- a/.mise.toml +++ b/.mise.toml @@ -33,7 +33,7 @@ run = [ "bash ./tests/release-please-auth-contract.sh", "bash ./tests/automation-app-contract.sh", "uv run --script ./tests/app-key-confinement.py", - "uv run --script ./tests/lint-only.py", + "uv run --script ./tests/lint-include.py", "bash ./tests/lint-job-modes-contract.sh", "bash ./tests/open-pr-push.sh", "bash ./tests/open-pr-api-commit.sh", diff --git a/docs/architecture.md b/docs/architecture.md index 87b96c54..48ce7e3a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -115,11 +115,11 @@ on the event (v4.1.0+): failed visibility lookup count as public. Repositories whose Lint caller runs on pull requests only get the full-history scan from a second caller, after each merge, weekly and on dispatch (this - repository's `secret-scan-caller.yml`). It sets `lint-only: gitleaks` - (v4.4.0+), which skips every other linter, including linters added to - `lint.yml` later, so the caller keeps no list of linters to turn off. A Lint - caller that also runs on push already scans the history there, so drop `push` - below. + repository's `secret-scan-caller.yml`). It calls the include mode, + [`lint-include.yml`](#lint-include-mode-lint-includeyml), with only + `lint-gitleaks: true`, so linters added to `lint.yml` later never start + running there. A Lint caller that also runs on push already scans the history + there, so drop `push` below. ```yaml name: Secret scan @@ -135,7 +135,7 @@ permissions: jobs: gitleaks: - uses: DevSecNinja/.github/.github/workflows/lint.yml@ # v4.4.0 + uses: DevSecNinja/.github/.github/workflows/lint-include.yml@ # v4.4.0 permissions: contents: read security-events: write @@ -144,9 +144,8 @@ jobs: mise-version: "2026.10.19" # Findings only report; fail the run if the scan or upload fails. lint-fail-on-error: true - # Run gitleaks and nothing else, now and after future linter additions. - lint-only: gitleaks # upload-sarif: false # private repos without GitHub Advanced Security + lint-gitleaks: true ``` | Input | Description | @@ -156,7 +155,6 @@ jobs: | `go-version-file` | Go version file for setup-go. Default: `go.mod`. | | `lint-config-dir` | Optional linter config directory. Default: `""`. | | `lint-fail-on-error` | Fail when a linter fails. Default: `false`. | -| `lint-only` | Run only these linters, e.g. `gitleaks` (see below). Default: `""`. | | `lint-job-mode` | `auto`, `single`, or `parallel` (see above). Default: `auto`. v3.3.0+. | | `upload-sarif` | Upload checkov/trivy/zizmor SARIF to code scanning. Default: `true`. | | `lint-dprint` | Markdown formatting (dprint). Default: `true`. | @@ -172,17 +170,6 @@ jobs: | `lint-zizmor` | Actions security scan (zizmor). Default: `true`. | | `lint-config-drift` | Config-drift check. Default: `false`. | -**Running only some linters (v4.4.0+).** `lint-only` takes a comma-separated -list of linter names, the `lint-*` input names without the prefix (`dprint`, -`gitleaks`, `config-drift`, …); spaces around the commas are fine. Only the -listed linters run, and linters added to `lint.yml` later stay off, which the -`lint-*: false` switches can't promise. A listed linter still needs its -`lint-*` input on (`config-drift` also needs `lint-config-drift: true`). A -`lint-only` job checks the list whenever it is set and fails the run on an -unknown name, a disabled linter or an empty list, whatever -`lint-fail-on-error` says, so a typo can't silently skip a scan. That job is -billed like any other. - **Example caller:** ```yaml @@ -216,6 +203,22 @@ jobs: # lint-job-mode: auto # single | parallel ``` +### Lint, include mode (`lint-include.yml`) + +`lint.yml` is the exclude mode: every linter runs unless the caller sets +`lint-: false`. `lint-include.yml` (v4.4.0+) is the include mode: every +linter is off unless the caller sets `lint-: true`, and linters added to +`lint.yml` later stay off until a caller enables them. Use it when a caller +wants a few specific linters, such as the secret-scan caller above, instead of +keeping a list of linters to turn off. + +It takes the same inputs as `lint.yml` with the same defaults, except that +every `lint-` linter defaults to `false`, and passes them all to the +`lint.yml` of the same commit (through GitHub's `$/` self-repository syntax), +so linters behave exactly as described above. Grant the calling job +`contents: read` and `security-events: write`. `tests/lint-include.py` fails CI +when `lint.yml` gains an input that `lint-include.yml` doesn't forward. + ### Auto-fix formatting (`autofix.yml`) Runs dprint, yamlfmt, and shfmt in write mode, then commits and pushes any diff --git a/tests/lint-include.py b/tests/lint-include.py new file mode 100644 index 00000000..c401d4b2 --- /dev/null +++ b/tests/lint-include.py @@ -0,0 +1,157 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.9" +# dependencies = ["pyyaml==6.0.3"] +# /// +"""Keep lint-include.yml a faithful include-mode front end for lint.yml. + +lint-include.yml redeclares every input of lint.yml and passes it straight +through, with every `lint-` linter defaulting to false, so callers run +only the linters they turn on and a linter added to lint.yml later stays off +for them. This test fails when: + +- lint.yml has an input lint-include.yml doesn't declare, or the other way + round; +- an input's type differs, a linter input isn't optional with default false, + or another input's `required`/`default` differs from lint.yml; +- lint-include.yml isn't a single job calling `$/.github/workflows/lint.yml` + that passes every input through as `${{ inputs. }}`; +- that job grants fewer permissions than lint.yml's jobs use. + +Broken copies are checked too, to prove the test bites. +""" + +from __future__ import annotations + +import copy +import sys +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parent.parent +LINT = ROOT / ".github" / "workflows" / "lint.yml" +INCLUDE = ROOT / ".github" / "workflows" / "lint-include.yml" + +LINT_REF = "$/.github/workflows/lint.yml" +# Boolean `lint-*` inputs of lint.yml that are options rather than linters. +NOT_LINTERS = {"lint-fail-on-error"} +LEVELS = {"none": 0, "read": 1, "write": 2} + + +def call_inputs(workflow: dict) -> dict: + # PyYAML (YAML 1.1) reads the `on` key as True. + triggers = workflow.get("on", workflow.get(True)) or {} + return (triggers.get("workflow_call") or {}).get("inputs") or {} + + +def is_linter(name: str, spec: dict) -> bool: + return name.startswith("lint-") and (spec or {}).get("type") == "boolean" and name not in NOT_LINTERS + + +def needed_permissions(lint: dict) -> dict: + """The highest level lint.yml's jobs use per scope.""" + needed: dict = {} + scopes = [lint.get("permissions")] + [(job or {}).get("permissions") for job in (lint.get("jobs") or {}).values()] + for scope in scopes: + for name, level in (scope or {}).items() if isinstance(scope, dict) else (): + if LEVELS.get(level, 0) > LEVELS.get(needed.get(name, "none"), 0): + needed[name] = level + return needed + + +def check(lint: dict, include: dict) -> list[str]: + problems: list[str] = [] + lint_inputs, include_inputs = call_inputs(lint), call_inputs(include) + for name in sorted(set(lint_inputs) - set(include_inputs)): + problems.append(f"lint-include.yml does not declare lint.yml input {name}") + for name in sorted(set(include_inputs) - set(lint_inputs)): + problems.append(f"lint-include.yml declares {name}, which lint.yml doesn't have") + + for name in sorted(set(lint_inputs) & set(include_inputs)): + want, got = lint_inputs[name] or {}, include_inputs[name] or {} + if got.get("type") != want.get("type"): + problems.append(f"input {name} must be type {want.get('type')}, got {got.get('type')}") + if is_linter(name, want): + if got.get("required") is not False or got.get("default") is not False: + problems.append(f"linter input {name} must be optional with default: false") + continue + for key in ("required", "default"): + if got.get(key) != want.get(key): + problems.append(f"input {name} must have {key}: {want.get(key)!r} like lint.yml, got {got.get(key)!r}") + + jobs = include.get("jobs") or {} + if len(jobs) != 1: + problems.append("lint-include.yml must have exactly one job") + return problems + job_id, job = next(iter(jobs.items())) + job = job or {} + if job.get("uses") != LINT_REF: + problems.append(f"jobs.{job_id} must call {LINT_REF}, got {job.get('uses')!r}") + given = job.get("with") or {} + for name in sorted(lint_inputs): + if given.get(name) != f"${{{{ inputs.{name} }}}}": + problems.append(f"jobs.{job_id}.with.{name} must be ${{{{ inputs.{name} }}}}, got {given.get(name)!r}") + for name in sorted(set(given) - set(lint_inputs)): + problems.append(f"jobs.{job_id}.with.{name} is not an input of lint.yml") + + granted = job.get("permissions") or {} + for name, level in sorted(needed_permissions(lint).items()): + if LEVELS.get(granted.get(name, "none"), 0) < LEVELS[level]: + problems.append(f"jobs.{job_id}.permissions must grant {name}: {level} (lint.yml uses it)") + return problems + + +def broken_copies(lint: dict, include: dict): + """Yield (description, lint.yml, lint-include.yml) triples that check() must reject.""" + + def mutate(description, change, target="include"): + broken_lint, broken_include = copy.deepcopy(lint), copy.deepcopy(include) + change(broken_lint if target == "lint" else broken_include) + return description, broken_lint, broken_include + + def job(workflow): + return next(iter(workflow["jobs"].values())) + + yield mutate("a new lint.yml linter", + lambda w: call_inputs(w).update({"lint-newtool": {"type": "boolean", "default": True}}), "lint") + yield mutate("a new lint.yml option", + lambda w: call_inputs(w).update({"lint-newtool-args": {"type": "string", "default": ""}}), "lint") + yield mutate("a linter defaulting to true", lambda w: call_inputs(w)["lint-trivy"].update({"default": True})) + yield mutate("a linter without a default", lambda w: call_inputs(w)["lint-trivy"].pop("default")) + yield mutate("an option default that drifted", lambda w: call_inputs(w)["upload-sarif"].update({"default": False})) + yield mutate("an optional mise-version", lambda w: call_inputs(w)["mise-version"].update({"required": False})) + yield mutate("a retyped input", lambda w: call_inputs(w)["lint-job-mode"].update({"type": "boolean"})) + yield mutate("an input not passed through", lambda w: job(w)["with"].pop("lint-shfmt-exclude")) + yield mutate("a hard-coded value", lambda w: job(w)["with"].update({"lint-zizmor": False})) + yield mutate("a value from another input", + lambda w: job(w)["with"].update({"lint-trivy": "${{ inputs.lint-checkov }}"})) + yield mutate("a workspace-relative call", lambda w: job(w).update({"uses": "./.github/workflows/lint.yml"})) + yield mutate("a missing permission", lambda w: job(w)["permissions"].pop("security-events")) + yield mutate("a downgraded permission", lambda w: job(w)["permissions"].update({"security-events": "read"})) + yield mutate("a permission lint.yml starts to need", + lambda w: w["jobs"]["trivy"]["permissions"].update({"actions": "read"}), "lint") + + +def main() -> int: + lint = yaml.safe_load(LINT.read_text(encoding="utf-8")) + include = yaml.safe_load(INCLUDE.read_text(encoding="utf-8")) + failures = check(lint, include) + cases = list(broken_copies(lint, include)) + for description, broken_lint, broken_include in cases: + if not check(broken_lint, broken_include): + failures.append(f"self-test: {description} was not caught") + + if failures: + print(f"✖ {len(failures)} lint-include.yml problem(s):", file=sys.stderr) + for failure in failures: + print(f" - {failure}", file=sys.stderr) + return 1 + linters = sum(is_linter(name, spec) for name, spec in call_inputs(lint).items()) + print(f"✓ lint-include.yml forwards all {len(call_inputs(lint))} lint.yml inputs ({linters} linters off by " + f"default); {len(cases)} broken variants are caught.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/lint-job-modes-contract.sh b/tests/lint-job-modes-contract.sh index 574c92da..bcb7eb93 100755 --- a/tests/lint-job-modes-contract.sh +++ b/tests/lint-job-modes-contract.sh @@ -131,12 +131,11 @@ grep -Fq 'default: auto' <<<"${mode_input}" || fail "lint-job-mode must default grep -Fq 'required: false' <<<"${mode_input}" || fail "lint-job-mode must stay optional" # Exactly one mode runs: per-linter jobs carry the parallel guard, the -# combined job its negation. The `lint-only` match in between is checked by -# tests/lint-only.py. +# combined job its negation. for job in "${linter_jobs[@]}"; do condition="$(job_if "${job}")" - [[ "${condition}" == "\${{ inputs.lint-${job} && "*" && ${parallel_guard} }}" ]] || - fail "job ${job} must use: if: \${{ inputs.lint-${job} && && ${parallel_guard} }} (found: ${condition})" + [ "${condition}" = "\${{ inputs.lint-${job} && ${parallel_guard} }}" ] || + fail "job ${job} must use: if: \${{ inputs.lint-${job} && ${parallel_guard} }} (found: ${condition})" done condition="$(job_if "${combined_job}")" [ "${condition}" = "\${{ !${parallel_guard} }}" ] || diff --git a/tests/lint-only.py b/tests/lint-only.py deleted file mode 100644 index 4d70ddf5..00000000 --- a/tests/lint-only.py +++ /dev/null @@ -1,278 +0,0 @@ -#!/usr/bin/env -S uv run --script -# /// script -# requires-python = ">=3.9" -# dependencies = ["pyyaml==6.0.3"] -# /// -"""Make every linter of lint.yml honour the `lint-only` input. - -`lint-only: gitleaks` runs gitleaks and skips every other linter, so -secret-scan callers keep no list of linters to turn off. A linter added to -lint.yml later must honour the list too, or it silently starts running in all -of them. Jobs and steps are read from lint.yml, so new ones are checked -without editing this test: - -- every linter job (all jobs except `all-linters` and the `lint-only` - validation job) needs a boolean `lint-` input, and its `if:` needs - `inputs.lint-` and the generated match for its own name (MATCH) as - top-level `&&` terms; -- in the single-job `all-linters`, every step with an `id:` or whose `if:` - reads a linter input needs both terms for one linter, or a top-level term - that is false whenever an allowed predecessor step was skipped - (`steps..outputs. == ''` or - `steps..outcome == 'success'`); SHARED_STEPS are exempt; -- the `lint-only` job runs whenever the input is set, can't be ignored by - `continue-on-error`, and its `known` names equal the linter jobs. - -The validation script is also run with bash against sample lists, and the -match expression is checked to agree with it. Broken copies of lint.yml are -checked too, to prove the test bites. -""" - -from __future__ import annotations - -import copy -import json -import os -import re -import shutil -import subprocess -import sys -from pathlib import Path - -import yaml - -ROOT = Path(__file__).resolve().parent.parent -LINT = ROOT / ".github" / "workflows" / "lint.yml" - -INPUT = "lint-only" -VALIDATOR = "lint-only" -NOT_LINTERS = {"all-linters", VALIDATOR} -# Steps every enabled linter needs. -SHARED_STEPS = {"Install mise"} -TOKEN = re.compile(r"'(?:[^']|'')*'|&&|\|\||[()]|[^'()&|]+|.") -# A whole `&&` term that is false whenever step was skipped. -SKIPS_WITH = re.compile( - r"^steps\.([A-Za-z_][\w-]*)\.(?:outputs\.[\w-]+=='(?:[^']|'')+'|(?:outcome|conclusion)=='success')$") -KNOWN = re.compile(r'^known="([^"]*)"$', re.M) -BORDERS = ((",", ","), (",", " "), (" ", ","), (" ", " ")) - - -def match(name: str) -> str: - """The condition that is true when `lint-only` is empty or lists `name`. - - Expressions have no split or trim, so the list is padded with commas and - the name matched with a comma or space on either side.""" - hay = "format(',{0},', inputs.lint-only)" - return ("(inputs.lint-only == '' || " - + " || ".join(f"contains({hay}, '{a}{name}{b}')" for a, b in BORDERS) + ")") - - -def match_value(name: str, value: str) -> bool: - """What match(name) evaluates to (contains() is case-insensitive).""" - hay = f",{value},".lower() - return value == "" or any(f"{a}{name}{b}" in hay for a, b in BORDERS) - - -def squash(text: str) -> str: - return re.sub(r"\s+", "", text) - - -def call_inputs(workflow: dict) -> dict: - # PyYAML (YAML 1.1) reads the `on` key as True. - triggers = workflow.get("on", workflow.get(True)) or {} - return (triggers.get("workflow_call") or {}).get("inputs") or {} - - -def terms(condition) -> list[str]: - """Top-level `&&` terms of an `if:`, whitespace removed; one term when `||` is top-level.""" - text = str(condition or "").strip() - if text.startswith("${{") and text.endswith("}}"): - text = text[3:-2] - parts, current, depth, has_or = [], "", 0, False - for token in TOKEN.findall(text): - if token == "(": - depth += 1 - elif token == ")": - depth -= 1 - if depth == 0 and token == "&&": - parts.append(current) - current = "" - continue - has_or = has_or or (depth == 0 and token == "||") - current += token - parts.append(current) - if has_or: - parts = ["&&".join(parts)] - return [squash(part) for part in parts] - - -def honours(step_terms: list[str], name: str) -> bool: - return f"inputs.lint-{name}" in step_terms and squash(match(name)) in step_terms - - -def check(lint: dict) -> list[str]: - problems: list[str] = [] - inputs = call_inputs(lint) - spec = inputs.get(INPUT) or {} - if spec.get("type") != "string" or spec.get("default") != "": - problems.append(f"lint.yml must declare a string {INPUT} input defaulting to ''") - - jobs = lint.get("jobs") or {} - for job_id in sorted(NOT_LINTERS - set(jobs)): - problems.append(f"lint.yml has no {job_id} job") - linters = sorted(set(jobs) - NOT_LINTERS) - for name in linters: - if (inputs.get(f"lint-{name}") or {}).get("type") != "boolean": - problems.append(f"jobs.{name} has no boolean lint-{name} input") - if not honours(terms((jobs[name] or {}).get("if")), name): - problems.append(f"jobs.{name}.if must include `inputs.lint-{name} && {match(name)}` at its top level") - - validator = jobs.get(VALIDATOR) or {} - if squash(str(validator.get("if"))) != squash("${{ inputs.lint-only != '' }}"): - problems.append(f"jobs.{VALIDATOR}.if must be ${{{{ inputs.lint-only != '' }}}}") - if "continue-on-error" in validator: - problems.append(f"jobs.{VALIDATOR} must not set continue-on-error") - known = KNOWN.search(validator_script(lint) or "") - if not known: - problems.append(f"jobs.{VALIDATOR} must define known=\"...\" in its script") - elif sorted(known.group(1).split()) != linters: - problems.append(f"jobs.{VALIDATOR} known names {sorted(known.group(1).split())} must equal the " - f"linter jobs {linters}") - - allowed: set[str] = set() - for step in (jobs.get("all-linters") or {}).get("steps") or []: - name, step_id = step.get("name"), step.get("id") - condition = str(step.get("if") or "") - reads_linter = any(re.search(rf"\binputs\.lint-{re.escape(n)}\b", condition) for n in linters) - if name in SHARED_STEPS or not (step_id or reads_linter): - continue - step_terms = terms(condition) - ok = (any(honours(step_terms, n) for n in linters) - or any((m := SKIPS_WITH.match(term)) and m.group(1) in allowed for term in step_terms)) - if ok: - allowed.add(step_id) - else: - problems.append(f"jobs.all-linters step {name!r} must include `inputs.lint- && " - f"` at the top level of its if:") - return problems - - -def validator_script(lint: dict) -> str | None: - steps = ((lint.get("jobs") or {}).get(VALIDATOR) or {}).get("steps") or [] - return next((s.get("run") for s in steps if s.get("run")), None) - - -# (lint-only value, input overrides, accepted) -VALIDATION_CASES = [ - ("gitleaks", {}, True), - (" gitleaks , trivy ", {}, True), - ("gitleaks,trivy,", {}, True), - ("gitleaks, zizmor", {}, True), - ("config-drift", {"lint-config-drift": True}, True), - ("gitleak", {}, False), - ("gitleaks trivy", {}, False), - ("GitLeaks", {}, False), - ("gitleaks\ntrivy", {}, False), - ("gitleaks;trivy", {}, False), - (",", {}, False), - (" ", {}, False), - ("config-drift", {}, False), - ("trivy", {"lint-trivy": False}, False), -] - - -def check_validator(lint: dict) -> list[str]: - bash = shutil.which("bash") - script = validator_script(lint) - if not script: - return [f"jobs.{VALIDATOR} has no run script"] - if not bash or not shutil.which("jq"): - return ["bash and jq are needed to run the validator"] if os.environ.get("CI") else [] - defaults = {name: spec.get("default") for name, spec in call_inputs(lint).items()} - linters = sorted(set(lint.get("jobs") or {}) - NOT_LINTERS) - problems = [] - for value, overrides, accepted in VALIDATION_CASES: - env = {**os.environ, "LINT_ONLY": value, "INPUTS": json.dumps({**defaults, INPUT: value, **overrides})} - result = subprocess.run([bash, "-c", script], env=env, capture_output=True, text=True) - if (result.returncode == 0) != accepted: - problems.append(f"validator {'rejects' if accepted else 'accepts'} lint-only {value!r}: " - f"{result.stdout.strip() or result.stderr.strip()}") - if accepted: - names = {part.strip() for part in value.split(",")} - {""} - for name in linters: - if match_value(name, value) != (name in names): - problems.append(f"the job condition for {name} disagrees with the validator on {value!r}") - return problems - - -def broken_copies(lint: dict): - """Yield (description, mutated lint.yml) pairs that check() must reject.""" - - def mutate(description, change): - broken = copy.deepcopy(lint) - change(broken["jobs"]) - return description, broken - - def step(jobs, step_id): - return next(s for s in jobs["all-linters"]["steps"] if s.get("id") == step_id) - - def set_known(jobs, names): - run = jobs[VALIDATOR]["steps"][0]["run"] - jobs[VALIDATOR]["steps"][0]["run"] = KNOWN.sub(f'known="{names}"', run, count=1) - - yield mutate("a job without the match", lambda j: j["dprint"].update({"if": "${{ inputs.lint-dprint }}"})) - yield mutate("a job matching another linter's name", - lambda j: j["dprint"].update({"if": f"${{{{ inputs.lint-dprint && {match('trivy')} }}}}"})) - yield mutate("a new job without the match", - lambda j: j.update({"newtool": {"if": "${{ inputs.lint-newtool }}", "runs-on": "ubuntu-24.04"}})) - yield mutate("a new job without any if", lambda j: j.update({"newtool": {"runs-on": "ubuntu-24.04"}})) - yield mutate("the match only inside an || term", - lambda j: j["trivy"].update({"if": f"${{{{ inputs.lint-trivy || {match('trivy')} }}}}"})) - yield mutate("a single-job step without the match", - lambda j: step(j, "zizmor").update({"if": "${{ inputs.lint-zizmor }}"})) - yield mutate("a SARIF step without the match", - lambda j: step(j, "trivy-sarif").update({"if": "${{ inputs.lint-trivy && inputs.upload-sarif }}"})) - yield mutate("a new single-job step without any if", - lambda j: j["all-linters"]["steps"].insert(-1, {"name": "Run newtool", "id": "newtool", "run": "x"})) - yield mutate("a validator that can be ignored", lambda j: j[VALIDATOR].update({"continue-on-error": True})) - yield mutate("a validator that doesn't always run", - lambda j: j[VALIDATOR].update({"if": "${{ inputs.lint-only != '' && inputs.lint-fail-on-error }}"})) - yield mutate("a known list missing a linter", lambda j: set_known(j, "gitleaks trivy")) - for description, condition in ( - ("a step running when its predecessor was skipped", "${{ steps.setup-go.outcome == 'skipped' }}"), - ("a step on a negative output comparison", "${{ steps.go-version-file.outputs.exists != 'false' }}"), - ("a step on an empty-output comparison", "${{ steps.go-version-file.outputs.exists == '' }}"), - ("a predecessor reference inside ||", "${{ steps.setup-go.outcome == 'success' || inputs.lint-go }}"), - ("a predecessor reference inside a parenthesised ||", - "${{ (steps.setup-go.outcome == 'success' || always()) && inputs.golangci-lint-version != '' }}"), - ): - yield mutate(description, lambda j, c=condition: step(j, "go").update({"if": c})) - - -def main() -> int: - lint = yaml.safe_load(LINT.read_text(encoding="utf-8")) - failures = check(lint) + check_validator(lint) - - no_input = copy.deepcopy(lint) - call_inputs(no_input).pop(INPUT, None) - if not any(f"declare a string {INPUT}" in problem for problem in check(no_input)): - failures.append(f"self-test: a missing {INPUT} input was not caught") - cases = list(broken_copies(lint)) - for description, broken in cases: - if not check(broken): - failures.append(f"self-test: {description} was not caught") - - if failures: - print(f"✖ {len(failures)} {INPUT} problem(s):", file=sys.stderr) - for failure in failures: - print(f" - {failure}", file=sys.stderr) - return 1 - ran = f"{len(VALIDATION_CASES)} lists validated" if shutil.which("bash") and shutil.which("jq") else \ - "validator not run (no bash/jq)" - print(f"✓ {INPUT}: every lint.yml linter job and single-job step honours the list; {ran}; " - f"{len(cases) + 1} broken variants are caught.") - return 0 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/tests/workflow-job-conditions.py b/tests/workflow-job-conditions.py index 64d22df4..360d46e1 100755 --- a/tests/workflow-job-conditions.py +++ b/tests/workflow-job-conditions.py @@ -266,11 +266,6 @@ def call(self, name, args): for index, arg in enumerate(args[1:]): result = result.replace("{" + str(index) + "}", "" if arg is None else str(arg)) return result - if name == "contains": - search, item = args - if isinstance(search, list): - return any(loose_equal(entry, item) for entry in search) - return str(item).lower() in ("" if search is None else str(search)).lower() raise ValueError(f"unsupported function {name}()") @@ -384,7 +379,6 @@ def lint_context(*, mode="auto", private=False, has_repository=True, event_name= inputs = {f"lint-{name}": True for name in ("dprint", "yamlfmt", "yamllint", "actionlint", "gitleaks", "go", "shellcheck", "shfmt", "checkov", "trivy", "zizmor")} inputs["lint-config-drift"] = False - inputs["lint-only"] = "" inputs["lint-job-mode"] = mode inputs.update({f"lint-{k.replace('_', '-')}": v for k, v in toggles.items()}) event = {"repository": {"private": private}} if has_repository else {"schedule": "0 0 * * 1"} @@ -406,15 +400,6 @@ def lint_context(*, mode="auto", private=False, has_repository=True, event_name= PER_LINTER - {"go", "trivy"}), ("public repo, config drift on", lint_context(config_drift=True), PER_LINTER | {"config-drift"}), ("invalid mode fails loudly in the single job", lint_context(mode="bogus"), SINGLE), - ("public repo, lint-only gitleaks", lint_context(only="gitleaks", config_drift=True), {"gitleaks", "lint-only"}), - ("public repo, lint-only with spaces", lint_context(only=" gitleaks , trivy"), {"gitleaks", "trivy", "lint-only"}), - ("public repo, lint-only lists a disabled linter", lint_context(only="gitleaks,go", go=False), - {"gitleaks", "lint-only"}), - ("public repo, lint-only typo runs only the validation", lint_context(only="gitleak"), {"lint-only"}), - ("private repo, parallel, lint-only gitleaks", lint_context(mode="parallel", private=True, only="gitleaks"), - {"gitleaks", "lint-only"}), - ("private repo, lint-only gitleaks (steps gated in the single job)", lint_context(private=True, only="gitleaks"), - SINGLE | {"lint-only"}), ] for name, context, expected in lint_scenarios: check("lint.yml", name, running_jobs(lint, context), expected)