From 8c409d323bc6d7510d2d350455841774fdc0b8f6 Mon Sep 17 00:00:00 2001 From: veilor-org Date: Tue, 5 May 2026 15:05:59 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20STRATEGY.md=20=E2=80=94=20hybrid=20kick?= =?UTF-8?q?start=20bootstrap=20+=20bootc=20OCI=20on=20secureblue?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Locks in the strategic decision from 2026-05-05 secureblue research agent: pivot the technical base toward bootc/OCI, but as a layer over secureblue's `securecore-kinoite-hardened-userns` rather than a Containerfile-from-scratch. ## What changed - New: `docs/STRATEGY.md` — full hybrid plan (kickstart bootstrap → first-boot bootc rebase → bootc-only at v1.0). Documents secureblue rationale, our overrides (drop Trivalent, restore sudo + Xwayland), next concrete steps for v0.7 spike (BlueBuild recipe + GH Actions workflow + `veilor-firstboot-rebase` one-shot). - Updated: `docs/ROADMAP.md` v0.7 bootc-spike subsection — supersedes the Agent 3 Containerfile-from-scratch plan with the BlueBuild layering plan. Spike compresses 1 week → 2 days; hardening review inherited from 30 secureblue contributors. ## Why hybrid, not pure pivot - Anaconda's LUKS UX (single passphrase prompt + custom partitioning) is mature; bootc-image-builder's installer is not yet on par. Keep the kickstart as the bootstrap. - bootc upgrade gets us atomic A/B + signed image chain + instant rollback that we can't realistically build alone with our contributor count. - The kickstart work is not lost — it becomes the day-zero installer through v0.7. v1.0 deprecates it entirely once bootc-image-builder installer ISO matures. ## Why secureblue, not Athena (Arch) | Axis | secureblue | Athena OS | |---|---|---| | Maintainers | 30 | 8 | | MAC enforcing OOB | SELinux + custom policy | AppArmor active, profiles mostly unconfined | | Atomic / immutable updates | Yes (bootc/rpm-ostree) | No (rolling) | | Threat model published | No | Yes | | MS-signed Secure Boot shim | Yes (Fedora shim) | Yes (with auto-MOK) | Athena's only structural advantage is the published threat model. We're already drafting one (Agent 5 of 2026-05-05 wave) — we get that win regardless. secureblue's contributor count + atomic update infrastructure is the leverage. ## Strategic credibility win Publishing `docs/THREAT-MODEL.md` BEFORE the v0.7 launch positions veilor-os ahead of secureblue (no threat model) and Athena (has threat model but smaller contributor base) on the one axis that matters most. ## Open questions documented in STRATEGY.md - secureblue contribution acceptance for upstream patches (USBGuard id-based-rules fix, threat model framework) - Brave vs Mullvad-Browser pick for default browser - bootc rebase first-boot fallback if rebase fails - Fedora 44 transition timing follows secureblue's release tags --- docs/ROADMAP.md | 47 ++++++++++++---- docs/STRATEGY.md | 137 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 174 insertions(+), 10 deletions(-) create mode 100644 docs/STRATEGY.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 571c475..23fa559 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -223,17 +223,44 @@ public, benchmarks come after. After threat model, not before. 5. **Press kit** — wallpapers, logo, screenshots, feature one-liner. -### bootc-image-builder spike (PROMOTED from v1.0+) +### Hybrid bootc spike — layer on secureblue (REVISED 2026-05-05) -The v0.5.27–31 grind cost us hours on anaconda + RPM-6.0 + -`--cmdline` mode brittleness: three install failures, kernel-cmdline -written to four different places before one worked, transaction-progress -patches that masked real bugs. **bootc-image-builder builds a -`Containerfile` once and gets a bootable image** — no anaconda, no -kickstart, no `%post --nochroot` vs `%post`, no -`CollectKernelArgumentsTask`. A v0.7 spike (NOT v1.0) evaluates whether -the next major rev should rebase on it. Spike outcome determines -whether `veilor-atomic` (stretch goal) becomes the mainline. +The original v0.7 entry called for a Containerfile-from-scratch +spike on `quay.io/fedora/fedora-bootc:43`. Research on 2026-05-05 +(see `docs/STRATEGY.md` and +`docs/research/2026-05-05-agent-wave/`) found a faster path: +**layer veilor's branding + threat model + UX on top of +secureblue's already-shipping `securecore-kinoite-hardened-userns` +OCI image** via a BlueBuild recipe. + +Reasoning: + +- secureblue has 30 active contributors, 940 stars, 56 commits + in the last 5 weeks. They've already implemented the hardening + surface we'd need to build alone (sysctl + kargs + SELinux + custom policy + USBGuard + hardened-malloc + Unbound DoT + + cosign-signed OCI build pipeline). +- Containerfile-from-scratch spike: 1 week to first ISO. + BlueBuild recipe extending secureblue: ~2 days, ~200 lines + YAML. The hardening review is inherited. +- secureblue does NOT publish a threat model. Athena OS does + (their main differentiator, only public threat model in + hardened-Linux 2026). Our `docs/THREAT-MODEL.md` (drafted) gets + us ahead of both on the one axis that matters most for a + security-branded distro. + +Hybrid path locked: kickstart ISO stays as the **bootstrap +installer** (Anaconda's LUKS UX is mature). On first boot, a +one-shot `veilor-firstboot-rebase` service runs `bootc rebase +ghcr.io/veilor/veilor-os:43`. From then on, `bootc upgrade` is +the update channel. v1.0 deprecates the kickstart entirely. + +Overrides we apply over secureblue: replace Trivalent (their +single-maintainer browser fork) with Brave or Mullvad-Browser; +keep sudo (revert `run0`-only); re-enable Xwayland. + +Full plan: `docs/STRATEGY.md`. Spike will land in +`bluebuild/recipe.yml` plus `.github/workflows/build-bluebuild.yml`. --- diff --git a/docs/STRATEGY.md b/docs/STRATEGY.md new file mode 100644 index 0000000..b40455c --- /dev/null +++ b/docs/STRATEGY.md @@ -0,0 +1,137 @@ +# veilor-os Strategy — Hybrid kickstart bootstrap + bootc OCI + +Decision date: **2026-05-05** +Locked at: **v0.5.31 → v0.7 spike → v1.0** + +## TL;DR + +- Keep the Anaconda-driven kickstart ISO as the **bootstrap installer** + (LUKS UX is mature, single passphrase prompt, custom partitioning + works). +- On first boot, the installed system is automatically rebased to a + **veilor-os OCI image** built via BlueBuild on top of secureblue's + `securecore-kinoite-hardened-userns`. +- All future updates flow through `bootc upgrade` — atomic A/B, + instant rollback, cosign-signed. +- The kickstart-driven mutable-root path is deprecated at v1.0; kept + alive as fallback through v0.7. + +## Why hybrid, not pure pivot + +Pure pivot to bootc-from-scratch (Agent 3's spike plan) was **1 week +to first ISO**. Pure pivot to layering on secureblue is **2 days to +first ISO** because the hardening work is already done. But both +require throwing away the partitioning UX we already have working in +Anaconda. + +Hybrid: +- **Day-zero install:** Anaconda kickstart + custom partitioning + + LUKS prompt (what we have today). User experience = unchanged. +- **First boot, post-LUKS-unlock:** `bootc rebase + ghcr.io/veilor/veilor-os:43` runs once; pulls the OCI image; next + reboot lands in the veilor OCI tree. +- **Day-2:** `bootc upgrade` cadence for everything from then on. + +We keep what works, pivot the part that doesn't. + +## Why secureblue underneath + +| Question | Answer | +|---|---| +| Maintainers | secureblue: 30 contributors, 56 commits/5wks. veilor-os: solo. | +| Hardening surface | secureblue ships sysctl + kargs + SELinux + USBGuard + hardened-malloc + DoT — far more than we'd build alone. | +| Build pipeline | BlueBuild → cosign-signed OCI in GH Actions (`build-all.yml`, `trivy.yml`). | +| Update model | bootc upgrade with A/B + instant rollback + signed image chain. | +| Variants | `kinoite-hardened-userns` is the KDE+Wayland+SELinux variant we'd want. | +| License | Apache-2.0 (compatible with our MIT). | + +What we override in our recipe: + +- **Browser**: Trivalent (their fork) → Brave / Mullvad-Browser. + Single-maintainer browser fork is unacceptable risk for daily-driver + audience. +- **`run0` instead of sudo**: revert. Breaks too many workflows. +- **Xwayland disabled**: revert. Some apps still need it. +- **veilor branding**: theme, KDE color scheme, Plymouth, SDDM, font, + os-release. All `overlay/*` ports verbatim from current repo. + +## Strategic credibility win + +secureblue does NOT publish a threat model. Athena OS does, and it's +their main differentiator. We've already drafted +`docs/THREAT-MODEL.md` (Agent 5 of 2026-05-05 wave). Publishing that +*before* the v0.7 launch positions veilor-os ahead of secureblue and +Athena on the one axis that matters most for a security-branded +distro: **honest, scoped, public threat model**. + +## Roadmap implications + +| Version | Status | Path | +|---|---|---| +| v0.5.31 | shipped | Anaconda kickstart, mutable root | +| v0.5.32 | active — top blockers from 9-agent wave | Anaconda kickstart | +| v0.5.x → v0.6 | maintenance | Anaconda kickstart, ergonomics + UX polish | +| **v0.7 spike** | **2-day BlueBuild prototype** | First veilor OCI image extending secureblue-kinoite-hardened | +| v0.7 ship | ISO bootstraps install, first boot rebases to OCI | Hybrid path live | +| **v1.0** | **bootc-only**, kickstart deprecated | `bootc upgrade` for all updates | + +The `bootc-image-builder` spike plan (Agent 3) is **superseded** by +this hybrid: don't build a Containerfile from scratch on +`fedora-bootc:43`. Instead, write a BlueBuild recipe on +`securecore-kinoite-hardened-userns`. Spike compresses 1 week → 2 days. + +## Next concrete steps + +### v0.5.32 — current (no strategy change) + +Ship the 7 blockers from `docs/research/2026-05-05-agent-wave/`: +suspend/resume wifi fix, firstboot WantedBy, USBGuard id-rules, +firewalld tailscale0 zone, KMS modeset, /etc/skel branding, virtio-9p +log capture. + +### v0.7-spike (2 days) + +1. New repo dir: `bluebuild/recipe.yml`. +2. `from`: `ghcr.io/secureblue/securecore-kinoite-hardened-userns:latest`. +3. Override modules: + - `type: files` — stamp our `overlay/*` tree (branding, themes, + veilor scripts, sddm theme, plymouth theme). + - `type: rpm-ostree` — install Brave + restore Xwayland. + - `type: rpm-ostree` — remove Trivalent. + - `type: brand` — PRETTY_NAME, GRUB_DISTRIBUTOR, distributor URL. +4. `.github/workflows/build-bluebuild.yml` — pull BlueBuild action, + build + cosign sign + push to GHCR. +5. `kickstart/install.ks` — add a one-shot `veilor-firstboot-rebase` + service that runs `rpm-ostree rebase ghcr.io/veilor/veilor-os:43` + then disables itself. User reboots once and is on the OCI image. + +### v1.0 — bootc-only + +- Drop `kickstart/veilor-os.ks`, drop `livecd-creator` workflow. +- Keep `installer-iso.toml` for the bootstrap ISO (built via + bootc-image-builder); the OCI image is the source of truth. +- `veilor-update` becomes thin `bootc upgrade --apply` wrapper. + +## Open questions + +- Does secureblue accept upstream contributions? If yes, send our + USBGuard id-based-rules fix and our threat model framework. +- Brave vs Mullvad-Browser: Brave has telemetry concerns out of box; + Mullvad-Browser is Tor-Browser-derived but not designed for + daily-driver. Test both in spike. +- Recovery flow when bootc rebase fails on first boot — need fallback + to keep the kickstart-installed system bootable. Likely already + handled by bootc's A/B; verify in spike. +- Fedora 44 transition: secureblue tracks Fedora releases (current + `v4.9` on F44). If we follow, we get F44 for free at the same time + upstream does. + +## See also + +- `docs/THREAT-MODEL.md` — drafted, needs publish for v0.7 +- `docs/ROADMAP.md` — to be updated to reflect this strategy +- `docs/research/2026-05-05-agent-wave/03-bootc-spike-plan.md` — + superseded by this hybrid (kept as reference for the + Containerfile-from-scratch alternative) +- secureblue: +- BlueBuild: