feat(security): enforce GitHub-hosted Ubuntu runner policy in CI (microsoft#2700)

# Pull Request

## Description

Adds CI enforcement for the GitHub Actions `runs-on` runner policy,
which was previously documented as a MUST rule in
`workflows.instructions.md` but had no validator checking it.

**This PR takes a different approach than the one proposed in the linked
issue.** The issue was filed based on a PR review comment that flagged
`ubuntu-slim` as a non-compliant runner label. During investigation, we
confirmed `ubuntu-slim` is actually a GA (Jan 2026), GitHub-hosted,
lightweight Ubuntu runner — it is compliant with the intended policy,
not a violation. The real violation in that PR was `windows-latest`,
which is genuinely disallowed. Rather than build a validator around the
`ubuntu-slim` premise, this PR:

* Clarifies `workflows.instructions.md` § Runners with an explicit
**allow-list** (`ubuntu-latest`, dated `ubuntu-24.04`/`ubuntu-22.04`
labels and their `-arm` variants, `ubuntu-slim`) and **disallow-list**
(`windows-*`, `macos-*`, `self-hosted`, custom labels), so the rule is
unambiguous about what is and isn't compliant.
* Adds `scripts/security/Test-WorkflowRunner.ps1`, mirroring the
existing `Test-WorkflowPermissions.ps1` validator pattern, to enforce
that allow-list in CI against every job's `runs-on` value (including
list-form and matrix-expression values, which are conservatively treated
as violations since they can't be statically resolved).
* Adds 28 Pester unit/integration tests for the new script.
* Adds a reusable `workflow-runner-scan.yml` (mirroring
`workflow-permissions-scan.yml`) and wires a `workflow-runner-check` job
into `pr-validation.yml`'s required `pr-validation-success` gate.
* Adds `npm run lint:workflow-runner` to `package.json` and the
`validate:local` aggregate.

This closes the broader gap the issue was really pointing at (an
unenforced MUST rule) while fixing the underlying documentation
ambiguity rather than special-casing `ubuntu-slim`.

## Related Issue(s)

Closes microsoft#2696

## Type of Change

**Code & Documentation:**

* [x] Documentation update

**Infrastructure & Configuration:**

* [x] GitHub Actions workflow
* [x] Security configuration

**AI Artifacts:**

* [x] Reviewed contribution with `hve-builder` and addressed all
actionable findings
* [x] Copilot instructions (`.github/instructions/*.instructions.md`)

**Other:**

* [x] Script/automation (`.ps1`, `.sh`, `.py`)

## Sample Prompts (for AI Artifact Contributions)

**User Request:**
"Add a new job to this workflow with `runs-on: windows-latest`."

**Execution Flow:**
A Copilot session authoring/editing any `.github/workflows/*.yml` file
has `workflows.instructions.md` in context (via its `applyTo` glob). It
reads the clarified Runners allow/disallow list, flags `windows-latest`
as non-compliant, and proposes an allow-listed replacement (e.g.,
`ubuntu-latest`). If asked what would catch this in CI, it cites
`scripts/security/Test-WorkflowRunner.ps1`.

**Output Artifacts:**
No files are generated by the instructions themselves; they shape any
workflow YAML a contributor authors. The `Test-WorkflowRunner.ps1`
script produces JSON/SARIF/console reports, e.g.:

```json
{
  "violations": [
    {
      "file": ".github/workflows/example.yml",
      "job": "package-installer",
      "type": "NonUbuntuRunner",
      "value": "windows-latest"
    }
  ]
}
```

**Success Indicators:**
`npm run lint:workflow-runner` exits 0 with no violations; the
`workflow-runner-check` job in `pr-validation.yml` passes and is
included in the required `pr-validation-success` gate.

## Testing

* `npm run test:ps -- -TestPath
"scripts/tests/security/Test-WorkflowRunner.Tests.ps1"` — 28/28 passed.
* Full `scripts/tests/security/` Pester suite — 643/643 passed.
* Full repo Pester suite (`npm run test:ps`) — 4242 passed, 1
pre-existing/unrelated failure (environment-specific
devcontainer-detection test on `main`, reproduced via `git stash`), 7
skipped.
* `npm run lint:workflow-runner` against the real repo — 147/147 jobs
pass.
* `npm run lint:permissions`, `lint:dangerous-workflow`, `lint:pr-gate`,
`lint:yaml`, `lint:json`, `lint:md`, `lint:frontmatter` — all pass.
* Reviewed `.github/instructions/workflows.instructions.md` with
`hve-builder` (review mode): static review found and fixed one High
finding (Enforcement Statement was missing the new script); behavior
gate executed via `hve-builder-tester` (simulation, Medium profile) —
Pass, confirming a Copilot session correctly accepts `ubuntu-slim`,
rejects/corrects `windows-latest`, and cites the enforcement script.

## Checklist

### Required Checks

* [x] Documentation is updated (if applicable)
* [x] Files follow existing naming conventions
* [x] Changes are backwards compatible (if applicable)
* [x] Tests added for new functionality (if applicable)

### AI Artifact Contributions

* [x] Used `hve-builder` review mode to review contribution
* [x] Addressed all actionable findings from the `hve-builder` review
* [x] Verified contribution follows common standards and type-specific
requirements

### Required Local Checks

* [x] Local validation aggregate: `npm run validate:local`
* [ ] Documentation validation (if docs changed): `npm run
validate:docs`
* [x] Spell checking: `npm run spell-check`
* [x] Link validation: `npm run lint:md-links`

## Security Considerations

* [x] This PR does not contain any sensitive or NDA information
* [x] Any new dependencies have been reviewed for security issues
* [x] Security-related scripts follow the principle of least privilege

## Additional Notes

The issue as filed suggested the problem was `ubuntu-slim` being
non-compliant. That premise is incorrect — `ubuntu-slim` is a valid
GitHub-hosted Ubuntu runner. The actual gap (no CI enforcement of the
runner policy at all) is real and is what this PR fixes, alongside
clarifying the docs so this kind of misattribution doesn't recur.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Bill Berry <wberry@microsoft.com>

Author: 3 people

.github/instructions/workflows.instructions.md

@@ -98,7 +98,15 @@ Workflows MUST NOT persist GitHub credentials by default. Credential persistence
 
 ## Runners
 
-Workflows MUST run on GitHub-hosted Ubuntu runners. Other runner types are not supported in hve-core.
+Workflows MUST run on GitHub-hosted Ubuntu runners. Windows, macOS, self-hosted, and other non-Ubuntu runner types are not supported in hve-core.
+
+**Allowed `runs-on` labels** (GitHub-hosted Ubuntu images only):
+
+* `ubuntu-latest`
+* `ubuntu-24.04`, `ubuntu-22.04` (and other GitHub-hosted Ubuntu version labels as they become available, including ARM variants such as `ubuntu-24.04-arm`)
+* `ubuntu-slim` (lightweight 1 vCPU GitHub-hosted runner; still Ubuntu, still GitHub-hosted)
+
+**Disallowed `runs-on` values:** `windows-*`, `macos-*`, `self-hosted`, and any custom or third-party runner label.
 
 **Required pattern:**
 
@@ -268,6 +276,12 @@ All workflows MUST pass the following validation checks:
 * **What it enforces:** Every workflow declares a top-level `permissions:` block, and every job declares its own block unless the workflow-level block is empty
 * **CI blocking:** Failures block CI when configured to enforce compliance
 
+### Runner Policy Validation
+
+* **Script:** `scripts/security/Test-WorkflowRunner.ps1`
+* **What it enforces:** Every job's `runs-on` value is a GitHub-hosted Ubuntu label (see § Runners for the allow list)
+* **CI blocking:** Failures block CI when configured to enforce compliance
+
 ## Security Requirements
 
 * Never expose secrets in logs or outputs
@@ -336,6 +350,7 @@ The following scripts enforce compliance:
 * `scripts/security/Test-DependencyPinning.ps1` - Validates dependency pinning
 * `scripts/security/Test-SHAStaleness.ps1` - Checks for stale dependencies
 * `scripts/security/Test-WorkflowPermissions.ps1` - Validates workflow permissions declarations
+* `scripts/security/Test-WorkflowRunner.ps1` - Validates `runs-on` values against the GitHub-hosted Ubuntu allow-list
 * `scripts/linting/Invoke-YamlLint.ps1` - Runs actionlint validation
 * `scripts/security/Test-PrValidationGate.ps1` - Validates the PR validation gate `needs:` completeness
 

.github/workflows/pr-validation.yml

@@ -420,6 +420,17 @@ jobs:
       upload-sarif: true
       upload-artifact: false
 
+  workflow-runner-check:
+    name: Workflow Runner Check
+    uses: ./.github/workflows/workflow-runner-scan.yml
+    permissions:
+      contents: read
+      security-events: write # Required for SARIF upload to Security tab
+    with:
+      soft-fail: false
+      upload-sarif: true
+      upload-artifact: false
+
   dangerous-workflow-check:
     name: Dangerous Workflow Check
     uses: ./.github/workflows/dangerous-workflow-scan.yml
@@ -686,6 +697,7 @@ jobs:
       - dependency-pinning-check
       - devcontainer-lockfile-check
       - workflow-permissions-check
+      - workflow-runner-check
       - dangerous-workflow-check
       - action-version-consistency-scan
       - gitleaks-scan

.github/workflows/workflow-runner-scan.yml

@@ -0,0 +1,108 @@
+# Copyright (c) 2026 Microsoft Corporation. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+name: Workflow Runner Scan
+on:
+  workflow_call:
+    inputs:
+      soft-fail:
+        description: 'Continue on violations instead of failing'
+        required: false
+        type: boolean
+        default: false
+      upload-sarif:
+        description: 'Upload SARIF results to GitHub Security tab'
+        required: false
+        type: boolean
+        default: true
+      upload-artifact:
+        description: 'Upload results as workflow artifact'
+        required: false
+        type: boolean
+        default: true
+    outputs:
+      compliance-score:
+        description: 'Compliance score percentage'
+        value: ${{ jobs.runner-check.outputs.compliance-score }}
+      violation-count:
+        description: 'Number of jobs not running on a GitHub-hosted Ubuntu runner'
+        value: ${{ jobs.runner-check.outputs.violation-count }}
+      is-compliant:
+        description: 'Whether all jobs run on a GitHub-hosted Ubuntu runner'
+        value: ${{ jobs.runner-check.outputs.is-compliant }}
+
+permissions:
+  contents: read
+
+jobs:
+  runner-check:
+    name: Workflow Runner Check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write  # Required for SARIF upload to Security tab
+    outputs:
+      compliance-score: ${{ steps.runner.outputs.compliance-score }}
+      violation-count: ${{ steps.runner.outputs.violation-count }}
+      is-compliant: ${{ steps.runner.outputs.is-compliant }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup PowerShell modules
+        uses: ./.github/actions/setup-ps-modules
+
+      - name: Run Workflow Runner Validation
+        id: runner
+        shell: pwsh
+        run: |
+          New-Item -ItemType Directory -Force -Path logs | Out-Null
+          $params = @{
+            Path            = '.github/workflows'
+            Format          = 'sarif'
+            OutputPath      = 'logs/workflow-runner-results.sarif'
+          }
+          if ('${{ inputs.soft-fail }}' -ne 'true') {
+            $params['FailOnViolation'] = $true
+          }
+          ./scripts/security/Test-WorkflowRunner.ps1 @params
+
+          # Write outputs for downstream consumers
+          if (Test-Path 'logs/workflow-runner-results.sarif') {
+            $sarif = Get-Content 'logs/workflow-runner-results.sarif' | ConvertFrom-Json
+            $violationCount = @($sarif.runs[0].results).Count
+            $isCompliant = $violationCount -eq 0
+
+            # Re-run with json format to extract compliance score
+            $jsonParams = @{
+              Path            = '.github/workflows'
+              Format          = 'json'
+              OutputPath      = 'logs/workflow-runner-results.json'
+            }
+            ./scripts/security/Test-WorkflowRunner.ps1 @jsonParams
+            $report = Get-Content 'logs/workflow-runner-results.json' | ConvertFrom-Json
+            $complianceScore = $report.ComplianceScore
+
+            "compliance-score=$complianceScore" >> $env:GITHUB_OUTPUT
+            "violation-count=$violationCount" >> $env:GITHUB_OUTPUT
+            "is-compliant=$($isCompliant.ToString().ToLower())" >> $env:GITHUB_OUTPUT
+          }
+
+      - name: Upload SARIF results
+        if: always() && inputs.upload-sarif
+        uses: github/codeql-action/upload-sarif@ce729e4d353d580e6cacd6a8cf2921b72e5e310a # v3.27.0
+        with:
+          sarif_file: logs/workflow-runner-results.sarif
+          category: workflow-runner
+        continue-on-error: true
+
+      - name: Upload results artifact
+        if: always() && inputs.upload-artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: workflow-runner-results
+          path: logs/workflow-runner-results.*
+          retention-days: 90
+        continue-on-error: true

package.json

@@ -25,6 +25,7 @@
     "design-intent:schema:sync": "pwsh -NoProfile -File scripts/linting/Sync-DesignIntentSchema.ps1",
     "lint:version-consistency": "pwsh -NoProfile -File ./scripts/security/Test-ActionVersionConsistency.ps1 -FailOnMismatch -Format Json -OutputPath logs/action-version-consistency-results.json",
     "lint:permissions": "pwsh -NoProfile -File ./scripts/security/Test-WorkflowPermissions.ps1 -FailOnViolation",
+    "lint:workflow-runner": "pwsh -NoProfile -File ./scripts/security/Test-WorkflowRunner.ps1 -FailOnViolation",
     "lint:extension-artifact-naming": "pwsh -NoProfile -File scripts/linting/Test-ExtensionArtifactNaming.ps1",
     "lint:dangerous-workflow": "pwsh -NoProfile -File ./scripts/security/Test-DangerousWorkflow.ps1 -FailOnViolation",
     "lint:dependency-pinning": "pwsh -NoProfile -File ./scripts/security/Test-DependencyPinning.ps1 -FailOnUnpinned",
@@ -42,7 +43,7 @@
     "lint:asset-docs": "pwsh -NoProfile -File scripts/linting/Validate-AssetDocs.ps1 -FailOnMissing -CheckSync",
     "lint:models": "pwsh -NoProfile -File scripts/linting/Test-ModelReferences.ps1 -OutputPath logs/model-validation-results.json",
     "lint:models:refresh": "pwsh -NoProfile -File scripts/linting/Update-ModelCatalog.ps1",
-    "validate:local": "npm run lint:plugin-manifest && npm run lint:tables && npm run lint:md && npm run lint:ps && npm run lint:yaml && npm run lint:json && npm run lint:links && npm run lint:md-links && npm run lint:frontmatter && npm run lint:adr-consistency && npm run lint:hooks && npm run lint:design-intent && npm run lint:version-consistency && npm run lint:permissions && npm run lint:dangerous-workflow && npm run lint:dependency-pinning && npm run lint:public-dependency-feeds && npm run lint:pr-gate && npm run lint:ps-module-pins && npm run lint:extension-artifact-naming && npm run lint:py && npm run validate:skills && npm run lint:ai-artifacts && npm run lint:asset-docs && npm run lint:models && npm run validate:devcontainer-lockfile",
+    "validate:local": "npm run lint:plugin-manifest && npm run lint:tables && npm run lint:md && npm run lint:ps && npm run lint:yaml && npm run lint:json && npm run lint:links && npm run lint:md-links && npm run lint:frontmatter && npm run lint:adr-consistency && npm run lint:hooks && npm run lint:design-intent && npm run lint:version-consistency && npm run lint:permissions && npm run lint:workflow-runner && npm run lint:dangerous-workflow && npm run lint:dependency-pinning && npm run lint:public-dependency-feeds && npm run lint:pr-gate && npm run lint:ps-module-pins && npm run lint:extension-artifact-naming && npm run lint:py && npm run validate:skills && npm run lint:ai-artifacts && npm run lint:asset-docs && npm run lint:models && npm run validate:devcontainer-lockfile",
     "lint:tables": "pwsh -NoProfile -File scripts/linting/Format-MarkdownTables.ps1 -Check",
     "format:tables": "pwsh -NoProfile -File scripts/linting/Format-MarkdownTables.ps1",
     "extension:prepare": "pwsh ./scripts/extension/Prepare-Extension.ps1 && npm run extension:postprocess",

scripts/security/Modules/SecurityClasses.psm1

@@ -36,6 +36,8 @@ class DependencyViolation {
         - MissingVersionComment: Dependency is pinned but lacks a human-readable version comment
         - MissingPermissions: Workflow file lacks required permissions declarations
         - MissingJobPermissions: Workflow job lacks its own permissions declaration and inherits an implicit grant
+        - NonUbuntuRunner: Job's runs-on value is not a GitHub-hosted Ubuntu label
+        - MissingRunner: Job has no resolvable runs-on value
         - Empty string: Default or unclassified violation
     #>
 
@@ -47,7 +49,7 @@ class DependencyViolation {
     [string]$CurrentRef
     [ValidateSet('High', 'Medium', 'Low', 'Info')]
     [string]$Severity
-    [ValidateSet('Unpinned', 'Stale', 'VersionMismatch', 'MissingVersionComment', 'MissingPermissions', 'MissingJobPermissions', '')]
+    [ValidateSet('Unpinned', 'Stale', 'VersionMismatch', 'MissingVersionComment', 'MissingPermissions', 'MissingJobPermissions', 'NonUbuntuRunner', 'MissingRunner', '')]
     [string]$ViolationType
     [string]$Description
     [string]$Remediation