~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""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()