Enforce workflow data trust boundaries

Contract-Neutral: Moves workflow expressions into environment data flow without changing deployment interfaces or behavior.

scripts/check_workflow_trust.py

@@ -14,6 +14,14 @@ ACTION_SHA_RE = re.compile(r"^[0-9a-f]{40}$")
 CONTAINER_DIGEST_RE = re.compile(r"^docker://.+@sha256:[0-9a-f]{64}$")
 HOSTED_LATEST_RE = re.compile(r"\b(?:ubuntu|windows|macos)-latest\b")
 USES_RE = re.compile(r"^\s*(?:-\s*)?uses:\s*([^\s#]+)")
+RUN_RE = re.compile(r"^(\s*)(?:-\s*)?run:\s*(.*)$")
+EXPRESSION_RE = re.compile(r"\$\{\{(.*?)\}\}")
+# Workflow-call and dispatch inputs are data, not shell source. Secrets include
+# github.token because Actions makes that credential available independently of
+# an explicit secrets.GITHUB_TOKEN reference.
+SHELL_DATA_CONTEXT_RE = re.compile(
+    r"(?<![\w.])(?:inputs|secrets)\.|(?<![\w.])github\.token\b"
+)
 CHECKOUT_PREFIX = "actions/checkout@"
 WRITE_CREDENTIAL_RATIONALE = "# required: authenticated git writes"
 
@@ -48,10 +56,54 @@ def _checkout_block(lines: list[str], uses_index: int) -> list[tuple[int, str]]:
     return block
 
 
+def _run_script_lines(lines: list[str], run_index: int) -> list[tuple[int, str]]:
+    """Return the source lines GitHub will materialize as a run script."""
+    match = RUN_RE.match(lines[run_index])
+    if not match:
+        return []
+    run_indent = len(match.group(1))
+    value = match.group(2).strip()
+    if value not in {"|", "|-", "|+", ">", ">-", ">+"}:
+        return [(run_index, match.group(2))]
+
+    script: list[tuple[int, str]] = []
+    for index in range(run_index + 1, len(lines)):
+        line = lines[index]
+        if line.strip() and _indent(line) <= run_indent:
+            break
+        script.append((index, line))
+    return script
+
+
 def audit_workflow(path: Path) -> list[Finding]:
     lines = path.read_text(encoding="utf-8").splitlines()
     findings: list[Finding] = []
 
+    permission_declarations = [
+        index
+        for index, line in enumerate(lines)
+        if re.match(r"^permissions\s*:", line)
+    ]
+    if len(permission_declarations) != 1:
+        findings.append(
+            Finding(
+                path,
+                1,
+                "workflow must declare top-level permissions explicitly exactly once",
+            )
+        )
+    elif lines[permission_declarations[0]].split("#", 1)[0].strip() not in {
+        "permissions:",
+        "permissions: {}",
+    }:
+        findings.append(
+            Finding(
+                path,
+                permission_declarations[0] + 1,
+                "workflow permissions must use a scope mapping or explicit empty mapping",
+            )
+        )
+
     for index, line in enumerate(lines):
         line_number = index + 1
         code = line.split("#", 1)[0]
@@ -64,6 +116,18 @@ def audit_workflow(path: Path) -> list[Finding]:
                 )
             )
 
+        if RUN_RE.match(code):
+            for script_index, script_line in _run_script_lines(lines, index):
+                for expression in EXPRESSION_RE.findall(script_line):
+                    if SHELL_DATA_CONTEXT_RE.search(expression):
+                        findings.append(
+                            Finding(
+                                path,
+                                script_index + 1,
+                                "workflow inputs and secrets must enter run scripts through env",
+                            )
+                        )
+
         match = USES_RE.search(code)
         if not match:
             continue

scripts/release_control/release_promotion_policy_test.py

@@ -1721,8 +1721,10 @@ class ReleasePromotionPolicyTest(unittest.TestCase):
         self.assertIn("name: Backfill Release Assets", backfill_workflow)
         self.assertIn("workflow_dispatch:", backfill_workflow)
         self.assertIn('SYFT_VERSION="1.42.4"', backfill_workflow)
