Add negative fixture tests and host preflight checks for cloud-hypervisor

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>

Author: Copilot

actions/setup/sh/cloud_hypervisor_host_preflight.sh

@@ -8,6 +8,9 @@ set +o histexpand
 # - GitHub-hosted runners only
 # - Ubuntu Linux x86_64 only
 # - /dev/kvm must be present
+# - gh, rsync, and docker host tools must be present, with a usable Docker Engine
+# - a usable cgroup v2 hierarchy must be present
+# - the running kernel must report Landlock LSM support
 
 set -euo pipefail
 
@@ -43,5 +46,32 @@ if ! test -c /dev/kvm; then
   exit 1
 fi
 
+for tool in gh rsync docker; do
+  if ! command -v "${tool}" >/dev/null 2>&1; then
+    echo "::error::required host tool is missing: ${tool}. AWF's cloud-hypervisor runtime needs gh (attested artifact verification), rsync (guest rootfs staging), and docker (infrastructure containers)."
+    exit 1
+  fi
+done
+
+if ! docker info >/dev/null 2>&1; then
+  echo "::error::a host-visible Docker Engine is required for cloud-hypervisor's infrastructure containers."
+  exit 1
+fi
+
+if [[ ! -r /sys/fs/cgroup/cgroup.controllers ]]; then
+  echo "::error::a usable cgroup v2 hierarchy is required to bound the cloud-hypervisor process (/sys/fs/cgroup/cgroup.controllers is unreadable)."
+  exit 1
+fi
+
+if [[ -r /sys/kernel/security/lsm ]]; then
+  if ! grep -Fq landlock /sys/kernel/security/lsm; then
+    echo "::error::the running kernel does not report Landlock in /sys/kernel/security/lsm, which the cloud-hypervisor launcher requires for filesystem confinement."
+    exit 1
+  fi
+else
+  echo "::error::/sys/kernel/security/lsm is unavailable; cannot confirm Landlock LSM support required by the cloud-hypervisor launcher."
+  exit 1
+fi
+
 echo "runner is eligible for cloud-hypervisor preview"
 echo "::endgroup::"

docs/src/content/docs/reference/agent-runtimes.md

@@ -283,13 +283,13 @@ Preview scope is intentionally narrow:
 
 - GitHub-hosted runners only (`RUNNER_ENVIRONMENT=github-hosted`).
 - Ubuntu Linux x86_64 only (`RUNNER_OS=Linux`, `RUNNER_ARCH=X64`, `ImageOS=ubuntu*`).
-- `/dev/kvm` must be present.
+- `/dev/kvm` must be present, and the host must have `gh`, `rsync`, and Docker (with a running Docker Engine), a usable cgroup v2 hierarchy, and a kernel that reports Landlock LSM support.
 - `runner.topology: arc-dind` is not supported.
 - `tools.github.mode: gh-proxy` and the `integrity-reactions` feature are not supported: the CLI proxy sidecar is not attached to the isolated topology.
 - `sandbox.agent.allow-host-ports` and GitHub Actions `services:` with published ports are not supported: host access requires `sandbox.agent.runtime: docker-sudo-iptables`.
 - `enclaves` configuration is not supported.
 
-The compiler grants only the runner user read/write access to `/dev/kvm`, then emits host preflight and release-asset provisioning steps before AWF runs. Provisioning downloads the Cloud Hypervisor bundle, `SHA256SUMS`, and `manifest.json` from the pinned `gh-aw-firewall` release, verifies checksums, and feeds AWF digest-pinned flags for the Cloud Hypervisor binary, `virtiofsd`, kernel, rootfs, and supervisor.
+The compiler grants only the runner user read/write access to `/dev/kvm`, then emits host preflight and release-asset provisioning steps before AWF runs. Host preflight fails closed unless `/dev/kvm`, `gh`, `rsync`, Docker, a usable cgroup v2 hierarchy, and Landlock LSM support are all present. Provisioning downloads the Cloud Hypervisor guest archive together with its attested `manifest.json` and Sigstore `manifest.sigstore.jsonl` bundle from the pinned `gh-aw-firewall` release, validates the release identity, artifact names, and bundle structure, and feeds AWF the manifest path, bundle path, and exact release tag so AWF can perform the authoritative offline Sigstore/provenance verification for the Cloud Hypervisor binary, `virtiofsd`, kernel, rootfs, and supervisor.
 
 AWF launches with host privileges required to create the VM, but the runtime remains in strict network-isolation mode. The guest defaults to 2 vCPUs and 4096 MiB of memory. Its trusted topology attachment is limited to the MCP gateway on TCP 8080; the CLI proxy is not attached.
 

pkg/workflow/cloud_hypervisor_test.go

