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/secret-scan-caller.yml b/.github/workflows/secret-scan-caller.yml index 0a9dd08b..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,13 +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 - 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-gitleaks: true diff --git a/.mise.toml b/.mise.toml index 9bd7dcc7..00192f8b 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/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 97dbd4de..48ce7e3a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -114,9 +114,12 @@ 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. + scan from a second caller, after each merge, weekly and on dispatch (this + 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 @@ -132,7 +135,7 @@ permissions: jobs: gitleaks: - uses: DevSecNinja/.github/.github/workflows/lint.yml@ # v4.1.0 + uses: DevSecNinja/.github/.github/workflows/lint-include.yml@ # v4.4.0 permissions: contents: read security-events: write @@ -142,16 +145,7 @@ jobs: # 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 + lint-gitleaks: true ``` | Input | Description | @@ -209,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())