-        self.assertIn('./scripts/backfill-release-assets.sh --tag "${{ inputs.tag }}" --repo "${{ github.repository }}"', backfill_workflow)
-        self.assertIn('./scripts/validate-published-release.sh "${{ inputs.tag }}" "${{ github.repository }}"', backfill_workflow)
+        self.assertIn("TAG: ${{ inputs.tag }}", backfill_workflow)
+        self.assertIn("REPOSITORY: ${{ github.repository }}", backfill_workflow)
+        self.assertIn('./scripts/backfill-release-assets.sh --tag "${TAG}" --repo "${REPOSITORY}"', backfill_workflow)
+        self.assertIn('./scripts/validate-published-release.sh "${TAG}" "${REPOSITORY}"', backfill_workflow)
         self.assertIn("PULSE_UPDATE_SIGNING_PUBLIC_KEY: ${{ vars.PULSE_UPDATE_SIGNING_PUBLIC_KEY }}", backfill_workflow)
         self.assertIn("./scripts/prepare-release-container-context.sh", candidate_workflow)
         self.assertIn('test "${actual_server}" = "${expected_server}"', docker_build)

scripts/tests/test_workflow_trust.py

@@ -31,7 +31,9 @@ class WorkflowTrustTest(unittest.TestCase):
 
     def test_accepts_immutable_dependencies_and_explicit_checkout_credentials(self) -> None:
         findings = self.audit(
-            f"""jobs:
+            f"""permissions:
+  contents: read
+jobs:
   test:
     runs-on: ubuntu-24.04
     steps:
@@ -47,7 +49,9 @@ class WorkflowTrustTest(unittest.TestCase):
 
     def test_rejects_mutable_action_runner_and_container_references(self) -> None:
         findings = self.audit(
-            """jobs:
+            """permissions:
+  contents: read
+jobs:
   test:
     runs-on: ubuntu-latest
     steps:
@@ -61,14 +65,16 @@ class WorkflowTrustTest(unittest.TestCase):
 
     def test_rejects_implicit_or_unjustified_checkout_credentials(self) -> None:
         omitted = self.audit(
-            f"""steps:
+            f"""permissions: {{}}
+steps:
   - uses: actions/checkout@{PIN}
 """
         )
         self.assertTrue(any("must set persist-credentials" in finding for finding in omitted))
 
         unjustified = self.audit(
-            f"""steps:
+            f"""permissions: {{}}
+steps:
   - uses: actions/checkout@{PIN}
     with:
       persist-credentials: true
@@ -77,7 +83,8 @@ class WorkflowTrustTest(unittest.TestCase):
         self.assertTrue(any("require # required" in finding for finding in unjustified))
 
         mixed_case = self.audit(
-            f"""steps:
+            f"""permissions: {{}}
+steps:
   - uses: Actions/Checkout@{PIN}
 """
         )
@@ -87,7 +94,8 @@ class WorkflowTrustTest(unittest.TestCase):
 
     def test_accepts_documented_authenticated_git_write(self) -> None:
         findings = self.audit(
-            f"""steps:
+            f"""permissions: {{}}
+steps:
   - uses: actions/checkout@{PIN}
     with:
       persist-credentials: true  # required: authenticated git writes
@@ -95,6 +103,38 @@ class WorkflowTrustTest(unittest.TestCase):
         )
         self.assertEqual(findings, [])
 
+    def test_requires_explicit_least_privilege_permissions(self) -> None:
+        missing = self.audit("jobs: {}\n")
+        self.assertTrue(any("top-level permissions" in finding for finding in missing))
+
+        broad = self.audit("permissions: write-all\njobs: {}\n")
+        self.assertTrue(any("scope mapping" in finding for finding in broad))
+
+        dynamic = self.audit("permissions: ${{ inputs.permissions }}\njobs: {}\n")
+        self.assertTrue(any("scope mapping" in finding for finding in dynamic))
+
+    def test_rejects_shell_template_data_but_accepts_env_data(self) -> None:
+        findings = self.audit(
+            """permissions: {}
+jobs:
+  unsafe:
+    runs-on: ubuntu-24.04
+    steps:
+      - run: echo "${{ inputs.name }}"
+      - run: |
+          echo "${{ secrets.ACCESS_TOKEN }}"
+          echo "${{ github.token }}"
+      - env:
+          NAME: ${{ inputs.name }}
+          TOKEN: ${{ github.token }}
+        run: printf '%s\\n' "$NAME" >/dev/null
+"""
+        )
+        self.assertEqual(
+            sum("must enter run scripts through env" in finding for finding in findings),
+            3,
+        )
+
     def test_repository_workflows_satisfy_contract(self) -> None:
         findings = workflow_trust.audit_directory(REPO_ROOT / ".github" / "workflows")
         self.assertEqual([finding.render() for finding in findings], [])