Workflow hardening: no pull-request job reads a secret or holds a new write scope - #682

Scope

• What this PR changes, in one or two sentences: adds PullRequestReachableJobsTests to tests/test_workflow_hardening.py. It is a regression tripwire: no job a pull request can start may reference a repository secret, pass secrets:, declare environment:, call a remote reusable workflow, fall back to the repository-default token, or hold a write scope beyond the two SARIF upload jobs in security-scan.yml (security-events: write). Every workflow must also stay in the plain block YAML subset that these text checks read in full. The PR appends a dated note to the GitHub automation decision record.
• Base commit: 3bdacabd5b7bbc1b8c39f4e5fa3c694951a85751, with origin/main at ba0e8c48f (Harden the three-group OSV policy and SARIF upload paths (port #555) #673) merged in during the review round.
• Lane: lane:foundation
• Owned paths touched: tests/test_workflow_hardening.py; docs/decisions/2026-09-22-github-automation-closure.md (append-only section at the end; main's file is an unchanged prefix); manifests/evidence.json (my two entries re-registered with host_receipts.register_file, in the branch's last commit per docs/lanes.md).

Why: the OpenHands resolver (#489) will push agent-written commits to same-repository branches, and #489's pre-push gate keeps the agent out of .github/**. An ordinary pull_request run from a same-repository branch receives the repository's secrets and the job's token scopes as written. By default GitHub withholds secrets from a fork's pull request and turns its write scopes to read; only a private repository can choose to send them. A Dependabot-triggered run gets a read-only token and only Dependabot secrets. The remaining condition is that pull-request workflows hold no secrets and no write scopes. That holds at 3bdacab, but nothing in the tree pinned it.

What the class checks (tests/test_workflow_hardening.py:2434). The constants are PULL_REQUEST_EVENTS at :2245, PULL_REQUEST_WRITE_ALLOWLIST at :2249, PULL_REQUEST_SECRET_SOURCE_ALLOWLIST at :2262 (empty) and YAML_SUBSET_LINE at :2288.

• Reachability. A workflow is reachable when its on: names pull_request, pull_request_target, pull_request_review, pull_request_review_comment, issue_comment or workflow_run. Any local reusable workflow (uses: ./.github/workflows/<file>) called by a reachable job is followed transitively; no in-repo workflow calls one today. Every job of a reachable workflow counts, whatever its if: says. At 3bdacab that is 24 jobs in 11 workflows, which matches the coordinator's audit.

• test_every_workflow_is_written_in_the_form_the_checks_read (:2452). This applies to every workflow file, because an unread on: could hide reachability. Every YAML-significant line (that is, outside |/> block-scalar content) must match YAML_SUBSET_LINE: a plain key, or a sequence entry, whose value is a plain scalar, a single-quoted scalar, a double-quoted scalar with no backslash, a one-line flow sequence of those, or a block-scalar indicator. The test refuses:

  • non-empty flow mappings, such as a job or permissions: written as {...} (an empty {} or [] holds no key and is accepted: permissions: {}, GitHub's form that disables every scope, reads as an explicit grant of no scope, never as the repository default);
  • anchors, aliases, tags and merge keys;
  • quoted keys and multi-line scalars;
  • any backslash in a double-quoted scalar.

  Every on: must yield events. Each reachable workflow must keep the job layout jobs() reads: block headers at two spaces, keys at four, and a header count equal to what jobs() read. The tree used none of the refused forms (0 of 1,907 YAML-significant lines).

• test_no_reachable_job_reads_a_secret (:2488). Every ${{ }} expression naming the secrets context (secrets.X, secrets['X'], toJSON(secrets)) fails, including in comment lines, because a # line inside run: | is script text. So does every secrets: key, including secrets: inherit. Workflow-level env: and called workflows are covered.

• test_no_reachable_job_declares_an_environment_or_calls_a_remote_workflow (:2499). Either one brings secrets the caller never passes, and a remote workflow is not read here. The test fails unless PULL_REQUEST_SECRET_SOURCE_ALLOWLIST lists the declaring line; that allowlist is empty, and no current job needs either.

• test_only_the_sarif_upload_jobs_hold_a_write_scope (:2525). The set of (workflow, job) pairs whose effective permissions hold a write scope must equal PULL_REQUEST_WRITE_ALLOWLIST in both directions, so a stale entry also fails. A job's own block replaces the workflow's. A job with neither fails as "repository default". write-all fails, and so does any workflow-level write.

• test_event_reader_misses_no_event_yaml_reads_when_available (:2477). This is a PyYAML cross-check that may skip, as the module's existing job-parser cross-check does. CI installs no PyYAML.

Each failure names workflow and line, then ends with:
Why: an ordinary pull_request run from a same-repository branch, where the OpenHands resolver (#489) pushes agent-written commits, receives the repository's secrets and its job's token scopes as written; GitHub withholds them by default from a fork's pull request (a private repository can choose to send them), and a Dependabot-triggered run gets a read-only token and only Dependabot secrets.
A Fix: line follows. Changing either allowlist means editing a commented constant and the decision record.

SOTA sources

All sources were read on 2026-10-04. GitHub Docs were fetched at 05:16:08Z, with the reuse, Dependabot and repository-settings pages at 05:58:01Z. Scorecard and zizmor were fetched at 05:17:07Z and byte-verified at the pins below. The YAML spec was fetched at 06:07:09Z.

• GitHub Docs, Events that trigger workflows, pull_request > "Workflows in forked repositories": "With the exception of GITHUB_TOKEN, secrets are not passed to the runner when a workflow is triggered from a forked repository. The GITHUB_TOKEN has read-only permissions in pull requests from forked repositories." On the same page, a workflow_run workflow "is able to access secrets and write tokens, even if the previous workflow was not".
• GitHub Docs, Workflow syntax, permissions:
  • "How permissions are calculated for a workflow job": first the repository default, then the workflow level, then the job level. Fork pull requests get write changed to read unless "Send write tokens to workflows from pull requests" is selected.
  • "all of those that are not specified are set to none".
  • The read-all, write-all and {} forms and jobs.<job_id>.secrets.inherit.
• GitHub Docs, Managing GitHub Actions settings for a repository, "Enabling workflows for forks of private repositories": "Available to private repositories only"; "Send write tokens to workflows from pull requests"; "Send secrets to workflows from pull requests".
• GitHub Docs, Troubleshooting Dependabot on GitHub Actions: Dependabot runs "receive a read-only GITHUB_TOKEN and do not have access to any secrets that are normally available"; "the only secrets available to the workflow are Dependabot secrets".
• GitHub Docs, Reuse workflows, "Using inputs and secrets in a reusable workflow": "If you include environment in the reusable workflow at the job level, the environment secret will be used, and not the secret passed from the caller workflow."
• GitHub Docs, Reusing workflow configurations: "YAML anchors and aliases", including whole-job reuse; a called workflow's token "can be only downgraded (not elevated)".
• GitHub Docs, Contexts reference, context availability and Using secrets: where the secrets context can be used ("Secrets cannot be directly referenced in if: conditionals").
• YAML 1.2.2:
  • 5.7 Escaped Characters: 20 escapes including \x, \u and \U; "Each escape sequence must be parsed into the appropriate Unicode character".
  • 7.3.1: double-quoted is "the only style capable of expressing arbitrary strings".
  • 7.3.2: a repeated ' "is the only form of escaping performed in single-quoted scalars".
  • 7.3.3: plain style "provides no form of escaping".
• OpenSSF Scorecard docs/checks.md at f1ebd76756593c0454d782b4ba36ebc33ad131b6: Token-Permissions and Dangerous-Workflow.
• zizmor docs/audits.md at v1.30.1 (99a054ed9283c90abdd2d5b9fb5101d27dde9783), the version .github/requirements-ci.txt pins: excessive-permissions, secrets-inherit, secrets-outside-env, dangerous-triggers.
• Implementation reference: this module's own text helpers (jobs, permission_blocks, scopes, uncommented) and the cross-workflow pattern of NoWorkflowApprovesPullRequestsTests. The cross-check used PyYAML 6.0.3 from PyPI in a throwaway venv.

Evidence-class table

Local commands run

All runs used a scratch TMPDIR outside the checkout and nice -n 19, on head 6e166809.

$ python3 -m unittest tests.test_workflow_hardening
Ran 114 tests                           # exit 0; OK (skipped=3): empty HASH_FROZEN and the two PyYAML cross-checks
$ python3 scripts/validate.py
{"components": 69, "hashed_files": 9808, "profiles": 4, "receipts": 194, "status": "passed"}   # exit 0
$ python3 scripts/evidence_manifest.py --check
{"files": 9808, "status": "passed"}     # exit 0
$ git diff --check origin/main...HEAD   # exit 0
$ python3 scripts/component_matrix.py --check; python3 scripts/new_host_grand_list.py --check
# exit 0; exit 0, so the hot-file protocol's --write steps were no-ops
$ python3 harness.py <worktree> 5e2f85e5=FGH 846cb03e=AMX   # mutation harness, kept outside the repository
expected-pass cases: 6; expected-fail cases: 34
HARNESS RESULT: PASS (every expected-pass case green; every mutant red with its expected, line-numbered message)   # exit 0
$ bash full-module.sh <worktree>        # R1 / R3 against all 114 tests in a clone of the branch
R1 EXIT=1 (1 failure, new class) / R3 EXIT=1 (1 failure, new class) / control EXIT=0

The harness builds each case in a fresh root holding real copies of tests/ and .github/ plus read-only symlinks for the rest of the tree. It mutates the copy and runs the class. The first-round cases each still fail with these messages (E5 and E8 are reworded):

• R1 ${{ secrets.X }} in a step: validate.yml:57 (job validate; on: pull_request) reads the secrets context: ${{ secrets.PLANTED_TOKEN }}
• R2 secrets: inherit: validate.yml:597 (job planted-call; on: pull_request) reads the secrets context: secrets: inherit
• R3 contents: write on a PR job: validate.yml:570 (job sota-sources; on: pull_request) holds contents: write, which PULL_REQUEST_WRITE_ALLOWLIST does not grant it
• R4 a third security-events: write: security-scan.yml:38 (job osv-scanner; on: pull_request) holds security-events: write, ...
• R5 no permissions anywhere: dependency-review.yml:20 (job dependency-review; on: pull_request) sets no permissions and neither does its workflow, so its token gets the repository default
• E1–E9: pull_request_target flow form, issue_comment with write-all, workflow_run with a workflow-level env secret, a secret in a called workflow, a whole-job anchor and alias, a quoted 'write', a write after a blank line in a block, a stale allowlist entry (now security-scan.yml:162 (job osv-sarif-upload) holds no write scope a pull request can reach, but PULL_REQUEST_WRITE_ALLOWLIST grants it ...), and a comment on the permissions: line.
• F1–F2, G1–G11, H1–H3: the repair-round cases are listed with their messages in the review-round comment on this PR. Each passed the class at 5e2f85e5 and fails it now.

Decision record

docs/decisions/2026-09-22-github-automation-closure.md, section "Pull-request secrets and write-scope tripwire (2026-10-04)". It is appended after the existing sections, including those main changed in #673. It records what is pinned, the evidence class, the cross-family review round, the alternatives (zizmor's general audits and Scorecard's checks) and the overturn conditions.

Host evidence

Not applicable: no file under evidence/hosts/ changes.

Checklist

• New/changed GitHub Actions are pinned to a full commit SHA with a
  version comment (no floating tags). This PR changes no workflow or action; the merge brings in only main's own security-scan.yml change from Harden the three-group OSV policy and SARIF upload paths (port #555) #673.
• New/changed workflows declare top-level permissions: contents: read
  (or a narrower, explicitly justified addition). The new test pins this for every workflow a pull request can start.
• No secrets are printed, logged or committed; no new required secret was
  added without a documented owner.
• No new paid hosting, subscription or billing surface was introduced.
• Peer-owned untracked files and worktrees were preserved (not deleted,
  moved or overwritten).

Open points

• The trigger set is a superset of the brief: pull_request_review and pull_request_review_comment are included, since both are pull_request* events.
• if: conditions are deliberately not credited. Both SARIF uploads skip pull_request by if:, and they are allowlisted explicitly instead.
• secrets.GITHUB_TOKEN is forbidden as well. The failure's Fix: line points to github.token, which the write-scope check bounds.
• A reachable job may not declare environment: or call a remote reusable workflow unless PULL_REQUEST_SECRET_SOURCE_ALLOWLIST (empty) lists it. A remote workflow is not read, and an environment brings secrets the caller never passes.
• The YAML subset applies to every workflow file, not only reachable ones, because an unread on: could hide reachability. Future workflows must therefore use plain block YAML; any other form fails with a line-numbered message naming the form. A maintained YAML parser in CI would let this give way to checks on parsed YAML.
• push is outside the event set. All 9 push triggers are filtered to main or v* tags today (measured), but nothing pins that filter. This is a follow-up candidate.
• The zizmor comparison ran offline. CI runs zizmor online, which adds only pin and ref audits.
• OpenHands resolver: host driver, one owner issue to one draft PR (stages 1-2, offline-tested) #489 adds no workflow file (it is a host driver), so this tripwire does not conflict with it. main moved to ba0e8c48 (Harden the three-group OSV policy and SARIF upload paths (port #555) #673) during the review round and was merged in per docs/lanes.md. The class passes against Harden the three-group OSV policy and SARIF upload paths (port #555) #673's security-scan.yml change, which adds two if: ${{ !cancelled() }} upload guards and no permission.
• CI least privilege: permissions {} by default, cache-mode none on pull requests, workflow policy tripwire #681 (CI least privilege, de0b0043) moves every workflow to permissions: {}. The class passes on its 21 workflows: 11 reachable workflows, 24 jobs. A trial merge of both branches auto-merges tests/test_workflow_hardening.py; only the manifests/evidence.json hot file conflicts, and both PRs' workflow test modules pass together. CI least privilege: permissions {} by default, cache-mode none on pull requests, workflow policy tripwire #681's tests/test_workflow_policy.py already enforces most of this class's rules; it does not cover environment: or remote reusable calls in pull-request jobs, secrets in issue_comment or pull_request_review* workflows, or secrets.GITHUB_TOKEN. The compatibility comment on this PR has the probe results.

🤖 Generated with Claude Code