M52: Better release verification UX — Makefile, release manifest, structured verify output

SecAI-Hub · claude · SecAI-Hub · commit b7931ea36261 · 2026-03-14T21:07:06.000-07:00
Add repo-root Makefile with developer targets (verify-release, test,
shellcheck, lint).  Add RELEASE_MANIFEST.json generation to release CI
pipeline (image digest, binaries with SHA256, SBOMs, provenance, checksums,
build metadata — transitively signed via SHA256SUMS).  Enhance
verify-release.sh with --json and --report flags for machine-readable and
human-readable structured output while preserving backward compatibility.
Wire audit-quick-path.md to verify-release.sh with Make target reference.
Update sample-release-bundle.md with manifest documentation.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -108,6 +108,101 @@ jobs:
           path: dist/
           merge-multiple: true
 
+      - name: Record release image digest
+        run: |
+          IMAGE_REF="ghcr.io/${{ github.repository }}"
+          TAG="${{ github.ref_name }}"
+          DIGEST=$(skopeo inspect "docker://${IMAGE_REF}:${TAG}" 2>/dev/null | jq -r '.Digest' || echo "")
+          if [ -n "$DIGEST" ] && [ "$DIGEST" != "null" ]; then
+            echo "${DIGEST}" > dist/IMAGE_DIGEST
+            echo "${IMAGE_REF}@${DIGEST}" > dist/IMAGE_REF_PINNED
+            echo "## Install with digest pinning" >> "$GITHUB_STEP_SUMMARY"
+            echo '```bash' >> "$GITHUB_STEP_SUMMARY"
+            echo "sudo bash secai-bootstrap.sh --digest ${DIGEST}" >> "$GITHUB_STEP_SUMMARY"
+            echo '```' >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "WARNING: Could not extract image digest for tag ${TAG}"
+            echo "unknown" > dist/IMAGE_DIGEST
+          fi
+
+      - name: Generate release manifest
+        run: |
+          cd dist
+
+          # Collect binary names + SHA256 hashes
+          BINARIES_JSON="[]"
+          for bin in *-linux-*; do
+            [ -f "$bin" ] || continue
+            HASH=$(sha256sum "$bin" | awk '{print $1}')
+            BINARIES_JSON=$(echo "$BINARIES_JSON" | jq \
+              --arg name "$bin" --arg sha256 "$HASH" \
+              '. + [{"name": $name, "sha256": $sha256}]')
+          done
+
+          # Collect SBOM filenames
+          SBOMS_JSON="[]"
+          for sbom in *-sbom.cdx.json; do
+            [ -f "$sbom" ] || continue
+            SBOMS_JSON=$(echo "$SBOMS_JSON" | jq \
+              --arg name "$sbom" \
+              '. + [$name]')
+          done
+
+          # Read image digest
+          IMAGE_DIGEST="unknown"
+          if [ -f IMAGE_DIGEST ]; then
+            IMAGE_DIGEST=$(cat IMAGE_DIGEST)
+          fi
+          IMAGE_REF_PINNED=""
+          if [ -f IMAGE_REF_PINNED ]; then
+            IMAGE_REF_PINNED=$(cat IMAGE_REF_PINNED)
+          fi
+
+          # Build manifest JSON
+          jq -n \
+            --arg schema_version "1" \
+            --arg tag "${{ github.ref_name }}" \
+            --arg image_ref "ghcr.io/${{ github.repository }}" \
+            --arg image_digest "$IMAGE_DIGEST" \
+            --arg image_ref_pinned "$IMAGE_REF_PINNED" \
+            --argjson binaries "$BINARIES_JSON" \
+            --argjson sboms "$SBOMS_JSON" \
+            --arg provenance_type "https://slsa.dev/provenance/v1" \
+            --arg checksum_file "SHA256SUMS" \
+            --arg signature_file "SHA256SUMS.sig" \
+            --arg commit_sha "${{ github.sha }}" \
+            --arg workflow_run "${{ github.run_id }}" \
+            --arg workflow_ref "${{ github.workflow_ref }}" \
+            --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            '{
+              schema_version: $schema_version,
+              tag: $tag,
+              image: {
+                ref: $image_ref,
+                digest: $image_digest,
+                ref_pinned: $image_ref_pinned
+              },
+              binaries: $binaries,
+              sboms: $sboms,
+              provenance: {
+                type: $provenance_type,
+                attested: true
+              },
+              checksums: {
+                file: $checksum_file,
+                signature: $signature_file
+              },
+              build: {
+                commit_sha: $commit_sha,
+                workflow_run: $workflow_run,
+                workflow_ref: $workflow_ref,
+                timestamp: $timestamp
+              }
+            }' > RELEASE_MANIFEST.json
+
+          echo "--- RELEASE_MANIFEST.json ---"
+          cat RELEASE_MANIFEST.json
+
       - name: Generate SHA256 checksums
         run: |
           cd dist
@@ -141,23 +236,6 @@ jobs:
         env:
           COSIGN_PRIVATE_KEY: ${{ secrets.SIGNING_SECRET }}
 
-      - name: Record release image digest
-        run: |
-          IMAGE_REF="ghcr.io/${{ github.repository }}"
-          TAG="${{ github.ref_name }}"
-          DIGEST=$(skopeo inspect "docker://${IMAGE_REF}:${TAG}" 2>/dev/null | jq -r '.Digest' || echo "")
-          if [ -n "$DIGEST" ] && [ "$DIGEST" != "null" ]; then
-            echo "${DIGEST}" > dist/IMAGE_DIGEST
-            echo "${IMAGE_REF}@${DIGEST}" > dist/IMAGE_REF_PINNED
-            echo "## Install with digest pinning" >> "$GITHUB_STEP_SUMMARY"
-            echo '```bash' >> "$GITHUB_STEP_SUMMARY"
-            echo "sudo bash secai-bootstrap.sh --digest ${DIGEST}" >> "$GITHUB_STEP_SUMMARY"
-            echo '```' >> "$GITHUB_STEP_SUMMARY"
-          else
-            echo "WARNING: Could not extract image digest for tag ${TAG}"
-            echo "unknown" > dist/IMAGE_DIGEST
-          fi
-
       - name: Create GitHub Release
         if: ${{ !inputs.dry_run }}
         uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631 # v2.2.2
@@ -169,5 +247,6 @@ jobs:
             dist/SHA256SUMS.sig
             dist/IMAGE_DIGEST
             dist/IMAGE_REF_PINNED
+            dist/RELEASE_MANIFEST.json
           generate_release_notes: true
           fail_on_unmatched_files: false
diff --git a/Makefile b/Makefile
@@ -0,0 +1,58 @@
+# SecAI OS — Developer Targets
+# Usage: make help
+#
+# Thin wrappers around existing CI / verification commands.
+# No build targets — image builds are handled by BlueBuild + release.yml.
+
+.DEFAULT_GOAL := help
+SHELL := /usr/bin/env bash
+
+# ---------------------------------------------------------------------------
+# Configuration (override via environment or make args)
+# ---------------------------------------------------------------------------
+IMAGE ?= ghcr.io/secai-hub/secai_os:latest
+
+GO_SERVICES := airlock registry tool-firewall gpu-integrity-watch mcp-firewall \
+               policy-engine runtime-attestor integrity-monitor incident-recorder
+
+SCRIPTS_LIBEXEC := $(wildcard files/system/usr/libexec/secure-ai/*.sh)
+SCRIPTS_FILES   := $(wildcard files/scripts/*.sh)
+
+# ---------------------------------------------------------------------------
+# Targets
+# ---------------------------------------------------------------------------
+
+.PHONY: help
+help: ## Show available targets
+	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | \
+	  awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: verify-release
+verify-release: ## Verify a release image (IMAGE=ghcr.io/...)
+	@files/scripts/verify-release.sh "$(IMAGE)"
+
+.PHONY: test
+test: test-go test-python ## Run all tests (Go + Python)
+
+.PHONY: test-go
+test-go: ## Run Go service tests (all 9 services, -race)
+	@for svc in $(GO_SERVICES); do \
+	  echo "=== $${svc} ===" ; \
+	  (cd services/$${svc} && go test -v -race -count=1 ./...) || exit 1 ; \
+	done
+
+.PHONY: test-python
+test-python: ## Run Python tests (pytest tests/ -v)
+	PYTHONPATH=services python -m pytest tests/ -v
+
+.PHONY: shellcheck
+shellcheck: ## Lint all shell scripts with shellcheck
+	shellcheck -s bash $(SCRIPTS_LIBEXEC) $(SCRIPTS_FILES)
+
+.PHONY: lint
+lint: shellcheck ## Combined lint (shellcheck + ruff + go vet)
+	ruff check services/ tests/ --select E,F,W --ignore E501,E402
+	@for svc in $(GO_SERVICES); do \
+	  echo "--- vet: $${svc} ---" ; \
+	  (cd services/$${svc} && go vet ./...) || exit 1 ; \
+	done
diff --git a/README.md b/README.md
@@ -158,7 +158,7 @@ Every model passes through the same fully automatic pipeline:
 | **Updates** | Cosign-verified rpm-ostree, staged workflow, greenboot auto-rollback |
 | **Supply Chain** | Per-service CycloneDX SBOMs, SLSA3 provenance attestation, cosign-signed checksums |
 
-See [docs/threat-model.md](docs/threat-model.md) for threat classes, residual risks, and security invariants. See [docs/security-status.md](docs/security-status.md) for implementation status of all 51 milestones.
+See [docs/threat-model.md](docs/threat-model.md) for threat classes, residual risks, and security invariants. See [docs/security-status.md](docs/security-status.md) for implementation status of all 52 milestones.
 
 ### Verify Image Signatures
 
@@ -241,7 +241,7 @@ All CI jobs are defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml
 | [Threat Model](docs/threat-model.md) | Threat classes, invariants, residual risks |
 | [API Reference](docs/api.md) | HTTP API for all services |
 | [Policy Schema](docs/policy-schema.md) | Full policy.yaml schema reference |
-| [Security Status](docs/security-status.md) | Implementation status of all 50 milestones |
+| [Security Status](docs/security-status.md) | Implementation status of all 52 milestones |
 | [Test Matrix](docs/test-matrix.md) | Test coverage: 1,141 tests across Go and Python (see [test-counts.json](docs/test-counts.json)) |
 | [Compatibility Matrix](docs/compatibility-matrix.md) | GPU, VM, and hardware support |
 | [Security Test Matrix](docs/security-test-matrix.md) | Security feature test coverage |
@@ -378,7 +378,7 @@ See [docs/test-matrix.md](docs/test-matrix.md) for full breakdown.
 ## Roadmap
 
 <details>
-<summary>All 51 project milestones (click to expand)</summary>
+<summary>All 52 project milestones (click to expand)</summary>
 
 - [x] **Milestone 0** -- Threat model, dataflow, invariants, policy files
 - [x] **Milestone 1** -- Bootable OS, encrypted vault, GPU drivers
@@ -432,6 +432,7 @@ See [docs/test-matrix.md](docs/test-matrix.md) for full breakdown.
 - [x] **Milestone 49** -- Signed-first install path: bootstrap script configures signing policy before first rebase (eliminates unverified transport), digest-pinned install flow (CI publishes digests in build summary + release assets), first-boot setup wizard (interactive integrity verification + vault + TPM2 + health check), recovery/dev path separated into dedicated doc
 - [x] **Milestone 50** -- Production operations package: backup/restore scripts (full/config/logs/keys categories, age/gpg encryption, SHA256 manifest, LUKS header backup/restore), rollback decision matrix (Greenboot auto-rollback + manual criteria), 5 break-glass recovery procedures, formal data retention policy (7 data classes, disk capacity thresholds)
 - [x] **Milestone 51** -- Stronger observability: unified appliance health dashboard (trusted/degraded/recovery_required), live SLO compliance monitoring (uptime + P95 latency tracking), webhook alerting hooks for containment events, forensic bundle export via UI + CLI (secai-forensic.sh), recovery ceremony endpoints wired
+- [x] **Milestone 52** -- Better release verification UX: repo-root Makefile (verify-release, test, shellcheck, lint), RELEASE_MANIFEST.json in release CI (image digest, binaries, SBOMs, provenance, checksums, build metadata), verify-release.sh --json and --report flags, audit-quick-path wired to verify-release.sh
 
 </details>
 
diff --git a/docs/audit-quick-path.md b/docs/audit-quick-path.md
@@ -230,6 +230,37 @@ cosign verify-blob \
 sha256sum -c SHA256SUMS
 ```
 
+### Automated Release Verification
+
+For a single-command verification of all supply-chain artifacts, use the `verify-release.sh` script:
+
+```bash
+# Download release artifacts
+mkdir release && cd release
+gh release download v1.0.0 -R SecAI-Hub/SecAI_OS
+
+# Place cosign.pub (or set COSIGN_PUB_KEY)
+cp /path/to/cosign.pub .
+
+# Run full verification (colored terminal output)
+../files/scripts/verify-release.sh ghcr.io/secai-hub/secai_os:v1.0.0
+
+# Generate a human-readable report file
+../files/scripts/verify-release.sh --report verification-report.txt \
+  ghcr.io/secai-hub/secai_os:v1.0.0
+
+# Machine-readable JSON output (for CI pipelines or tooling)
+../files/scripts/verify-release.sh --json ghcr.io/secai-hub/secai_os:v1.0.0
+```
+
+The script checks cosign image signature, CycloneDX SBOM attestation, SLSA3 provenance attestation, and SHA256 checksums. See `files/scripts/verify-release.sh --help` for configuration options.
+
+Or via Make:
+
+```bash
+make verify-release IMAGE=ghcr.io/secai-hub/secai_os:v1.0.0
+```
+
 ### Forensic Bundle Integrity
 
 Export and verify a forensic bundle from a running appliance:
@@ -382,24 +413,33 @@ Run this all-in-one script to validate the test suite and artifact structure fro
 set -e
 echo "=== M5 Audit Quick Validation ==="
 
-echo "[1/5] M5 acceptance suite..."
+echo "[1/6] M5 acceptance suite..."
 PYTHONPATH=services python -m pytest tests/test_m5_acceptance.py -v --tb=short
 
-echo "[2/5] Adversarial tests..."
+echo "[2/6] Adversarial tests..."
 PYTHONPATH=services python -m pytest tests/test_adversarial.py -v --tb=short
 
-echo "[3/5] Incident recorder recovery/forensic tests..."
+echo "[3/6] Incident recorder recovery/forensic tests..."
 (cd services/incident-recorder && go test -v -race -run "TestRecovery|TestEscalation|TestForensic|TestLatched" ./...)
 
-echo "[4/5] MCP firewall adversarial tests..."
+echo "[4/6] MCP firewall adversarial tests..."
 (cd services/mcp-firewall && go test -v -race -run TestAdversarial ./...)
 
-echo "[5/5] All Go service tests..."
+echo "[5/6] All Go service tests..."
 for svc in airlock registry tool-firewall gpu-integrity-watch mcp-firewall \
            policy-engine runtime-attestor integrity-monitor incident-recorder; do
   echo "--- ${svc} ---"
   (cd services/${svc} && go test -race -count=1 ./...)
 done
 
+echo "[6/6] Release artifact verification..."
+if [ -f SHA256SUMS ]; then
+  files/scripts/verify-release.sh --report /tmp/secai-verify-report.txt \
+    ghcr.io/secai-hub/secai_os:latest
+  echo "Report: /tmp/secai-verify-report.txt"
+else
+  echo "SKIP: No release artifacts found (download with 'gh release download')"
+fi
+
 echo "=== All M5 checks passed ==="
 ```
diff --git a/docs/sample-release-bundle.md b/docs/sample-release-bundle.md
@@ -47,8 +47,11 @@ v1.0.0/
   diffusion-worker-sbom.cdx.json
   search-mediator-sbom.cdx.json
 
+  # Release manifest (machine-readable)
+  RELEASE_MANIFEST.json # structured JSON: image, binaries, SBOMs, provenance, build metadata
+
   # Checksums and signature
-  SHA256SUMS            # sha256sum of every artifact above
+  SHA256SUMS            # sha256sum of every artifact above (includes RELEASE_MANIFEST.json)
   SHA256SUMS.sig        # cosign detached signature over SHA256SUMS
 ```
 
@@ -81,6 +84,59 @@ cosign sign-blob --yes \
   SHA256SUMS
 ```
 
+## Release Manifest
+
+`RELEASE_MANIFEST.json` is a structured JSON file that catalogues every artifact in the release bundle. It is included in `SHA256SUMS` and is therefore transitively signed.
+
+Example structure:
+
+```json
+{
+  "schema_version": "1",
+  "tag": "v1.0.0",
+  "image": {
+    "ref": "ghcr.io/secai-hub/secai_os",
+    "digest": "sha256:a1b2c3d4e5f6...",
+    "ref_pinned": "ghcr.io/secai-hub/secai_os@sha256:a1b2c3d4e5f6..."
+  },
+  "binaries": [
+    {"name": "airlock-linux-amd64", "sha256": "e3b0c44298fc..."},
+    {"name": "airlock-linux-arm64", "sha256": "7d865e959b24..."}
+  ],
+  "sboms": [
+    "airlock-sbom.cdx.json",
+    "registry-sbom.cdx.json"
+  ],
+  "provenance": {
+    "type": "https://slsa.dev/provenance/v1",
+    "attested": true
+  },
+  "checksums": {
+    "file": "SHA256SUMS",
+    "signature": "SHA256SUMS.sig"
+  },
+  "build": {
+    "commit_sha": "abc123def456...",
+    "workflow_run": "12345678",
+    "workflow_ref": "SecAI-Hub/SecAI_OS/.github/workflows/release.yml@refs/tags/v1.0.0",
+    "timestamp": "2026-03-15T12:00:00Z"
+  }
+}
+```
+
+Use `jq` to inspect specific fields:
+
+```bash
+# Image digest
+jq -r '.image.digest' RELEASE_MANIFEST.json
+
+# List all binaries with their hashes
+jq '.binaries[] | .name + "  " + .sha256' RELEASE_MANIFEST.json
+
+# Build commit
+jq -r '.build.commit_sha' RELEASE_MANIFEST.json
+```
+
 ## SBOM Files
 
 Each service gets a CycloneDX JSON SBOM generated by [Syft](https://github.com/anchore/syft). These SBOMs list all direct and transitive dependencies for the service.
@@ -228,8 +284,17 @@ gh release download v1.0.0 -R SecAI-Hub/SecAI_OS
 # Place cosign.pub in the directory (or set COSIGN_PUB_KEY)
 cp /path/to/cosign.pub .
 
-# Run full verification
+# Run full verification (colored terminal output)
 ../files/scripts/verify-release.sh ghcr.io/secai-hub/secai_os:v1.0.0
+
+# Save a human-readable report
+../files/scripts/verify-release.sh --report report.txt ghcr.io/secai-hub/secai_os:v1.0.0
+
+# Machine-readable JSON (for CI pipelines or tooling)
+../files/scripts/verify-release.sh --json ghcr.io/secai-hub/secai_os:v1.0.0
+
+# Or via Make target from the repo root
+make verify-release IMAGE=ghcr.io/secai-hub/secai_os:v1.0.0
 ```
 
 The script prints PASS/FAIL for each step and exits non-zero if any check fails. See `--help` for configuration options.
diff --git a/docs/security-status.md b/docs/security-status.md
diff --git a/files/scripts/verify-release.sh b/files/scripts/verify-release.sh
