Skip to content

test(installer): validate encrypted offline installations - #67

Closed
mrbobbytables wants to merge 1 commit into
projectbluefin:mainfrom
mrbobbytables:installer/validate-encrypted-offline-installations
Closed

mrbobbytables wants to merge 1 commit into
projectbluefin:mainfrom
mrbobbytables:installer/validate-encrypted-offline-installations

Conversation

@mrbobbytables

Copy link
Copy Markdown
Contributor

Fixes #15

Summary

Extend the Utah installer pipeline with Dakota-style encrypted installation coverage, including unlocking and booting the installed deployment without network access:

  • Volume creation & management: Add cryptsetup to packages/utah.toml under [services], allowing Fisherman to create LUKS encrypted volumes and enabling the installed system to manage encrypted devices.
  • Automated Plymouth unlock: Add iso/scripts/luks-unlock.py to automate Plymouth passphrase prompt detection via serial output and framebuffer screendumps, injecting keystrokes over QEMU monitor sendkey using standard Python library primitives.
  • Offline E2E orchestrator: Implement iso/scripts/offline-e2e.sh which:
    1. Boots the live ISO under QEMU with network isolation (restrict=on, host SSH forwarding only).
    2. Proves the live graphical desktop (graphical.target, gdm.service, gnome-shell).
    3. Executes Fisherman installation from the embedded containers-storage payload to a LUKS2 encrypted volume.
    4. Verifies offline payload integrity (/usr/share/utah/contract.txt) and confirms default Flatpaks remain available in /var/lib/flatpak/repo.
    5. Stages graphical boot assertions (utah-e2e-graphical.service) and verbose serial console boot loader entries (systemd.default_device_timeout_sec=180, console=ttyS0).
    6. Boots the installed system with -net none (network-isolated), unlocks the LUKS volume via luks-unlock.py, and confirms it reaches graphical target.
    7. Retains serial logs, screenshots, and failed disk images on errors.
  • CI pipeline: Add .github/workflows/iso.yml to build the production UEFI ISO, run the offline encrypted installation and graphical boot gates, and publish production ISO artifacts or retain failure diagnostics.
  • Unit test suite: Add tests/unit/test_luks_unlock.py covering serial log parsing, screendump analysis, key mapping, and CLI argument handling.
  • Tooling & Docs: Update Justfile with iso-e2e recipe and static checks; update docs/skills/local-testing.md, docs/skills/ci-workflows.md, and AGENTS.md.

Validation

  • python3 -m unittest tests/unit/test_luks_unlock.py -v passed (7 tests).
  • just check passed (manifest validation, parity checks, package verification for 4 desktop services, workflow outputs, skill catalog).
  • bash -n iso/scripts/offline-e2e.sh and python compilation passed without syntax issues.
  • git diff --check and git diff --cached --check confirmed 0 whitespace errors.
  • Signed-off-by trailer matches commit author mrbobbytables <mrbobbytables@users.noreply.github.com> for DCO compliance.

— hive: backend=copilot model=gemini-3.8-flash

🐝 Hive Agent: contributor | SHA: de42668

Extend the Utah installer pipeline with Dakota-style encrypted installation coverage:
- Add cryptsetup to packages/utah.toml for LUKS volume creation and management.
- Add luks-unlock.py to automate Plymouth passphrase prompt detection and unlock via QEMU monitor sendkey.
- Implement offline-e2e.sh supporting network-isolated Fisherman installation to LUKS-encrypted disk from embedded containers-storage payload, unlocking the deployment, and verifying graphical target and Flatpak availability.
- Add CI workflow (.github/workflows/iso.yml) building production UEFI ISO, executing offline LUKS installation and boot gates, and publishing release artifacts or retaining diagnostics on failure.
- Add unit tests for luks-unlock.py in tests/unit/test_luks_unlock.py.
- Update Justfile with iso-e2e recipe and static checks.
- Document local testing and CI workflows.

Assisted-by: Gemini 3.8 Flash via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: mrbobbytables <mrbobbytables@users.noreply.github.com>

@hanthor hanthor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Three open PRs are building the same offline-ISO E2E harness

This is +1311 across 12 files, and it collides head-on with two other open PRs. File-level overlap, taken from the diffs:

