fix(workflows): harden pr-labels-ci.yml against fork-PR shell injection (#332)

[cmeans-claude-dev]

Closes #332.

Summary

.github/workflows/pr-labels-ci.yml on this repo was in the pre-cmeans/mcp-clipboard#88 state for the sibling cmeans/* cascade: contributor-controlled workflow_run fields (head_branch, id, repository) were inlined directly as ${{ ... }} expressions inside run: bodies. Git refnames allow shell metacharacters ($, backtick, ;, &, |, etc.), so a malicious fork-PR branch name would render as directly-executed shell once GHA substituted the expression at queue time.

This PR cascades the hardening from cmeans/mcp-clipboard:

1. Bump codecov/codecov-action from 5 to 6 #88 pattern — env routing. All contributor-controlled values now flow through step-level env: blocks and are referenced as shell variables ("$HEAD_BRANCH", "$REPO", "$RUN_ID"). Job-level if: conditionals continue to use ${{ ... }} (that expression context is safe — it's evaluated by GHA itself, not handed to a shell).
2. Make entries.updated nullable — NULL on insert, set only on update #92 pattern — comment escape. Comments inside run: blocks avoid any literal ${{ }} sequence. GHA's queue-time parser substitutes expressions even inside shell # comments and rejects empty expressions with An expression was expected on workflow_dispatch / fresh-repo registration. Without this, the Bump codecov/codecov-action from 5 to 6 #88 hardening would have landed a latent trap.

Cascaded verbatim from cmeans/mcp-clipboard's .github/workflows/pr-labels-ci.yml at the main HEAD after PR #92 merged (2026-04-20T20:26:12Z), preserving this repo's AGPL-3.0 header at lines 1–16. No functional behavior change — label transitions, PR lookup, force-push tolerance, and Dev Active skip logic are all byte-identical to before, just with shell values now arriving via environment instead of via text substitution.

Scope

• .github/workflows/pr-labels-ci.yml — hardened (22 lines changed)
• CHANGELOG.md — [Unreleased] → ### Security entry

No source, tests, migrations, or docs.

References

• Root diagnosis of the GHA parser quirk: cmeans/yt-dont-recommend#28
• Original security hardening (merged): cmeans/mcp-clipboard#88
• Comment-escape cascade source (merged): cmeans/mcp-clipboard#92
• Follow-up for symmetric pr-labels.yml hardening (non-blocking, P3): #334

QA

Prerequisites

Pure workflow-file change. No deploy, no env setup, no Python changes. All verification is static (yq/python -c, grep) plus an optional post-merge Actions UI smoke.

Automated checks

The CHANGELOG check, ruff, mypy, pytest, Codecov — none of these touch the workflow file. They should all pass unchanged against main. Confirm via the green CI checks on this PR before approving.

Manual tests

All local verification runs from the repo root on the PR branch (fix/pr-labels-ci-hardening-332).

1. • YAML parse is clean.

     python3 -c "import yaml; yaml.safe_load(open('.github/workflows/pr-labels-ci.yml')); print('OK')"
     

     Expected: prints OK, exit 0. Confirms no syntax regression.
2. • No literal empty ${{ }} anywhere in the file.

     grep -n '\${{ }}' .github/workflows/pr-labels-ci.yml || echo "(none — good)"
     

     Expected: prints (none — good). Guarantees the #92 parser trap can't surface on workflow_dispatch / fresh-repo registration.
3. • No contributor-controlled field appears inside a run: body as an expression.

     awk '/^        run: \|/,/^      - name:|^  [^ ]|^jobs:/' .github/workflows/pr-labels-ci.yml | grep -nE '\$\{\{ *github\.event\.workflow_run\.(head_branch|id) *\}\}' || echo "(none — good)"
     

     Expected: prints (none — good). The only remaining ${{ github.event.workflow_run.head_branch }} references are inside job-level if: conditionals (safe context, evaluated by GHA not a shell) and step-level env: assignments (safe by design — the whole point of the cascade).
4. • env: blocks route the three contributor-controlled fields.

     grep -nE '^[[:space:]]+(REPO|RUN_ID|HEAD_BRANCH):' .github/workflows/pr-labels-ci.yml
     

     Expected: six lines total (three per job), each assigning from the matching ${{ github.event.workflow_run.* }} / ${{ github.repository }} expression.
5. • workflows: [CI] still matches the CI workflow name in this repo.

     grep -A1 'workflows:' .github/workflows/pr-labels-ci.yml | head -3; grep '^name:' .github/workflows/ci.yml
     

     Expected: workflows: [CI] appears in this file AND name: CI appears in .github/workflows/ci.yml. Names match, so workflow_run will still fire on CI completion.
6. • AGPL header preserved.

     sed -n '1,16p' .github/workflows/pr-labels-ci.yml
     

     Expected: lines 1–16 are the existing mcp-awareness — ambient system awareness for AI agents / Copyright (C) 2026 Chris Means / AGPLv3 preamble. Unchanged from main.
7. • Diff against main is hardening-only (no behavior drift).

     git diff origin/main -- .github/workflows/pr-labels-ci.yml
     

     Expected: only adds REPO:, RUN_ID:, HEAD_BRANCH: to the two env: blocks, deletes the shell-level REPO=${{...}} / HEAD_BRANCH=${{...}} assignments, rewrites API_OUT=...${{ ... }}/pull_requests to .../$RUN_ID/pull_requests, and updates two comment blocks to avoid ${{ }} literals. No changes to if: conditionals, permissions, on:, job names, label manipulation logic, or exit 0 paths.
8. • (Post-merge) Smoke the label automation end-to-end. This workflow is workflow_run-triggered (no workflow_dispatch), so pre-merge dispatch isn't available. After merge, take any in-flight Awaiting CI PR and confirm the label transitions still happen on the next CI completion:
     • Watch .github/workflows/pr-labels-ci.yml runs at https://github.com/cmeans/mcp-awareness/actions/workflows/pr-labels-ci.yml
     • Expected on CI pass: on-ci-pass succeeds (~5 s), target PR moves Awaiting CI → Ready for QA.
     • Expected on CI fail: on-ci-fail succeeds, target PR gains CI Failed.

Out of scope (explicitly)

• pr-labels.yml (the on: pull_request: sibling) is not in this PR. Its current trigger makes secrets.GITHUB_TOKEN read-only for fork PRs and the values it does inline into run: blocks today are all safe types (numeric, repo name, hex SHA), so no injection vector exists at the current configuration. Symmetric env-routing as defense-in-depth tracked in #334 (P3, non-blocking).
• Adding workflow_dispatch to pr-labels-ci.yml for post-merge verifiability. Not cascaded because mcp-clipboard doesn't have it either. Track separately if desired.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

QA Active — starting review of the pr-labels-ci.yml hardening cascade.

[cmeans]

QA Review — Round 1

Verdict: QA Failed.

The functional cascade is correct: byte-identical to cmeans/mcp-clipboard/.github/workflows/pr-labels-ci.yml from line 17 onward (post-AGPL header), all 7 pre-merge QA steps pass, CI is fully green, no behavior drift in the diff. The blockers are in the PR body and CHANGELOG references — they point at mcp-clipboard PRs that don't reflect what actually merged, and they mischaracterize pr-labels.yml's trigger. A future maintainer chasing the cascade trail will hit dead ends.

Findings

1. Substantive — stale cmeans/mcp-clipboard PR references in PR body and CHANGELOG.

   • The PR body and CHANGELOG.md cite cmeans/mcp-clipboard#87 as the "original security hardening." PR #87 does not exist in that repo (gh pr view 87 --repo cmeans/mcp-clipboard returns Could not resolve to a PullRequest with the number of 87). The actually-merged hardening PR is #88 — fix(workflows): harden GitHub Actions context handling against script injection, merged 2026-04-20T01:31:47Z.
   • The PR body cites cmeans/mcp-clipboard#90 (open) as the comment-escape cascade source. PR #90 is CLOSED, not merged (fix(workflows): remove literal dollar-brace-brace from pr-labels-ci.yml comments). The actually-merged comment-escape PR is #92 — fix(workflows): remove literal empty GHA expression from pr-labels-ci.yml comments, merged 2026-04-20T20:26:12Z (about a minute after this PR was opened).
   • Fix: update the body's narrative paragraph (Cascaded verbatim from cmeans/mcp-clipboard's fix/pr-labels-ci-escape-comments branch (PR #90, CI green, awaiting QA)), the References section, and the ### Security CHANGELOG entry to point at #88 and #92.

2. Substantive — pr-labels.yml mischaracterized as pull_request_target in "Out of scope".
   The PR body says "pr-labels.yml (the pull_request_target sibling) is not in this PR." The file actually uses on: pull_request: (see .github/workflows/pr-labels.yml:22). That distinction is load-bearing: under pull_request from a fork, secrets.GITHUB_TOKEN is read-only and the gh pr edit --add-label calls would be rejected — so the shell-injection scenario this PR hardens against does not apply to that file at its current trigger configuration. Correct the description so future security audits don't start from a false premise.

3. Observation / suggested follow-up — pr-labels.yml symmetric hardening.
   pr-labels.yml does still inline contributor-touchable values directly into run: blocks (e.g., PR=${{ github.event.pull_request.number }}, REPO=${{ github.repository }}, HEAD_SHA=${{ github.event.pull_request.head.sha }}). All current values are safe types (numeric, repo name, hex SHA), and the pull_request trigger blocks fork-PR writes anyway, so there's no injection vector today. But a future trigger change to pull_request_target, or someone parameterizing the workflow with a contributor-controlled string field, would re-introduce the same class of bug. Defense-in-depth would benefit from cascading the env-routing pattern symmetrically. Please file a follow-up issue (nice-to-have, not blocking).

Steps verified (all pre-merge steps pass)

Step	Result
1. YAML parse clean	OK
2. No literal empty ${{ }}	(none — good)
3. No contributor-controlled fields in run: bodies	(none — good)
4. env: blocks route the three fields	6 lines (3 per job) ✓
5. workflows: [CI] matches name: CI in ci.yml	✓
6. AGPL header preserved (lines 1–16)	✓
7. Diff is hardening-only, no behavior drift	✓
8. Post-merge label-automation smoke	Deferred (workflow_run-only trigger)

Cascade cross-check

• diff <(sed -n '17,$p' .github/workflows/pr-labels-ci.yml) ../mcp-clipboard/.github/workflows/pr-labels-ci.yml → no differences. "Verbatim cascade" holds at the file-content level.
• git diff origin/main shows env-routing and comment-rewording only. No changes to if: conditionals, permissions, on:, job names, label manipulation logic, or exit 0 paths.
• All CI checks green: lint, typecheck, test (3.10/3.11/3.12), codecov/patch, license/cla.

Round 2

Fix findings 1 and 2 in this PR; file an issue for finding 3 (or fold it in if you prefer). I'll re-verify cascade equivalence and re-read the references on round 2.

[cmeans]

Audit: applying QA Failed. Cascade content is byte-identical to mcp-clipboard's pr-labels-ci.yml and all 7 pre-merge QA steps pass under SHA f09b5a8, but two substantive doc-drift findings (stale mcp-clipboard PR refs in body + CHANGELOG; pr-labels.yml mischaracterized as pull_request_target) need a fix before signoff. Details in the review above. Removing QA Active, applying QA Failed as the final act.

[cmeans-claude-dev]

Dev Response — Round 2

Thanks for the thorough review. Both substantive findings verified and addressed; filing the third as a follow-up.

Finding 1 — stale cmeans/mcp-clipboard PR references ✅ Fixed

Verified:

• gh pr view 87 --repo cmeans/mcp-clipboard → Could not resolve to a PullRequest with the number of 87
• gh pr view 88 --repo cmeans/mcp-clipboard → MERGED at 2026-04-20T01:31:47Z, title fix(workflows): harden GitHub Actions context handling against script injection — this is the actual env-routing hardening.
• gh pr view 90 --repo cmeans/mcp-clipboard → CLOSED, not merged.
• gh pr view 92 --repo cmeans/mcp-clipboard → MERGED at 2026-04-20T20:26:12Z, title fix(workflows): remove literal empty GHA expression from pr-labels-ci.yml comments — this is the actual comment-escape PR, merged about a minute after I opened this PR.

Fixed in commit 0e636a5 (CHANGELOG) and the PR body edit alongside:

• cmeans/mcp-clipboard#87 → #88 (both CHANGELOG and PR body References section)
• cmeans/mcp-clipboard#90 (open) → #92 (both CHANGELOG and PR body)
• "Cascaded verbatim from cmeans/mcp-clipboard's fix/pr-labels-ci-escape-comments branch (PR Thread owner_id through Store, Server, Tools, Collator #90, CI green, awaiting QA)" → rewritten to point at mcp-clipboard's main HEAD after Make entries.updated nullable — NULL on insert, set only on update #92 merged.

Finding 2 — pr-labels.yml mischaracterized as pull_request_target ✅ Fixed

Verified: .github/workflows/pr-labels.yml:21-24 is:

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, labeled, unlabeled]

Fixed in the PR-body "Out of scope" block — reworded to identify the actual trigger (on: pull_request:), note why the injection scenario this PR hardens against does not apply under that trigger today (fork PRs get a read-only GITHUB_TOKEN, so the gh pr edit label-write calls would be rejected regardless of branch-name content), and link to the new follow-up issue.

Finding 3 — symmetric env-routing for pr-labels.yml ✅ Filed as #334

Labeled enhancement, P3: low. Issue explains:

• Why it is not a latent security bug at the current pull_request trigger (read-only token on fork PRs + all currently-inlined values are safe types: numeric / repo name / hex SHA).
• Why to cascade the pattern anyway: trigger-drift risk, parameterization-drift risk, cascade-consistency across cmeans/* repos.
• Concrete scope and acceptance checks.

Kept out of this PR to preserve the one-concern-per-PR discipline and the "cascade verbatim, no drift" property of the file-content cascade.

Head SHA for re-verification

0e636a5 on fix/pr-labels-ci-hardening-332. The .github/workflows/pr-labels-ci.yml content is unchanged from round 1 (f09b5a8) — all round-2 changes are doc-only (CHANGELOG + PR body). Transitioning back to Ready for QA after CI goes green.

[cmeans]

QA Active — round 2, verifying the doc fixes on 0e636a5 and the #334 follow-up.

[cmeans]

QA Review — Round 2

Verdict: Ready for QA Signoff.

All round-1 findings closed. The workflow file is byte-identical to round 1 (only CHANGELOG.md was touched in 0e636a5, and the PR body was edited in parallel). All 7 pre-merge QA steps re-run against 0e636a5 pass. CI fully green. Cascade still byte-identical to cmeans/mcp-clipboard/.github/workflows/pr-labels-ci.yml.

Round-1 finding closure

#	Finding	Round-1	Round-2
1	PR body + CHANGELOG cite mcp-clipboard#87 (404) and #90 (closed)	broken refs	now reference #88 (merged hardening) and #92 (merged comment escape) — verified via grep for #87/#90 returns no hits in PR body or CHANGELOG.md
2	PR body's "Out of scope" mischaracterizes pr-labels.yml as pull_request_target	wrong premise	now reads "(the on: pull_request: sibling)" with accurate read-only-token rationale
3	Symmetric env-routing for pr-labels.yml (defense-in-depth)	suggested follow-up	filed as #334 (P3, enhancement) — well-scoped, accurate trigger analysis, defense-in-depth + drift-risk rationale, mechanical acceptance criteria

Re-verification (0e636a5)

Step	Result
1. YAML parse	OK
2. No literal empty ${{ }}	(none — good)
3. No contributor fields in run: bodies	(none — good)
4. env: blocks route the three fields	6 lines (3/job) ✓
5. workflows: [CI] matches name: CI in ci.yml	✓
6. AGPL header preserved	✓
7. git diff origin/main	hardening-only, 22 lines (13/9) ✓
8. Post-merge label-automation smoke	Deferred (workflow_run-only trigger)

CI rollup on 0e636a5: lint, typecheck, test (3.10/3.11/3.12), codecov/patch, license/cla — all SUCCESS.

Follow-ups outstanding (non-blocking)

• #334 — symmetric env-routing for pr-labels.yml (P3, defense-in-depth). Not exploitable today (pull_request trigger ⇒ read-only fork token; inlined values are all safe types), so this is genuinely nice-to-have, not gating.

Maintainer to apply QA Approved when ready.

[cmeans]

Audit: applying Ready for QA Signoff as the final act. Round-2 verified on 0e636a5: all 7 pre-merge QA steps re-pass, cascade still byte-identical to mcp-clipboard, all CI checks green, all 3 round-1 findings closed (CHANGELOG + PR body refs corrected to #88/#92, pr-labels.yml trigger correctly described as on: pull_request:, follow-up #334 filed). Removing QA Active, applying Ready for QA Signoff. Maintainer to apply QA Approved.

[cmeans]

LGTM