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.

12.7 KB
Raw Blame
"""Workflow-security tripwires for ``pull_request_target`` usage.

The audited workflows use ``pull_request_target`` for repository
metadata operations. 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",
        "dependency-pr-checks.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. 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(
    {"$/.github/actions/request-dependency-ci"}
)


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 ``./`` or ``$/`` 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 in {"ai-code-reviewer.yml", "dependency-pr-checks.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"
                )


@pytest.mark.parametrize("suffix", [".yml", ".yaml", ".YML"])
@pytest.mark.parametrize(
    "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()


@pytest.mark.parametrize(
    "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()


@pytest.mark.parametrize("ref", sorted(TRUSTED_CHECKOUT_REFS))
@pytest.mark.parametrize("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()