Fix USB boot flow and harden boot compatibility

Author: SecAI-Hub

.github/workflows/release.yml

@@ -207,6 +207,59 @@ jobs:
           name: iso-amd64
           path: dist/secai-os-*.iso*
 
+  build-usb-image:
+    name: Build Portable USB Image
+    needs: [preflight]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Free disk space
+        run: |
+          sudo rm -rf /usr/local/lib/android /usr/share/dotnet /opt/ghc
+          sudo docker image prune -af
+
+      - name: Install image build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y podman xz-utils
+
+      - name: Build portable USB image
+        run: |
+          mkdir -p dist
+          sudo bash scripts/build-usb-image.sh \
+            --image-ref "ghcr.io/secai-hub/secai_os:latest" \
+            --output-dir ./dist \
+            --version "${{ github.ref_name }}"
+
+      - name: Install cosign
+        run: |
+          COSIGN_VERSION="v2.4.3"
+          curl -sSfL "https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64" \
+            -o /usr/local/bin/cosign
+          chmod +x /usr/local/bin/cosign
+
+      - name: Sign portable USB image
+        run: |
+          USB_IMAGE=$(find dist -maxdepth 1 -name "secai-os-*-usb.raw.xz" -type f | head -1)
+          if [ -z "$USB_IMAGE" ]; then
+            echo "ERROR: portable USB image not found after build"
+            find dist -maxdepth 2 -type f
+            exit 1
+          fi
+          cosign sign-blob --yes \
+            --key env://COSIGN_PRIVATE_KEY \
+            --output-signature "${USB_IMAGE}.sig" \
+            "$USB_IMAGE"
+        env:
+          COSIGN_PRIVATE_KEY: ${{ secrets.SIGNING_SECRET }}
+
+      - name: Upload portable USB artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: usb-amd64
+          path: dist/secai-os-*-usb.raw.xz*
+
   build-vm-images:
     name: Build VM Images (QCOW2 + OVA)
     needs: [preflight]
@@ -253,7 +306,7 @@ jobs:
   provenance:
     name: SLSA Provenance & Attestation
     runs-on: ubuntu-latest
-    needs: [build-go, build-python, build-iso]
+    needs: [build-go, build-python, build-iso, build-usb-image]
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
@@ -365,11 +418,14 @@ jobs:
 
           # Add install artifacts (conditionally present)
           INSTALL_JSON="{}"
-          for artifact in secai-os-*.iso secai-os-*.qcow2 secai-os-*.ova; do
+          for artifact in secai-os-*.iso secai-os-*.qcow2 secai-os-*.ova secai-os-*-usb.raw.xz; do
             [ -f "$artifact" ] || continue
             HASH=$(sha256sum "$artifact" | awk '{print $1}')
             SIZE=$(stat -c%s "$artifact" 2>/dev/null || stat -f%z "$artifact" 2>/dev/null || echo 0)
             TYPE="${artifact##*.}"
