Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

test(ci): tripwires pinning pull_request_target workflow hardening (#6604)

LearningCircuit12cd2b0a3c8a
diff --git a/tests/ci/test_pull_request_target_hardening.py b/tests/ci/test_pull_request_target_hardening.py
new file mode 100644
index 0000000000..e502e2ba1e
--- /dev/null
+++ b/tests/ci/test_pull_request_target_hardening.py
@@ -0,0 +1,329 @@
+"""Workflow-security tripwires for ``pull_request_target`` usage.
+
+Two workflows run under ``pull_request_target`` so they can hold the
+org's tokens on fork PRs (two others merely mention the trigger in
+comments explaining why they avoid it). That trigger executes workflow definitions
+from the **trusted base**, which is safe only while nothing from the
+PR head is ever checked out or executed: the pwn-request vector is a
+checkout step gaining ``ref: ${{ github.event.pull_request.head.sha }}``
+(a tempting "fix" when a diff looks stale), and the quieter one is a
+checkout that retains its credentials on disk for later untrusted
+steps. ``tests/ci/test_label_workflow_contracts.py``'s
+``test_pull_request_target_reviewer_keeps_the_trusted_checkout_invariant``
+already pins the ai-code-reviewer's own checkout: ``assert "ref" not
+in options`` for every ``actions/checkout@`` step (a stricter,
+ref-free bar than merely avoiding head refs), ``assert
+options.get("persist-credentials") is False``, and a ``run:``-step
+scan asserting ``not ("git checkout" in line and ("origin/pr-head" in
+line or "refs/pull/" in line))``. This module generalises that single
+workflow's checkout contract to every ``pull_request_target``
+workflow, trading the ref-free bar for an allowlist of trusted
+checkout refs and repositories.
+
+These contracts pin: every ``actions/checkout`` step in a
+``pull_request_target`` workflow avoids PR-head refs and disables
+credential persistence, and the *set* of such workflows stays exactly
+the audited set — a new ``pull_request_target`` workflow cannot
+appear silently. ``workflow_run`` workflows that consume artifacts
+from PR runs are outside this module's scope.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+import yaml
+
+WORKFLOWS_DIR = Path(__file__).resolve().parents[2] / ".github" / "workflows"
+
+#: The audited set. Adding a workflow here is a deliberate act: review
+#: it under the same rules before extending this frozenset.
+AUDITED_PR_TARGET_WORKFLOWS = frozenset(
+ {
+ "ai-code-reviewer.yml",
+ "welcome-first-time.yml",
+ }
+)
+
+# Only checkout forms whose trust follows directly from pull_request_target
+# are accepted. A denylist of head-ref spellings misses bracket expressions,
+# env/matrix indirection, and switching repository to the fork with no ref.
+TRUSTED_CHECKOUT_REFS = frozenset(
+ {
+ "",
+ "${{github.sha}}",
+ "${{github.ref}}",
+ "${{github.event.pull_request.base.sha}}",
+ "${{github.event.pull_request.base.ref}}",
+ }
+)
+TRUSTED_CHECKOUT_REPOSITORIES = frozenset({"", "${{github.repository}}"})
+
+#: Escape hatch for a reviewed reusable-workflow call or local composite
+#: action. Empty today. Adding an entry is a deliberate act, like
+#: extending AUDITED_PR_TARGET_WORKFLOWS: review the callee under the
+#: same no-head-checkout rules first — this module cannot see inside it.
+ALLOWED_DELEGATIONS: frozenset[str] = frozenset()
+
+
+def _checkout_expression(value) -> str:
+ """Ignore expression whitespace, never evaluate or follow indirection."""
+ return "".join(str(value).split())
+
+
+def _workflows_with_pr_target() -> dict[str, dict]:
+ found: dict[str, dict] = {}
+ for path in sorted(
+ p
+ for p in WORKFLOWS_DIR.iterdir()
+ if p.is_file() and p.suffix.lower() in {".yml", ".yaml"}
+ ):
+ try:
+ doc = yaml.safe_load(path.read_text(encoding="utf-8"))
+ except yaml.YAMLError:
+ # Malformed workflow: not this tripwire's problem (CI's own
+ # actionlint gates that); skip rather than false-positive.
+ continue
+ if not isinstance(doc, dict):
+ continue
+ triggers = doc.get(True, doc.get("on", {}))
+ if isinstance(triggers, str):
+ triggers = [triggers]
+ if (
+ isinstance(triggers, (dict, list))
+ and "pull_request_target" in triggers
+ ):
+ found[path.name] = doc
+ return found
+
+
+def _checkout_steps(doc: dict) -> list[tuple[str, dict]]:
+ steps: list[tuple[str, dict]] = []
+ for job in doc.get("jobs", {}).values():
+ if not isinstance(job, dict):
+ continue
+ for step in job.get("steps", []) or []:
+ if not isinstance(step, dict):
+ continue
+ uses = str(step.get("uses", ""))
+ if uses.strip().casefold().split("@", 1)[0] == "actions/checkout":
+ steps.append((uses, step))
+ return steps
+
+
+def _delegation_targets(doc: dict) -> list[str]:
+ """Reusable-workflow calls (``jobs.<id>.uses``) and local composite
+ actions (a step ``uses:`` starting with ``./`` that is not itself a
+ reusable-workflow file) — either could check out the PR head inside
+ a callee this module never inspects, letting the checkout tests
+ above pass vacuously on a caller with no checkout steps of its own.
+ """
+ targets: list[str] = []
+ for job in doc.get("jobs", {}).values():
+ if not isinstance(job, dict):
+ continue
+ job_uses = job.get("uses")
+ if isinstance(job_uses, str) and job_uses.strip():
+ targets.append(job_uses)
+ for step in job.get("steps", []) or []:
+ if not isinstance(step, dict):
+ continue
+ uses = str(step.get("uses", "")).strip()
+ if uses.startswith("./"):
+ targets.append(uses)
+ return targets
+
+
+class TestPullRequestTargetHardening:
+ def test_the_pr_target_set_is_exactly_the_audited_set(self):
+ found = set(_workflows_with_pr_target())
+ assert found == AUDITED_PR_TARGET_WORKFLOWS, (
+ f"pull_request_target set changed: added={sorted(found - AUDITED_PR_TARGET_WORKFLOWS)} "
+ f"removed={sorted(AUDITED_PR_TARGET_WORKFLOWS - found)} — "
+ "review any addition under the same no-head-checkout rules, "
+ "then extend AUDITED_PR_TARGET_WORKFLOWS deliberately"
+ )
+
+ def test_no_pr_target_workflow_checks_out_the_pr_head(self):
+ for name, doc in _workflows_with_pr_target().items():
+ for uses, step in _checkout_steps(doc):
+ with_ref = step.get("with", {}) or {}
+ ref = str(with_ref.get("ref", ""))
+ assert _checkout_expression(ref) in TRUSTED_CHECKOUT_REFS, (
+ f"{name}: checkout may use a PR-head ref ({ref!r}) — "
+ "use the default or an explicit trusted-base ref"
+ )
+ repository = with_ref.get("repository", "")
+ assert (
+ _checkout_expression(repository)
+ in TRUSTED_CHECKOUT_REPOSITORIES
+ ), (
+ f"{name}: checkout repository is not the trusted base "
+ f"({repository!r}) — omit it or use github.repository"
+ )
+
+ def test_pr_target_checkouts_do_not_persist_credentials(self):
+ for name, doc in _workflows_with_pr_target().items():
+ for _uses, step in _checkout_steps(doc):
+ with_opts = step.get("with", {}) or {}
+ assert with_opts.get("persist-credentials") is False, (
+ f"{name}: checkout retains git credentials for later "
+ "untrusted steps — set persist-credentials: false"
+ )
+
+ def test_checkout_free_workflows_stay_checkout_free(self):
+ """The label/comment-only workflow was checkout-free by design;
+ it must not grow an ``actions/checkout`` step."""
+ for name, doc in _workflows_with_pr_target().items():
+ if name == "ai-code-reviewer.yml":
+ continue
+ assert _checkout_steps(doc) == [], (
+ f"{name} was checkout-free by design; a checkout appeared"
+ )
+
+ def test_pr_target_workflows_do_not_delegate_to_unaudited_callees(self):
+ for name, doc in _workflows_with_pr_target().items():
+ for target in _delegation_targets(doc):
+ assert target in ALLOWED_DELEGATIONS, (
+ f"{name}: delegates to {target!r} (a reusable-workflow "
+ "call or a local composite action) — this module "
+ "cannot see inside the callee to confirm it never "
+ "checks out the PR head; review it under the same "
+ "rules, then add it to ALLOWED_DELEGATIONS deliberately"
+ )
+
+
[email protected]("suffix", [".yml", ".yaml", ".YML"])
+ "trigger",
+ [
+ "pull_request_target",
+ "[pull_request_target]",
+ "{pull_request_target: {}}",
+ ],
+)
+def test_unsafe_workflows_cannot_hide_from_discovery(
+ tmp_path, monkeypatch, suffix, trigger
+):
+ path = tmp_path / f"unsafe{suffix}"
+ doc = {
+ "jobs": {
+ "test": {
+ "steps": [
+ {
+ "uses": "actions/checkout@v7",
+ "with": {
+ "ref": "refs/pull/123/head",
+ "persist-credentials": True,
+ },
+ }
+ ]
+ }
+ },
+ }
+ path.write_text(f"on: {trigger}\n" + yaml.safe_dump(doc), encoding="utf-8")
+ monkeypatch.setitem(globals(), "WORKFLOWS_DIR", tmp_path)
+
+ assert set(_workflows_with_pr_target()) == {path.name}
+ guard = TestPullRequestTargetHardening()
+ with pytest.raises(AssertionError, match="set changed"):
+ guard.test_the_pr_target_set_is_exactly_the_audited_set()
+ with pytest.raises(AssertionError, match="PR-head ref"):
+ guard.test_no_pr_target_workflow_checks_out_the_pr_head()
+ with pytest.raises(AssertionError, match="retains git credentials"):
+ guard.test_pr_target_checkouts_do_not_persist_credentials()
+
+
+#: Sentinel for a grid row whose "with" option must be entirely absent
+#: (not merely falsy) — distinct from a row that never mentions the key
+#: because it defaults to False. Catches ``is False`` weakening to
+#: ``is not True`` (``None is not True`` passes; ``None is False`` fires).
+_OMIT = object()
+
+
+ "uses, options",
+ [
+ (
+ "actions/checkout@v7",
+ {"ref": "${{ github['event']['pull_request']['head']['sha'] }}"},
+ ),
+ ("actions/checkout@v7", {"ref": "${{ env.HEAD_SHA }}"}),
+ ("actions/checkout@v7", {"ref": "${{ matrix.ref }}"}),
+ (
+ "actions/checkout@v7",
+ {
+ "repository": "${{ github.event.pull_request.head.repo.full_name }}"
+ },
+ ),
+ ("actions/checkout@v7", {"repository": "untrusted-owner/fork"}),
+ (
+ "Actions/Checkout@v7",
+ {"ref": "${{ github.event.pull_request.head.sha }}"},
+ ),
+ ("Actions/Checkout@v7", {"persist-credentials": True}),
+ ("actions/checkout@v7", {"persist-credentials": _OMIT}),
+ ],
+)
+def test_untrusted_checkout_forms_cannot_bypass_guards(
+ tmp_path, monkeypatch, uses, options
+):
+ with_opts = {
+ k: v
+ for k, v in {"persist-credentials": False, **options}.items()
+ if v is not _OMIT
+ }
+ doc = {
+ "on": "pull_request_target",
+ "env": {"HEAD_SHA": "${{ github.event.pull_request.head.sha }}"},
+ "jobs": {
+ "test": {
+ "steps": [
+ {
+ "uses": uses,
+ "with": with_opts,
+ }
+ ]
+ }
+ },
+ }
+ (tmp_path / "ai-code-reviewer.yml").write_text(
+ yaml.safe_dump(doc), encoding="utf-8"
+ )
+ monkeypatch.setitem(globals(), "WORKFLOWS_DIR", tmp_path)
+ guard = TestPullRequestTargetHardening()
+ check = (
+ guard.test_pr_target_checkouts_do_not_persist_credentials
+ if "persist-credentials" in options
+ else guard.test_no_pr_target_workflow_checks_out_the_pr_head
+ )
+ with pytest.raises(AssertionError):
+ check()
+
+
[email protected]("ref", sorted(TRUSTED_CHECKOUT_REFS))
[email protected]("repository", [None, "${{ github.repository }}"])
+def test_trusted_base_checkouts_remain_allowed(
+ tmp_path, monkeypatch, ref, repository
+):
+ options = {"persist-credentials": False}
+ if ref:
+ options["ref"] = ref
+ if repository is not None:
+ options["repository"] = repository
+ doc = {
+ "on": {"pull_request_target": {}},
+ "jobs": {
+ "test": {
+ "steps": [{"uses": "actions/checkout@v7", "with": options}]
+ }
+ },
+ }
+ (tmp_path / "ai-code-reviewer.yml").write_text(
+ yaml.safe_dump(doc), encoding="utf-8"
+ )
+ monkeypatch.setitem(globals(), "WORKFLOWS_DIR", tmp_path)
+ guard = TestPullRequestTargetHardening()
+ guard.test_no_pr_target_workflow_checks_out_the_pr_head()
+ guard.test_pr_target_checkouts_do_not_persist_credentials()