@@ -3,7 +3,12 @@
 package workflow
 
 import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"fmt"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -440,7 +445,7 @@ func TestCloudHypervisorShellScriptContent(t *testing.T) {
 		},
 		{
 			script:   "cloud_hypervisor_host_preflight.sh",
-			contains: []string{"RUNNER_ENVIRONMENT", "github-hosted", "ImageOS", "/dev/kvm", "test -c /dev/kvm", "cloud-hypervisor preview"},
+			contains: []string{"RUNNER_ENVIRONMENT", "github-hosted", "ImageOS", "/dev/kvm", "test -c /dev/kvm", "cloud-hypervisor preview", "gh rsync docker", "docker info", "/sys/fs/cgroup/cgroup.controllers", "landlock", "/sys/kernel/security/lsm"},
 		},
 		{
 			script:   "cloud_hypervisor_setup_bundle.sh",
@@ -458,3 +463,217 @@ func TestCloudHypervisorShellScriptContent(t *testing.T) {
 		})
 	}
 }
+
+const cloudHypervisorFixtureReleaseTag = "v9.9.9"
+
+// cloudHypervisorFixtureManifest returns a manifest JSON document that
+// satisfies the jq contract enforced by cloud_hypervisor_setup_bundle.sh,
+// for the given release tag.
+func cloudHypervisorFixtureManifest(releaseTag string) string {
+	sha := strings.Repeat("b", 64)
+	return fmt.Sprintf(`{
+  "schemaVersion": 1,
+  "release": {
+    "repository": "github/gh-aw-firewall",
+    "workflow": "github/gh-aw-firewall/.github/workflows/release.yml",
+    "tag": %q,
+    "sourceCommit": "%s"
+  },
+  "architecture": "x86_64",
+  "artifacts": {
+    "cloudHypervisor": {"file": "cloud-hypervisor", "sha256": "%s"},
+    "virtiofsd": {"file": "virtiofsd", "sha256": "%s"},
+    "kernel": {"file": "vmlinux.bin", "sha256": "%s"},
+    "rootfs": {"file": "rootfs.ext4", "sha256": "%s"},
+    "supervisor": {"file": "awf-supervisor", "sha256": "%s"}
+  }
+}`, releaseTag, strings.Repeat("a", 40), sha, sha, sha, sha, sha)
+}
+
+const cloudHypervisorFixtureBundle = `{"mediaType":"application/vnd.dev.sigstore.bundle.v0.3+json","verificationMaterial":{}}` + "\n"
+
+// buildCloudHypervisorFixtureArchive builds a valid tar.gz guest archive
+// containing the five artifact files cloud_hypervisor_setup_bundle.sh
+// requires after extraction.
+func buildCloudHypervisorFixtureArchive(t *testing.T) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	gz := gzip.NewWriter(&buf)
+	tw := tar.NewWriter(gz)
+	for _, name := range []string{"cloud-hypervisor", "virtiofsd", "vmlinux.bin", "rootfs.ext4", "awf-supervisor"} {
+		content := []byte("fixture-content-" + name)
+		require.NoError(t, tw.WriteHeader(&tar.Header{
+			Name: name,
+			Mode: 0o755,
+			Size: int64(len(content)),
+		}))
+		_, err := tw.Write(content)
+		require.NoError(t, err)
+	}
+	require.NoError(t, tw.Close())
+	require.NoError(t, gz.Close())
+	return buf.Bytes()
+}
+
+// writeCloudHypervisorCurlShim installs a fake curl on PATH that copies
+// files out of fixtureDir instead of performing a network request, keyed by
+// the requested URL's basename. A "<basename>.symlink-target" sidecar file
+// makes the shim create a symlink pointing at its contents instead of
+// copying a regular file, simulating a substituted/tampered artifact. A
+// missing fixture makes the shim fail closed like a real curl 404.
+func writeCloudHypervisorCurlShim(t *testing.T, fixtureDir string) string {
+	t.Helper()
+	binDir := t.TempDir()
+	script := "#!/usr/bin/env bash\n" +
+		"set -euo pipefail\n" +
+		"outfile=\"\"\n" +
+		"prev=\"\"\n" +
+		"for arg in \"$@\"; do\n" +
+		"  if [[ \"$prev\" == \"-o\" ]]; then\n" +
+		"    outfile=\"$arg\"\n" +
+		"  fi\n" +
+		"  prev=\"$arg\"\n" +
+		"done\n" +
+		"url=\"${!#}\"\n" +
+		"name=\"$(basename \"$url\")\"\n" +
+		"src=\"" + fixtureDir + "/${name}\"\n" +
+		"if [[ -f \"${src}.symlink-target\" ]]; then\n" +
+		"  ln -sf \"$(cat \"${src}.symlink-target\")\" \"$outfile\"\n" +
+		"  exit 0\n" +
+		"fi\n" +
+		"if [[ ! -e \"$src\" ]]; then\n" +
+		"  exit 22\n" +
+		"fi\n" +
+		"cp \"$src\" \"$outfile\"\n"
+	shimPath := filepath.Join(binDir, "curl")
+	require.NoError(t, os.WriteFile(shimPath, []byte(script), 0o755))
+	return binDir
+}
+
+// runCloudHypervisorSetupBundleScript executes the real
+// cloud_hypervisor_setup_bundle.sh script against fixtureDir via the curl
+// shim, so the script's own validation logic runs end-to-end.
+func runCloudHypervisorSetupBundleScript(t *testing.T, fixtureDir string) (string, error) {
+	t.Helper()
+	wd, err := os.Getwd()
+	require.NoError(t, err)
+	scriptPath, err := filepath.Abs(filepath.Join(wd, "..", "..", "actions", "setup", "sh", "cloud_hypervisor_setup_bundle.sh"))
+	require.NoError(t, err)
+
+	binDir := writeCloudHypervisorCurlShim(t, fixtureDir)
+	runnerTemp := t.TempDir()
+
+	cmd := exec.Command("bash", scriptPath)
+	cmd.Env = append(os.Environ(),
+		"RUNNER_TEMP="+runnerTemp,
+		"GH_AW_AWF_VERSION="+cloudHypervisorFixtureReleaseTag,
+		"PATH="+binDir+":"+os.Getenv("PATH"),
+	)
+	out, err := cmd.CombinedOutput()
+	return string(out), err
+}
+
+func TestCloudHypervisorSetupBundleScriptExecutesAgainstFixtures(t *testing.T) {
+	validManifest := cloudHypervisorFixtureManifest(cloudHypervisorFixtureReleaseTag)
+	validArchive := buildCloudHypervisorFixtureArchive(t)
+	archiveName := "cloud-hypervisor-test-x86_64.tar.gz"
+	manifestName := "cloud-hypervisor-test-x86_64.manifest.json"
+	bundleName := "cloud-hypervisor-test-x86_64.manifest.sigstore.jsonl"
+
+	t.Run("valid fixtures succeed", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(dir, archiveName), validArchive, 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, manifestName), []byte(validManifest), 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, bundleName), []byte(cloudHypervisorFixtureBundle), 0o644))
+
+		out, err := runCloudHypervisorSetupBundleScript(t, dir)
+		require.NoError(t, err, out)
+		assert.Contains(t, out, "cloud-hypervisor bundle prepared")
+	})
+
+	t.Run("missing manifest fails closed", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(dir, archiveName), validArchive, 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, bundleName), []byte(cloudHypervisorFixtureBundle), 0o644))
+
+		out, err := runCloudHypervisorSetupBundleScript(t, dir)
+		require.Error(t, err, out)
+	})
+
+	t.Run("missing bundle fails closed", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(dir, archiveName), validArchive, 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, manifestName), []byte(validManifest), 0o644))
+
+		out, err := runCloudHypervisorSetupBundleScript(t, dir)
+		require.Error(t, err, out)
+	})
+
+	t.Run("malformed manifest json rejected", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(dir, archiveName), validArchive, 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, manifestName), []byte(`{"schemaVersion": 1, "not": "a valid manifest"}`), 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, bundleName), []byte(cloudHypervisorFixtureBundle), 0o644))
+
+		out, err := runCloudHypervisorSetupBundleScript(t, dir)
+		require.Error(t, err, out)
+		assert.Contains(t, out, "does not match the cloud-hypervisor release bundle contract")
+	})
+
+	t.Run("release tag mismatch rejected", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(dir, archiveName), validArchive, 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, manifestName), []byte(cloudHypervisorFixtureManifest("v1.0.0")), 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, bundleName), []byte(cloudHypervisorFixtureBundle), 0o644))
+
+		out, err := runCloudHypervisorSetupBundleScript(t, dir)
+		require.Error(t, err, out)
+		assert.Contains(t, out, "does not match the cloud-hypervisor release bundle contract")
+	})
+
+	t.Run("substituted manifest symlink rejected", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(dir, archiveName), validArchive, 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, manifestName), []byte(validManifest), 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, manifestName+".symlink-target"), []byte("/etc/passwd"), 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, bundleName), []byte(cloudHypervisorFixtureBundle), 0o644))
+
+		out, err := runCloudHypervisorSetupBundleScript(t, dir)
+		require.Error(t, err, out)
+		assert.Contains(t, out, "does not match the cloud-hypervisor release bundle contract")
+	})
+
+	t.Run("malformed bundle jsonl rejected", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(dir, archiveName), validArchive, 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, manifestName), []byte(validManifest), 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, bundleName), []byte("not-json\n"), 0o644))
+
+		out, err := runCloudHypervisorSetupBundleScript(t, dir)
+		require.Error(t, err, out)
+		assert.Contains(t, out, "is missing or malformed")
+	})
+
+	t.Run("empty bundle rejected", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(dir, archiveName), validArchive, 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, manifestName), []byte(validManifest), 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, bundleName), []byte(""), 0o644))
+
+		out, err := runCloudHypervisorSetupBundleScript(t, dir)
+		require.Error(t, err, out)
+		assert.Contains(t, out, "is missing or malformed")
+	})
+
+	t.Run("substituted bundle symlink rejected", func(t *testing.T) {
+		dir := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(dir, archiveName), validArchive, 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, manifestName), []byte(validManifest), 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, bundleName), []byte(cloudHypervisorFixtureBundle), 0o644))
+		require.NoError(t, os.WriteFile(filepath.Join(dir, bundleName+".symlink-target"), []byte("/etc/passwd"), 0o644))
+
+		out, err := runCloudHypervisorSetupBundleScript(t, dir)
+		require.Error(t, err, out)
+		assert.Contains(t, out, "is missing or malformed")
+	})
+}