+            if [[ "$artifact" == *.raw.xz ]]; then
+              TYPE="usb_raw_xz"
+            fi
             INSTALL_JSON=$(echo "$INSTALL_JSON" | jq \
               --arg type "$TYPE" --arg name "$artifact" \
               --arg sha256 "$HASH" --arg size "$SIZE" \
@@ -430,23 +486,24 @@ jobs:
             dist/IMAGE_REF_PINNED
             dist/RELEASE_MANIFEST.json
             dist/secai-os-*.iso.sig
+            dist/secai-os-*-usb.raw.xz.sig
             dist/secai-os-*.qcow2.sig
             dist/secai-os-*.ova.sig
           generate_release_notes: true
           fail_on_unmatched_files: false
 
-      # ISO/QCOW2/OVA files are too large for GitHub Releases (>2GB limit).
+      # Install media files are too large for GitHub Releases (>2GB limit).
       # Upload signatures only (above). The full images are available as
       # workflow artifacts or should be hosted on external storage.
       - name: Note on large artifacts
         if: ${{ !inputs.dry_run }}
         run: |
           echo "## Large Artifacts" >> "$GITHUB_STEP_SUMMARY"
           echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "ISO/QCOW2/OVA files exceed GitHub Releases' 2GB limit." >> "$GITHUB_STEP_SUMMARY"
+          echo "Install media files can exceed GitHub Releases' 2GB limit." >> "$GITHUB_STEP_SUMMARY"
           echo "Their cosign signatures (.sig) are included in the release." >> "$GITHUB_STEP_SUMMARY"
           echo "Full images are available as workflow artifacts (90-day retention)." >> "$GITHUB_STEP_SUMMARY"
-          for f in dist/secai-os-*.iso dist/secai-os-*.qcow2 dist/secai-os-*.ova; do
+          for f in dist/secai-os-*.iso dist/secai-os-*-usb.raw.xz dist/secai-os-*.qcow2 dist/secai-os-*.ova; do
             [ -f "$f" ] || continue
             SIZE=$(stat -c%s "$f" 2>/dev/null || echo 0)
             SIZE_MB=$((SIZE / 1048576))

.gitignore

@@ -33,3 +33,4 @@ dist/
 # OS
 .DS_Store
 Thumbs.db
+/.bluebuild-scripts_*

README.md

@@ -67,6 +67,7 @@ The setup wizard guides you through privacy profile selection, system verificati
 | Method | Time | Best For | Details |
 |--------|------|----------|---------|
 | **Bootstrap** (Recommended) | ~30 min | Real PC or VM | Install Fedora Silverblue, run script, reboot |
+| **Portable USB** | ~10 min | Run directly from a USB stick | Flash the release `*-usb.raw.xz` artifact to removable media |
 | **Build VM locally** | ~45 min | VirtualBox / VMware / KVM | `scripts/vm/build-qcow2.sh` builds a QCOW2 from the OCI image |
 | **Development** | ~10 min | Service development only | No OS features; see [dev guide](docs/install/dev.md) |
 
@@ -204,18 +205,20 @@ Tagged releases (`v*`) are built by the [Release workflow](.github/workflows/rel
 | `IMAGE_DIGEST` | OCI image digest for this release |
 | `RELEASE_MANIFEST.json` | Machine-readable release manifest (binaries, SBOMs, provenance, build metadata) |
 | `secai-os-*.iso.sig` | Cosign signature for the bootable ISO |
+| `secai-os-*-usb.raw.xz.sig` | Cosign signature for the portable USB image |
 
 Go services shipped as release binaries: `airlock`, `registry`, `tool-firewall`, `gpu-integrity-watch`, `mcp-firewall`, `policy-engine`, `runtime-attestor`, `integrity-monitor`, `incident-recorder`.
 
 Python services (`ui`, `agent`, `quarantine`, `diffusion-worker`, `search-mediator`) are baked into the OCI image and do not ship as standalone binaries.
 
-### Bootable ISO
+### Bootable Media
 
-A signed bootable ISO is built by every tagged release using [build-container-installer](https://github.com/JasonN3/build-container-installer). The ISO exceeds GitHub's 2 GB release asset limit, so it is available as a **workflow artifact** (90-day retention) from the [Release workflow runs](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/release.yml). The cosign signature (`.iso.sig`) is published to the GitHub Release for verification.
+A signed bootable installer ISO is built by every tagged release using [build-container-installer](https://github.com/JasonN3/build-container-installer). Each release also includes a compressed portable USB image (`secai-os-*-usb.raw.xz`) built from the same bootc container so the OS can be flashed directly to a USB stick and run without first installing to the internal disk. Both artifacts are available as **workflow artifacts** (90-day retention) from the [Release workflow runs](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/release.yml), and their cosign signatures are published to the GitHub Release for verification.
 
-To build a QCOW2 or OVA locally from the OCI image:
+To build portable USB or VM media locally from the OCI image:
 
 ```bash
+bash scripts/build-usb-image.sh      # produces output/secai-os-<version>-x86_64-usb.raw(.xz)
 bash scripts/vm/build-qcow2.sh        # produces output/secai-os.qcow2
 bash scripts/vm/build-ova.sh           # produces output/secai-os.ova
 ```

docs/install/quickstart.md

@@ -7,10 +7,11 @@ Get SecAI OS running in the fewest steps possible. Choose the path that fits you
 | Method | Time | Difficulty | Best For |
 |--------|------|-----------|----------|
 | **Bootstrap** (Recommended) | ~30 min | Easy | Real PC or VM, full security |
+| **Portable USB** | ~10 min | Easy | Run directly from removable media without installing first |
 | **VM Build** | ~45 min | Moderate | Local evaluation in VirtualBox/VMware/KVM |
 | **Development** | ~10 min | Easy | Service development only (no OS features) |
 
-> **Note on ISO/OVA/QCOW2:** The release pipeline builds a signed bootable ISO, but it exceeds GitHub's 2 GB release asset limit. Pre-built VM images (OVA/QCOW2) require build infrastructure not yet provisioned. For now, the bootstrap path below is the primary install method. See [Artifact Availability](#artifact-availability) for details.
+> **Note on release media:** The release pipeline builds both an installer ISO and a portable USB image (`*-usb.raw.xz`). Pre-built VM images (OVA/QCOW2) still require build infrastructure not yet provisioned. The bootstrap path remains the recommended production install, but the portable USB artifact is the right choice when you want to boot and evaluate directly from removable media. See [Artifact Availability](#artifact-availability) for details.
 
 ---
 
@@ -160,11 +161,13 @@ make verify-release
 |----------|-------|--------|
 | **OCI image** | `ghcr.io/secai-hub/secai_os:latest` | Always available, cosign-signed |
 | **Go binaries + SBOMs** | [GitHub Releases](https://github.com/SecAI-Hub/SecAI_OS/releases/latest) | Always available |
-| **ISO** | Release workflow artifact (90-day retention) | Built in CI; too large (~4 GB) for GitHub Releases |
+| **Installer ISO** | Release workflow artifact (90-day retention) | Built in CI; intended for install-to-disk |
 | **ISO signature** | [GitHub Releases](https://github.com/SecAI-Hub/SecAI_OS/releases/latest) | `.iso.sig` file for verification |
+| **Portable USB image** | Release workflow artifact (90-day retention) | Built in CI as `secai-os-*-usb.raw.xz`; flash directly to removable media |
+| **Portable USB signature** | [GitHub Releases](https://github.com/SecAI-Hub/SecAI_OS/releases/latest) | `.raw.xz.sig` file for verification |
 | **QCOW2 / OVA** | `scripts/vm/build-qcow2.sh` / `build-ova.sh` | Build locally; CI build requires self-hosted KVM runner |
 
-The ISO is produced by every tagged release and is available as a [workflow artifact](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/release.yml) with 90-day retention. Its cosign signature (`.iso.sig`) is published to GitHub Releases for verification. For permanent ISO hosting, an external storage solution is needed.
+The installer ISO and portable USB image are produced by every tagged release and are available as [workflow artifacts](https://github.com/SecAI-Hub/SecAI_OS/actions/workflows/release.yml) with 90-day retention. Their cosign signatures are published to GitHub Releases for verification. For permanent hosting, an external storage solution is still needed.
 
 ---
 

docs/release-artifacts.json

@@ -56,6 +56,12 @@
         "description": "Bootable ISO (requires isogenerator)",
         "required_when": "always (standard runner)"
       },
+      "portable_usb": {
+        "pattern": "secai-os-{version}-x86_64-usb.raw.xz",
+        "signature": "secai-os-{version}-x86_64-usb.raw.xz.sig",
+        "description": "Direct-flash portable USB image built from bootc-image-builder raw output",
+        "required_when": "always (standard runner)"
+      },
       "qcow2": {
         "pattern": "secai-os-{version}.qcow2",
         "signature": "secai-os-{version}.qcow2.sig",

docs/release-policy.md

@@ -152,12 +152,13 @@ Each tagged release may include bootable install artifacts in addition to the OC
 |----------|--------|-------------|----------|
 | OCI image | Container | BlueBuild (build.yml) | Always |
 | ISO | Bootable installer | isogenerator (release.yml) | Always |
+| Portable USB | Direct-flash raw.xz | bootc-image-builder raw + xz (release.yml) | Always |
 | QCOW2 | KVM/QEMU disk image | build-qcow2.sh on KVM runner | When `vars.HAS_KVM_RUNNER` is set |
 | OVA | VirtualBox/VMware appliance | build-ova.sh on KVM runner | When `vars.HAS_KVM_RUNNER` is set |
 
 All install artifacts are built from the same OCI image. After installation, the upgrade path is identical regardless of install method: `rpm-ostree upgrade`.
 
-QCOW2 and OVA may be absent in releases if the repository does not have a self-hosted KVM runner configured. The ISO is always produced on standard GitHub runners.
+QCOW2 and OVA may be absent in releases if the repository does not have a self-hosted KVM runner configured. The installer ISO and portable USB image are produced on standard GitHub runners.
 
 See [release-artifacts.json](release-artifacts.json) for the machine-readable specification of expected artifacts.
 

docs/sample-release-bundle.md

@@ -53,6 +53,8 @@ v1.0.0/
   # Install artifacts (bootable images)
   secai-os-v1.0.0-x86_64.iso        # Bootable ISO (from isogenerator)
   secai-os-v1.0.0-x86_64.iso.sig    # cosign detached signature
+  secai-os-v1.0.0-x86_64-usb.raw.xz     # Portable USB image (direct-flash)
+  secai-os-v1.0.0-x86_64-usb.raw.xz.sig # cosign detached signature
   secai-os-v1.0.0.qcow2             # QCOW2 disk image (optional — requires KVM build infra)
   secai-os-v1.0.0.qcow2.sig         # cosign detached signature
   secai-os-v1.0.0.ova               # OVA appliance (optional — requires KVM build infra)
@@ -64,8 +66,9 @@ v1.0.0/
 ```
 
 > **Note:** QCOW2 and OVA artifacts may be absent if the repository does not have
-> a self-hosted KVM runner. The ISO is always produced. See `docs/release-artifacts.json`
-> for the machine-readable artifact specification.
+> a self-hosted KVM runner. The installer ISO and portable USB image are produced
+> on standard runners. See `docs/release-artifacts.json` for the machine-readable
+> artifact specification.
 
 ## Image Digest
 

files/scripts/verify-release.sh

@@ -336,7 +336,7 @@ echo ""
 info "Step 5: Verifying install artifact signatures (if present)..."
 
 install_artifacts_found=0
-for pattern in "secai-os-*.iso" "secai-os-*.qcow2" "secai-os-*.ova"; do
+for pattern in "secai-os-*.iso" "secai-os-*-usb.raw.xz" "secai-os-*.qcow2" "secai-os-*.ova"; do
     for artifact in $pattern; do
         [ -f "$artifact" ] || continue
         install_artifacts_found=$((install_artifacts_found + 1))
@@ -361,7 +361,7 @@ for pattern in "secai-os-*.iso" "secai-os-*.qcow2" "secai-os-*.ova"; do
 done
 
 if [[ $install_artifacts_found -eq 0 ]]; then
-    info "No install artifacts (ISO/QCOW2/OVA) found — skipping Step 5"
+    info "No install artifacts (ISO/USB/QCOW2/OVA) found — skipping Step 5"
     record_check 5 "install_artifacts" "SKIP" "no install artifacts present"
 fi
 

files/system/usr/lib/systemd/system/secure-ai-boot-kargs.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=Secure AI hardware-aware boot argument sync
+Documentation=https://github.com/SecAI-Hub/SecAI_OS
+After=local-fs.target
+Before=multi-user.target graphical.target
+ConditionPathExists=/usr/bin/rpm-ostree
+
+[Service]
+Type=oneshot
+ExecStart=/usr/libexec/secure-ai/sync-boot-kargs.sh
+RemainAfterExit=yes
+
+[Install]
+WantedBy=multi-user.target

files/system/usr/lib/systemd/system/secure-ai-firstboot.service

@@ -14,19 +14,21 @@ ProtectHome=yes
 PrivateTmp=yes
 
 # Kernel protection
-ProtectKernelTunables=yes
+# firstboot.sh intentionally adjusts a small set of boot-time sysctls
+# and may need to disable swap on the initial boot.
+ProtectKernelTunables=no
 ProtectKernelModules=yes
 ProtectKernelLogs=yes
 ProtectControlGroups=yes
 ProtectClock=yes
 ProtectHostname=yes
 
-# Capability bounding — root oneshot, no special caps needed
-CapabilityBoundingSet=
+# Capability bounding — firstboot performs host setup (sysctl, swapoff, nft)
+CapabilityBoundingSet=CAP_CHOWN CAP_DAC_OVERRIDE CAP_FOWNER CAP_NET_ADMIN CAP_SETGID CAP_SETUID CAP_SYS_ADMIN CAP_SYS_RESOURCE
 
 # Syscall filtering
 SystemCallFilter=@system-service
-SystemCallFilter=~@privileged @mount @clock @debug @swap @reboot @module @cpu-emulation @obsolete
+SystemCallFilter=~@privileged @mount @clock @debug @reboot @module @cpu-emulation @obsolete
 SystemCallArchitectures=native
 SystemCallErrorNumber=EPERM