Harden Jenkins Actions policy guard

Author: nate

.github/CI_POLICY.md

@@ -8,7 +8,12 @@ or `workflow_call` (reusable by a manually dispatched workflow) as events.
 No `push`, `pull_request`, `pull_request_target`, `schedule`, `issues`,
 `workflow_run`, or other automatic Actions events are allowed.
 
-* Jenkins' `Jenkinsfile` runs `scripts/ci/check-github-actions-policy.py`.
+* Jenkins installs the pinned CI Python tools, then runs
+  `scripts/ci/check-github-actions-policy.py` and its focused self-tests.
+  The guard parses YAML and rejects duplicate top-level `on` or trigger keys,
+  anchors, aliases, merge keys, explicit document markers/directives and tags. It
+  accepts block or flow mappings but permits only `workflow_dispatch` and
+  `workflow_call` under the workflow's top-level `on` key.
 * The GitHub release/promotion workflows are retained as **manual-only**
   fallback/publishing operations. They can consume Actions minutes when started.
 * CodeQL, GitHub Pages, smoke/soak and repro workflows remain manual-only;

Jenkinsfile

@@ -17,12 +17,19 @@ arena hash_table dyn_array str_intern log str_util index_policy workspace platfo
     }
 
     stages {
+        stage('Install Python CI tools') {
+            steps {
+                sh 'CBM_CI_VENV="$WORKSPACE/.ci-venv" scripts/ci/install-python-tools.sh'
+            }
+        }
         stage('Lint') {
             steps {
                 sh '''
                     set -eu
                     rm -f .jenkins-installed-cli
-                    python3 scripts/ci/check-github-actions-policy.py
+                    "$WORKSPACE/.ci-venv/bin/python" scripts/ci/check-github-actions-policy.py
+                    "$WORKSPACE/.ci-venv/bin/python" scripts/ci/test_github_actions_policy.py
+                    python3 scripts/ci/test_sync_ancestry.py
                     python3 tests/test_jenkins_daemon_recovery.py
                     scripts/lint.sh --ci CLANG_FORMAT=clang-format-20
                 '''
@@ -43,11 +50,6 @@ arena hash_table dyn_array str_intern log str_util index_policy workspace platfo
                 '''
             }
         }
-        stage('Install Python CI tools') {
-            steps {
-                sh 'CBM_CI_VENV="$WORKSPACE/.ci-venv" scripts/ci/install-python-tools.sh'
-            }
-        }
         stage('License gate') {
             steps {
                 withCredentials([usernamePassword(credentialsId: 'github-https-token',

docs/upstream-sync/ci-policy.md

@@ -0,0 +1,74 @@
+# CI policy and ancestry guard receipt
+
+## Workflow policy
+
+`scripts/ci/check-github-actions-policy.py` parses every top-level
+`.github/workflows/*.yml` and `*.yaml` file with pinned PyYAML 6.0.3. PyYAML is
+installed from `requirements-ci.txt` before Jenkins lint runs.
+
+Supported workflow syntax is YAML block and flow mappings. The document must
+contain exactly one implicit YAML document whose root is a mapping and whose
+top-level `on` value is a nonempty mapping. Quoted keys and event names are
+handled as YAML strings; ordinary and alternative indentation and flow event
+mappings receive the same checks. Only these event keys pass:
+
+* `workflow_dispatch`
+* `workflow_call`
+
+Aliases, anchors, merge keys, duplicate top-level `on` keys, duplicate event
+keys within `on`, explicit document starts/ends, YAML directives, explicit
+tags, invalid YAML, non-mapping `on` values, and unsupported trigger names
+fail closed.
+Scalar `on` values such as `on: push` and block scalars fail because `on` must
+be a mapping. Duplicate keys outside the trigger declaration are outside this
+guard's scope.
+
+Run locally:
+
+```sh
+scripts/ci/install-python-tools.sh
+.ci-venv/bin/python scripts/ci/check-github-actions-policy.py
+.ci-venv/bin/python scripts/ci/test_github_actions_policy.py
+python3 scripts/ci/test_sync_ancestry.py
+```
+
+The policy self-test exercises real repository workflows and malicious and
+positive fixtures for indentation, quoted keys, flow syntax, aliases/anchors,
+merge keys, duplicate trigger keys, scalar forms, directives, explicit
+documents, and tags.
+
+## Upstream ancestry helper
+
+`scripts/ci/check-sync-ancestry.py --checkpoint SHA --target SHA --merge SHA`
+requires full commit IDs, resolves each exact object, proves checkpoint is an
+ancestor of the pinned upstream target, and proves target is in a non-first
+parent's history for the integration merge. Git replacement refs are disabled
+for these graph checks, so a synthetic replacement cannot manufacture the
+ancestry claim. The helper is local/manual and does not run hosted Actions.
+Jenkins runs its self-test, which constructs true and replacement-ref-faked
+histories.
+
+## Validation record
+
+Passed locally on 2026-11-01:
+
+```text
+python3 scripts/ci/check-github-actions-policy.py
+  GitHub Actions policy: manual/reusable only; Jenkins owns automatic CI
+python3 scripts/ci/test_github_actions_policy.py
+  Ran 4 tests; OK (real workflows plus positive/negative fixtures)
+python3 scripts/ci/test_sync_ancestry.py
+  Ran 3 tests; OK (true ancestry, replacement-ref spoof, invalid inputs)
+git diff --check
+  passed
+```
+
+The exact-worktree Codebase Memory CLI discovery attempt (`cbm projects
+--json`; `cbm status --json`) failed with `codebase-memory-cli: secure CLI
+coordination could not be created (cache-resolve)`. Git porcelain was empty
+before and after this probe; source discovery continued with `rg` and direct
+reads. Graph evidence is unavailable for this run. Parent should record the CLI
+failure in its canonical backlog.
+
+Jenkins remains the full integration gate and was not run locally. No hosted
+Actions workflow was run.

requirements-ci.txt

@@ -1,6 +1,7 @@
 # Python tooling required by repository CI gates.
 # Keep this separate from pkg/pypi/requirements-publish.txt: these packages are
 # CI analyzers, not runtime or registry-publishing dependencies.
+PyYAML==6.0.3
 scancode-toolkit==32.5.0
 # pluggy 1.7.0 rejects plugincode 32.0.0's pre_scan hookspec module ("did not
 # find any 'pre_scan' hooks"), which breaks `scancode` at import. Keep the

scripts/ci/check-github-actions-policy.py

@@ -1,39 +1,68 @@
 #!/usr/bin/env python3
-"""Jenkins guard: forbid billable, automatically triggered GitHub Actions.
-
-Only manually dispatched or reusable workflows are permitted in this fork.
-When importing upstream changes, keep this policy even if upstream adds CI.
-"""
+"""Jenkins guard: allow only manual or reusable GitHub Actions workflows."""
 from pathlib import Path
-import re
 import sys
 
+import yaml
+from yaml.events import AliasEvent, DocumentEndEvent, DocumentStartEvent, NodeEvent
+from yaml.nodes import MappingNode, ScalarNode
+
 ROOT = Path(__file__).resolve().parents[2]
 WORKFLOWS = ROOT / ".github" / "workflows"
 ALLOWED = {"workflow_dispatch", "workflow_call"}
-ON = re.compile(r"""^(?:on|"on"|'on'):\s*(?:#.*)?$""")
-EVENT = re.compile(r"^  ([A-Za-z_][A-Za-z0-9_-]*):")
+
+
+class PolicyLoader(yaml.SafeLoader):
+    # GitHub Actions uses YAML 1.2, where the unquoted key `on` is a string.
+    yaml_implicit_resolvers = {
+        key: [(tag, regexp) for tag, regexp in resolvers
+              if tag != "tag:yaml.org,2002:bool"]
+        for key, resolvers in yaml.SafeLoader.yaml_implicit_resolvers.items()
+    }
 
 def inspect(path: Path) -> list[str]:
-    lines = path.read_text(encoding="utf-8").splitlines()
-    triggers = []
-    found = False
-    for idx, line in enumerate(lines):
-        if not ON.fullmatch(line):
-            continue
-        if found:
-            return [f"{path.name}: multiple on sections"]
-        found = True
-        for sub in lines[idx + 1:]:
-            if sub and not sub.startswith((" ", "#")):
-                break
-            match = EVENT.match(sub)
-            if match:
-                triggers.append(match.group(1))
-    if not found or not triggers:
-        return [f"{path.name}: missing or non-block YAML on declaration"]
+    text = path.read_text(encoding="utf-8")
+    try:
+        for event in yaml.parse(text, Loader=PolicyLoader):
+            if isinstance(event, AliasEvent) or (isinstance(event, NodeEvent) and event.anchor):
+                raise ValueError("anchors and aliases are unsupported")
+            if isinstance(event, DocumentStartEvent) and (event.explicit or event.version or event.tags):
+                raise ValueError("explicit YAML documents and directives are unsupported")
+            if isinstance(event, DocumentEndEvent) and event.explicit:
+                raise ValueError("explicit YAML document endings are unsupported")
+            if isinstance(event, NodeEvent) and event.tag:
+                raise ValueError("explicit YAML tags are unsupported")
+        root = yaml.compose(text, Loader=PolicyLoader)
+        if not isinstance(root, MappingNode):
+            raise ValueError("workflow document root must be a mapping")
+        on_nodes = [value for key, value in root.value
+                    if isinstance(key, ScalarNode) and key.value == "on"]
+        if len(on_nodes) != 1:
+            return [f"{path.name}: expected exactly one top-level 'on' key"]
+        if not isinstance(on_nodes[0], MappingNode):
+            return [f"{path.name}: top-level 'on' value must be a mapping"]
+        trigger_keys = []
+        for key, _ in on_nodes[0].value:
+            if not isinstance(key, ScalarNode):
+                raise ValueError("trigger event names must be scalar strings")
+            if key.value in trigger_keys:
+                return [f"{path.name}: duplicate trigger event {key.value!r}"]
+            trigger_keys.append(key.value)
+        docs = list(yaml.load_all(text, Loader=PolicyLoader))
+    except (yaml.YAMLError, ValueError) as exc:
+        return [f"{path.name}: unsupported or invalid YAML: {exc}"]
+
+    if len(docs) != 1 or not isinstance(docs[0], dict):
+        return [f"{path.name}: expected one YAML document with a workflow mapping"]
+    workflow = docs[0]
+    if "on" not in workflow or not isinstance(workflow["on"], dict) or not workflow["on"]:
+        return [f"{path.name}: missing or non-mapping 'on' trigger declaration"]
+    events = workflow["on"]
+    if any(not isinstance(event, str) for event in events):
+        return [f"{path.name}: trigger event names must be strings"]
     return [f"{path.name}: forbidden GitHub Actions trigger {event!r}"
-            for event in triggers if event not in ALLOWED]
+            for event in events if event not in ALLOWED]
+
 
 def main() -> int:
     errors = []
@@ -49,5 +78,6 @@ def main() -> int:
     print("GitHub Actions policy: manual/reusable only; Jenkins owns automatic CI")
     return 0
 
+
 if __name__ == "__main__":
     sys.exit(main())

scripts/ci/check-sync-ancestry.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Verify a real upstream checkpoint and merge-parent ancestry using Git."""
+import argparse
+import os
+import re
+import subprocess
+import sys
+
+
+def git(*args: str) -> str:
+    env = os.environ | {"GIT_NO_REPLACE_OBJECTS": "1"}
+    return subprocess.check_output(["git", *args], text=True, stderr=subprocess.PIPE, env=env).strip()
+
+
+def exact_commit(value: str) -> str:
+    if not re.fullmatch(r"(?:[0-9a-f]{40}|[0-9a-f]{64})", value):
+        raise ValueError(f"expected a full commit SHA, got {value!r}")
+    resolved = git("rev-parse", "--verify", f"{value}^{{commit}}")
+    if resolved != value:
+        raise ValueError(f"commit did not resolve to the exact supplied SHA: {value}")
+    return resolved
+
+
+def verify(checkpoint: str, target: str, merge: str) -> None:
+    checkpoint = exact_commit(checkpoint)
+    target = exact_commit(target)
+    merge = exact_commit(merge)
+    if subprocess.run(["git", "merge-base", "--is-ancestor", checkpoint, target],
+                      env=os.environ | {"GIT_NO_REPLACE_OBJECTS": "1"}, check=False).returncode:
+        raise ValueError("checkpoint is not an ancestor of pinned target")
+    parents = git("rev-list", "--parents", "-n", "1", merge).split()[1:]
+    if len(parents) < 2:
+        raise ValueError("result is not a merge commit")
+    if not any(subprocess.run(["git", "merge-base", "--is-ancestor", target, parent],
+                              env=os.environ | {"GIT_NO_REPLACE_OBJECTS": "1"},
+                              check=False).returncode == 0 for parent in parents[1:]):
+        raise ValueError("pinned target is not in a non-first merge-parent history")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--checkpoint", required=True, help="full upstream checkpoint commit SHA")
+    parser.add_argument("--target", required=True, help="full pinned upstream target commit SHA")
+    parser.add_argument("--merge", required=True, help="full integration merge commit SHA")
+    args = parser.parse_args()
+    try:
+        verify(args.checkpoint, args.target, args.merge)
+    except (ValueError, subprocess.CalledProcessError) as exc:
+        print(f"sync ancestry check failed: {exc}", file=sys.stderr)
+        return 1
+    print("sync ancestry: exact checkpoint, pinned target, and merge parent verified")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/ci/test_github_actions_policy.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Focused policy-guard tests; also validates every workflow in this checkout."""
+import importlib.util
+from pathlib import Path
+import tempfile
+import unittest
+
+SCRIPT = Path(__file__).with_name("check-github-actions-policy.py")
+SPEC = importlib.util.spec_from_file_location("github_actions_policy", SCRIPT)
+policy = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(policy)
+
+
+class PolicyTests(unittest.TestCase):
+    def rejects(self, text):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "fixture.yml"
+            path.write_text(text, encoding="utf-8")
+            self.assertTrue(policy.inspect(path), text)
+
+    def accepts(self, text):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "fixture.yml"
+            path.write_text(text, encoding="utf-8")
+            self.assertEqual([], policy.inspect(path), text)
+
+    def test_manual_and_reusable_block_and_flow_forms(self):
+        self.accepts("name: valid\non:\n  workflow_dispatch:\n    inputs: {}\n")
+        self.accepts("'on': {workflow_call: {}}\n")
+        self.accepts('"on": {"workflow_dispatch": null}\n')
+
+    def test_rejects_automatic_events_across_yaml_forms(self):
+        for document in (
+            "on:\n    push:\n",
+            "'on':\n  'pull_request': {}\n",
+            'on: {"schedule": [{cron: "* * * * *"}]}\n',
+            "on: push\n",
+            "on: |\n  workflow_dispatch\n",
+        ):
+            with self.subTest(document=document):
+                self.rejects(document)
+
+    def test_rejects_duplicate_alias_merge_document_directive_and_tag(self):
+        for document in (
+            "on: {workflow_dispatch: null}\non: {push: null}\n",
+            "on: {workflow_dispatch: null, workflow_dispatch: null}\n",
+            "on: &events {workflow_dispatch: null}\n",
+            "on: *events\n",
+            "on: {<<: {workflow_dispatch: null}, push: null}\n",
+            "---\non: {workflow_dispatch: null}\n",
+            "on: {workflow_dispatch: null}\n...\n",
+            "%YAML 1.2\non: {workflow_dispatch: null}\n",
+            "on: !!map {workflow_dispatch: null}\n",
+        ):
+            with self.subTest(document=document):
+                self.rejects(document)
+
+    def test_real_workflows(self):
+        paths = sorted((*policy.WORKFLOWS.glob("*.yml"), *policy.WORKFLOWS.glob("*.yaml")))
+        self.assertTrue(paths)
+        errors = [error for path in paths for error in policy.inspect(path)]
+        self.assertEqual([], errors)
+
+
+if __name__ == "__main__":
+    unittest.main()