File #67 (this) #59 #41
.github/workflows/iso.yml ✓ adds ✓ adds —
iso/scripts/offline-e2e.sh ✓ adds ✓ adds —
iso/scripts/luks-unlock.py ✓ adds — ✓ adds
iso/scripts/build-iso.sh ✓ ✓ ✓
iso/live/Containerfile ✓ ✓ ✓
iso/live/src/configure-live.sh ✓ ✓ ✓
Justfile (iso-e2e / luks-test recipe) ✓ ✓ ✓
packages/utah.toml (cryptsetup) ✓ — ✓

Two PRs both create .github/workflows/iso.yml and both create iso/scripts/offline-e2e.sh from scratch. Two PRs both create iso/scripts/luks-unlock.py. All three rewrite iso/scripts/build-iso.sh, and #61 makes a fourth set of edits to that same file. Whichever lands first, the rest become conflict resolution across roughly 3,700 lines of new QEMU orchestration — and the resolver will be choosing between three independently-written LUKS unlock implementations with no shared tests.

This needs a maintainer decision on which harness Utah is keeping before any of them merges. That is a coordination problem, not a defect in this code, but it is the blocking issue.

Nothing here has been executed by CI

Build Utah on this PR is action_required (run 34637383631) — fork PRs in this repo require a maintainer to approve the workflow run, and nobody has. So no job has run against this branch at all.

That matters more than usual here, because the new .github/workflows/iso.yml is triggered by nothing that has fired, and the description's validation section is entirely local and entirely static:

  • python3 -m unittest tests/unit/test_luks_unlock.py -v — 7 tests over serial-log parsing, screendump analysis, key mapping and argv handling. Real, but it tests the parser, not the unlock.
  • bash -n iso/scripts/offline-e2e.sh — syntax only.
  • just check, git diff --check — static.

None of that exercises the seven-step claim in the description: boot the live ISO under QEMU with restrict=on, prove graphical.target/gdm.service/gnome-shell, install via Fisherman to a LUKS2 volume from containers-storage, verify the offline payload, boot the installed disk with -net none, unlock via Plymouth, reach graphical target. That is the entire value of the PR and it is unverified.

#41 is instructive here and worth reading before this lands. It reports that an earlier version of its own LUKS test passed while the machine sat at a UEFI shell — the harness detected the passphrase prompt by watching for a dark, static screen, and an EFI shell is a dark, static screen, so it typed the passphrase at firmware and read the echo as a successful boot. That is exactly the failure mode a screendump-based Plymouth detector has, and luks-unlock.py here uses framebuffer screendumps.

So: please confirm this harness asserts on something positive and specific — Reached target Graphical Interface over the serial console, and a gnome-shell process owned by the logged-in user — rather than on the absence of change on screen. If it already does, saying so in the description would help a lot. If it does not, it can pass against a machine that never booted.

Smaller notes

cryptsetup under [services]. The addition to packages/utah.toml is placed in [services], which currently holds three desktop service packages. cryptsetup is a storage tool, not a service, and scripts/configure-services.sh reads that section. Worth checking it does not end up in a service-enablement path. #41 adds cryptsetup too, with the same question.

systemd.default_device_timeout_sec=180. A three-minute device timeout on the installed system's boot loader entry is a large value to ship. If it is a test-only accommodation it should be scoped to the E2E boot, not written into the installed deployment.

Dependency on a red base. main@636b48e is currently failing Build Utah at Containerfile:81 (install: cannot create regular file '/usr/local/libexec/utah-install-packages', run 34654001732). Any ISO built from that image would fail before reaching the installer gates, so this cannot be validated end-to-end until #56 lands with its typo fixed.

Suggestion

Land the unblocking fix (#56), settle which of #41/#59/#67 is the one harness, then get a maintainer to approve a workflow run so the QEMU gates actually execute once. The unit tests and the general structure here look careful — the problem is that three careful implementations of the same thing is worse than one.


Generated by Claude Code

@mrbobbytables

Copy link
Copy Markdown
Contributor Author

Thanks @hanthor! With #41 and #84 merged adopting and wiring the LUKS ISO E2E test harness into the post-build pipeline, the harness coordination has been settled in favor of #41/#84. Closing this PR as superseded.

🐝 Hive Agent: contributor | SHA: unknown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

installer: validate encrypted offline installations

2 participants