Compare commits

..

8 commits

Author SHA1 Message Date
fb4dcc5683 docs: record the 2026-09-22 harness, security and polish session
Some checks are pending
ci / test (push) Waiting to run
Update the changelog, status matrix, handoff and VM boot verification with
the 23/23 graphical journey, the hardened harness, the confirmed fixes and
the remaining blocked/unverified gates (full GUI install past AI, rollback,
installed desktop, physical second-computer OpenCode transport).
2026-09-21 20:01:58 -07:00
613e383082 fix(gui): focus the welcome action and refuse silent mid-install exit
The tiled welcome window was not keyboard-focused, so the primary action
had no focus ring and Return did nothing; request activation and force
focus. Refuse Escape during the destructive phase and say the operation
cannot be cancelled. Show the AI connection guidance beside the controls.
Guard the fixes with live_iso tests.
2026-09-21 20:01:58 -07:00
cc23df69de test(vm): enforce harness disk safety and structured results
Validate every writable drive (qcow2, inside PHOEBUS_VM_DISKS, no /dev/*,
block/char devices, raw images, escaping symlinks or outside backing
chains), give each run its own OVMF variable file, QMP socket and state
directory, and use QMP plus argument arrays instead of shell interpolation.
Return nonzero on any failed assertion, timeout, EOF or missing result and
record PASS/FAIL/BLOCKED/SKIPPED/NOT RUN. Add 16 unit tests, a report
generator and a findings register; make test runs the harness suite.
2026-09-21 20:01:50 -07:00
3d43f8c6c8 feat(executor): add an OpenCode server capability probe
OpenCode is an agent application, not an OpenAI-compatible endpoint. Add
a typed probe over /global/health and /config/providers that distinguishes
disconnected, authentication required, incompatible, reachable-no-model and
ready, and never returns provider credentials. Expose it as
phoebus-installer --opencode-probe. Document the four components, host and
tunnelled remote workflows, and the Phoebus assistant boundary (ADR 0011).
2026-09-21 20:01:44 -07:00
0a6725b049 fix(core): refuse symlink escapes in the target root
Reject a symlinked path component while writing beneath TargetRoot
instead of following it, so a planted symlink cannot redirect an
installer write to the host. Cover escaping directories and leaves.
2026-09-21 20:01:38 -07:00
9b5c1155b0 fix(ai): validate provider endpoints and bound the transport
Accept only http(s) endpoints and refuse URLs that could inject curl
config directives. Restrict the transfer to http,https, keep redirects
disabled (so a header cannot follow one to another origin) and bound the
response with max-filesize. Add endpoint and transport regression tests.
2026-09-21 20:01:38 -07:00
d395fd3464 fix(installer): make GUI bridge approvals single-use and bounded
Consume the approval before destructive work and refuse a second
start_install from a retry, a second frontend or a reconnect. Bound
request lines and secret values; reject deeply nested JSON. Add
regression tests for replay, oversized input and nesting.
2026-09-21 20:01:38 -07:00
5ae166e827 fix(executor): revalidate the target disk before partitioning
probe_disks parsed lsblk human-readable sizes as bytes, so every disk
reported 0 B and the size-based identity check was blind; pass -b.

Re-probe the selected disk immediately before the destructive stage and
refuse if it disappeared, became protected (mounted/read-only/live) or
changed size/model since the review. Add regression tests for each case.
2026-09-21 20:01:32 -07:00
28 changed files with 3149 additions and 407 deletions

View file

@ -8,14 +8,15 @@
SHELL := /bin/bash
.PHONY: help context doctor test test-rust fmt fmt-check clippy check build static vm hooks commit publish backup forgejo-init public private protect release clean
.PHONY: help context doctor test test-rust test-vm fmt fmt-check clippy check build static vm hooks commit publish backup forgejo-init public private protect release clean
help:
@printf 'Phoebus OS targets:\n'
@printf ' make context session briefing (state, roadmap, handoff)\n'
@printf ' make doctor check host prerequisites\n'
@printf ' make test run the Rust test suite\n'
@printf ' make test run the Rust and VM-harness test suites\n'
@printf ' make test-rust cargo test --workspace\n'
@printf ' make test-vm python3 installer/tests/vm/test_vmsafety.py\n'
@printf ' make fmt cargo fmt --all\n'
@printf ' make check fmt-check + clippy + tests\n'
@printf ' make build release Rust installer\n'
@ -35,11 +36,14 @@ context:
doctor:
scripts/doctor.sh
test: test-rust
test: test-rust test-vm
test-rust:
cd installer-rs && cargo test --workspace
test-vm:
python3 installer/tests/vm/test_vmsafety.py
fmt:
cd installer-rs && cargo fmt --all

View file

@ -7,6 +7,65 @@ Format: Keep a Changelog. Dates are UTC.
## Unreleased
### Added
- **OpenCode connection workflow and capability probe.** New ADR 0011 and
`docs/OPENCODE.md` separate the four components (client, server, model
service, Phoebus broker) and document host-local and tunnelled remote use.
`phoebus-executor::opencode_server` probes `/global/health` and
`/config/providers` and reports a typed state (`disconnected`,
`authentication_required`, `incompatible`, `reachable_no_model`, `ready`)
instead of assuming a TCP connect or HTTP 200 means compatibility. Exposed as
`phoebus-installer --opencode-probe <url>` (read-only, nonzero unless a model
is available). Never returns provider credentials. Verified against the
installed `opencode 1.18.32` (ready) and a deliberate unauthenticated LAN bind
(`authentication_required`).
### Security
- **The target disk is revalidated immediately before partitioning.** An
approval now binds to a verified device, not a name: `storage_prepare` re-probes
and refuses if the disk disappeared, became protected (mounted/read-only/live),
or changed size/model since it was selected. Regression tests cover each case.
- **The GUI bridge refuses replayed and overlapping installs.** An approval is
single-use and consumed before destructive work; a second `start_install`, a
retry or a reconnected frontend cannot start a second installation. Request
lines and secret values are length-bounded; deeply nested JSON is rejected.
- **Provider transport hardened.** Only `http(s)` endpoints are accepted, URLs
with characters that could inject curl config directives are refused, the
transfer is restricted to `http,https`, redirects stay disabled (so an
`Authorization` header cannot follow a redirect to another origin), and the
response is size-bounded (`max-filesize`).
- **`TargetRoot` refuses symlink escapes.** `write`/`ensure_dir` reject a
symlinked path component inside the target instead of following it, so a
planted symlink cannot redirect an installer write to the host.
- **Unauthenticated OpenCode endpoints are not treated as usable.** The probe
reports `authentication_required` for a passwordless LAN bind rather than
`ready`.
### Fixed
- **Disk sizes are no longer reported as `0 B`.** `probe_disks` invoked `lsblk`
without `-b`, so human-readable sizes (`30G`) failed the byte parse and every
disk displayed `0 B`; the size-based disk-identity check was also blind. The
`-b` flag is now used and pinned by a test.
- **The welcome window's primary action is keyboard-reachable.** It now requests
activation and force-focuses "Install Phoebus OS", so Return launches the
installer (previously no focus ring was shown and Return did nothing). A
regression test also rejects the non-existent `FloatingWindow.onActiveChanged`.
- **The installer cannot be abandoned mid-install without explanation.** Escape
during the destructive phase is refused and the UI states that the operation
cannot be cancelled safely; the AI step shows its "connect and validate"
guidance inline, beside the controls.
### Changed
- **The VM harness enforces its own safety rules and reports structured
results.** `installer/tests/vm/vmsafety.py` validates every writable drive
(qcow2, inside `PHOEBUS_VM_DISKS`, no `/dev/*`, block/char devices, raw
images, escaping symlinks or outside backing chains), gives each run its own
OVMF variable file and QMP socket, uses structured QMP and argument arrays
(no `os.system`), and returns nonzero on any failed assertion, timeout, EOF or
missing result. Statuses are `PASS`/`FAIL`/`BLOCKED`/`SKIPPED`/`NOT RUN`.
`make test` now runs the harness unit tests; `installer/tests/vm/report.py`
builds a browsable run report.
### Added
- **Graphical installation experience.** The live ISO now boots into a branded
Phoebus welcome window (`phoebus-welcome`) that makes "Install Phoebus OS" the

View file

@ -3,53 +3,70 @@
Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail.
- **Last updated:** this session (2026-09-21), graphical installer ISO.
- **Current focus:** The ISO now boots into a branded **welcome window** and a
full **graphical installer wizard** over a typed JSON bridge
(`phoebus-installer --gui-bridge`), with the TUI/CLI as fallback. The brand
system, boot-menu identity, live-medium detection and the recovery-boot
default bug are fixed. See ADR 0010 and `docs/VM-BOOT-VERIFICATION.md`.
- **Last updated:** this session (2026-09-22), harness + security + polish.
- **Current focus:** Hardened the VM harness (enforced qcow2/`/dev`/backing-chain
safety, structured PASS/FAIL results, per-run OVMF+QMP, no `os.system`),
fixed confirmed security defects (disk revalidation before partitioning,
bridge replay/concurrency + input bounds, provider transport URL/size
hardening, `TargetRoot` symlink escapes, and the `0 B` disk-size probe bug),
added an OpenCode server capability probe + docs/ADR 0011, and fixed the
welcome focus ring and the untruthful mid-install cancellation.
- **Last verified (this session):**
- `gui-driver.py gui`: welcome autostarts; DMS first-run dialogs suppressed;
installer opens; duplicate sessions prevented (`n1=n2=1`); keyboard
navigation reaches network + AI steps; the AI step blocks without a model.
- `gui-driver.py install` + `boot` on the built ISO: `INSTALL-RC=0`,
`NO_SECRET_LEAK`, and a **detached** boot with systemd `running`,
**0 failed units**, LUKS2, all Btrfs subvolumes and network, and the boot
menu defaulting to **Gentoo Linux** (not recovery).
- Rust suite: GUI bridge dry-run protocol, approval binding/invalidation,
secret non-disclosure, brand tokens/contrast, boot default pinning.
- `gui-driver.py gui` on the rebuilt ISO: **23/23 PASS**, exit 0. Welcome
autostarts; Return launches the installer (focus fixed); duplicate sessions
prevented; live medium protected; keyboard navigation reaches network + AI;
advancing without a model is refused and starts nothing.
- `make test` green (Rust + 16 harness unit tests); `cargo fmt --check`,
`cargo clippy --workspace --all-targets` (no errors), release + static
builds.
- OpenCode probe: `ready` against `opencode 1.18.32`; `authentication_required`
(exit 1) against an unauthenticated LAN bind.
- ISO: `installer/live/phoebus-installer-amd64.iso` 1.6 GiB,
`sha256 2a52178c4b4a71bbc5c011b89533988ceb9aa95493160cb93c4335f03d9a1eee`.
`sha256 428dbd7547db8690596bf5c3a0d7a6fa8aee4c9f9eca1e926c216712dd050b36`;
static binary `sha256 2f9cd4b36a12e469d2b6187166acaf8b11f7f382cc19f7ad08bb2a809c855591`.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order)
1. **Live AI provider call**: exercise the GUI AI step (and `sys ask`) with a
real 0600 key or a downloaded local model; the path is fixture-verified only.
1. **Complete the graphical install with a real model**: download a small local
OpenAI-compatible model (or supply a 0600 provider key), then run
`gui-driver.py gui` through disk/account/review/ERASE/install/rebooot twice
on fresh qcow2 disks and record the passing journeys. The current automated
journey passes to the AI gate only.
2. **Installed Mango desktop**: install the default profile in a graphical VM
and verify the panel/launcher/terminal/audio/network/lock/idle, the dwl
fallback, and the welcome/installer absence on the installed system.
3. **Rollback VM acceptance**: deliberately break an update, run `sys undo`,
reboot detached, verify `/var/db/pkg` matches `/`, then boot the recovery
entry with no network or model (ADR 0007).
4. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
4. **Narrow the live broker privilege**: replace the live-only
`NOPASSWD: ALL` rule for the GUI bridge with the smallest practical
command-scoped rule once a safe sudoers form is verified (ADR 0011 context).
5. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
`phoebus-menu`, `phoebus-lock`, `phoebus-idle`, kitty, XWayland, the polkit
agent, logout/reap and reboot (`docs/DEVELOPMENT.md`).
5. **Release gates on a CI runner**: `phoebus-release gates --execute` and
6. **Release gates on a CI runner**: `phoebus-release gates --execute` and
`publish` once a runner exists; no gate has executed.
## Known blockers / risks
- No live DeepSeek/OpenAI call has been made (no key in this environment); the
AI step is verified as a blocked prerequisite and with a fixture transport.
- No live DeepSeek/OpenAI key and no local model are available; the **full GUI
install past the AI step** and two fresh-disk graphical installs are NOT
verified (normal installation requires a connected model). The AI step is
verified as a blocked prerequisite and with a fixture transport.
- **Installed** Mango (GURU + compiled Quickshell/DMS) is not VM-verified; nor
is the dwl fallback session.
- Rollback and the AI sandbox are implemented and unit-tested but not
VM-verified. NVIDIA is not verified.
- A **separate physical computer** for the OpenCode transport test is not
available (BLOCKED); a forwarded-hop + unauthenticated-LAN-refusal host-local
test was done instead.
- The GUI bridge reaches Quickshell via `Process` + `/usr/bin/sudo -n`; it
relies on the live user's passwordless sudo.
relies on the live user's passwordless sudo. The live sudoers rule is still
`NOPASSWD: ALL` (live-only); narrowing the broker permission is future work.
- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git):
`results.json`, `screenshot-manifest.json`, `report.html`, screenshots.
## Environment notes

136
docs/OPENCODE.md Normal file
View file

@ -0,0 +1,136 @@
# OpenCode connection workflow
OpenCode is used in two clearly separated ways:
1. **Developer workflow** — on this repository, inspecting sanitized evidence.
Full tool access (shell, files, plugins) is fine because it runs as *you*,
on *your* machine, against *your* checkout.
2. **Phoebus assistant connection** — approved, bounded system facts and
validated typed proposals. It must never inherit the developer tool
permissions and never receives secrets.
Read [ADR 0011](adr/0011-opencode-connection-boundary.md) first.
## Four components, not one
| Component | What it is | Where it runs |
|-----------|------------|---------------|
| OpenCode client | `opencode` TUI/CLI, or `opencode attach <url>` | your machine |
| OpenCode server | `opencode serve` — an HTTP/JSON **agent** API, not a model API | usually the same machine as the client or the model |
| Model inference service | DeepSeek/OpenAI, or a local OpenAI-compatible server (Ollama, llama.cpp, ...) | provider cloud or your LAN |
| Phoebus installer/broker | the typed, privileged, local executor | the target machine only |
**An OpenCode server URL does not go in Phoebus's local-model endpoint field.**
An OpenCode server is an agent application; it is not an OpenAI-compatible
`/v1/chat/completions` endpoint. Pointing Phoebus's `local` provider at it will
fail, and would be the wrong trust boundary even if it parsed.
## Capability probe (never assume compatibility)
```sh
phoebus-installer --opencode-probe http://127.0.0.1:4096
```
It is read-only and prints a typed state, exiting nonzero unless a model is
available:
| State | Meaning |
|-------|---------|
| `disconnected` | TCP connect failed; the service is down |
| `authentication_required` | the server answered 401/403; supply the password/tunnel |
| `incompatible` | a health response arrived but the API shape is not the expected one |
| `reachable_no_model` | healthy server, no model configured |
| `ready` | reachable, healthy, API-compatible, and ≥1 model configured |
`ready` still does **not** prove the model can emit a valid Phoebus proposal;
that requires a real prompt round-trip and proposal parse. A health check or an
HTTP 200 is not that proof.
The probe reads `/global/health` and `/config/providers`, keeps only counts from
the latter, and never returns the provider credentials that upstream includes in
that response.
## A. OpenCode on the development/VM host
```sh
# 1. Set a provider credential through the environment (never a file in git).
export DEEPSEEK_API_KEY="$(cat ~/.config/phoebus/deepseek.key)" # 0600 file
# 2. Start the server on loopback only. Upstream warns when it is unsecured.
opencode serve --hostname 127.0.0.1 --port 4096
# 3. In another terminal, attach a client to it.
opencode attach http://127.0.0.1:4096
```
Keep the server on `127.0.0.1`. Do not pass `--mdns` and do not bind `0.0.0.0`
without authentication: the server's configuration API can expose provider
credentials.
## B. OpenCode on a separate user-controlled computer
Run the server on that computer, bound to **loopback**, and reach it through an
authenticated encrypted tunnel. SSH port-forwarding is the simplest approved
transport:
```sh
# On the remote computer:
opencode serve --hostname 127.0.0.1 --port 4096
# From your machine (tunnel local 127.0.0.1:4096 -> remote loopback:4096):
ssh -N -L 127.0.0.1:4096:127.0.0.1:4096 you@remote.example
# Then, locally:
opencode attach http://127.0.0.1:4096
phoebus-installer --opencode-probe http://127.0.0.1:4096
```
The probe now sees a loopback endpoint and the tunnel supplies transport
authentication and encryption. If you cannot use a tunnel, set
`OPENCODE_SERVER_PASSWORD` and terminate TLS in front of the server; never
expose an unauthenticated plaintext service.
### VM networking is not one thing
Inside a VM these are different endpoints and must not be confused:
| Endpoint | Meaning |
|----------|---------|
| `guest 127.0.0.1` | the guest's own loopback |
| `host 127.0.0.1` | the host's loopback (invisible to the guest) |
| `10.0.2.2` | the QEMU user-net gateway to the host |
| `192.168.x.y` | a real LAN address, reachable by other machines |
## C. Phoebus assistant boundary
When a Phoebus assistant uses OpenCode:
- Run the service unprivileged, with restricted filesystem access.
- Disable tools you do not need. OpenCode permission settings are *not* an
operating-system security boundary; enforce isolation outside the prompt.
- Keep the destructive execution path in Phoebus's local broker with local human
approval. The agent is never given a shell, root, credentials or private-file
access.
- Keep credentials in protected runtime storage (0600, outside model context).
Never forward disk passphrases or account passwords to OpenCode.
- Changing the model or connection invalidates any approval whose meaning
depends on it; a reconnect must never replay an installation command.
## Developer workflow note
For work on this repository, the developer OpenCode session may use full tools,
but only against a checkout and against **sanitized** test evidence. Do not feed
it VM disks, serial transcripts with credentials, `*.pw` files, or the
`PHOEBUS_OPENCODE_*` runtime inputs.
## Verified evidence
- `phoebus-installer --opencode-probe http://127.0.0.1:41999` against the
installed `opencode 1.18.32` returned `ready` (3 providers, 27 models).
- The same probe through a forwarded second loopback endpoint returned `ready`.
- A server deliberately bound to a LAN address **without** authentication
returned `authentication_required` and exit status 1: the probe refuses to
treat an unauthenticated service as usable.
- Physical second-computer verification is **BLOCKED** in this environment (no
second machine / no passwordless SSH); the forwarded-hop test is labelled as a
host-local transport test, not a second computer.

View file

@ -93,6 +93,13 @@ still not VM-verified.
| greetd login (Mango default, dwl fallback) | yes | yes | no | no |
| Live desktop ISO (Mango + DMS) | yes | guards tested | graphical VM + GUI journey + detached boot | no |
| Live welcome autostart + duplicate prevention | yes | guards tested | live graphical VM | no |
| Welcome primary action keyboard-focus | yes | guards tested | live graphical VM | no |
| VM harness disk safety + structured results | yes | yes (16 tests) | n/a | n/a |
| Target disk revalidation before partition | yes | yes | no | n/a |
| Bridge replay/concurrency + input bounds | yes | yes | no | n/a |
| Provider transport endpoint/size hardening | yes | yes | no | n/a |
| `TargetRoot` symlink-escape guard | yes | yes | n/a | n/a |
| OpenCode server capability probe | yes | yes | real host probe (`ready`) | n/a |
| GURU packaging (scoped keywords) | yes | yes | no (build/install unverified) | no |
| Release gates + atomic publish | yes | yes | no | n/a |
| `sys` verbs | yes | yes | yes | no |
@ -130,18 +137,21 @@ still not VM-verified.
- **The live desktop ISO** (`installer/live/build.sh`) builds a Debian testing
rootfs with Mango + DMS, live-only autologin, a branded welcome window and a
graphical installer frontend over the typed bridge. Its desktop-payload
guards are unit-tested, and the built ISO
(`sha256 2a52178c…`, 1.6 GiB) was booted in a graphical, seat-providing VM:
the welcome window opened automatically, the installer launched (a second
launch created no duplicate), keyboard navigation reached the network and AI
steps, and advancing without a connected model was refused. The same ISO was
then installed non-interactively (`INSTALL-RC=0`, `NO_SECRET_LEAK`) and
booted **with the ISO detached** (systemd running, 0 failed units, LUKS2,
all Btrfs subvolumes, network). A live AI provider call was **not** possible
(no key in this environment); the AI step is verified as a blocked
prerequisite and with a fixture transport in unit tests. The **installed**
Mango system (GURU + compiled Quickshell/DMS) and the dwl fallback in a VM
are not yet verified.
guards are unit-tested. The rebuilt ISO
(`sha256 428dbd75…`, 1.6 GiB, build id in `/etc/phoebus/build`) was booted in
a graphical, seat-providing VM and the automated `gui` journey passed
**23/23** checks: the welcome window opened automatically, "Install Phoebus
OS" launched the installer from the keyboard, a second launch created no
duplicate, the live medium was reported protected, keyboard navigation
reached the network and AI steps, and advancing without a connected model was
refused. An earlier appliance build of the same code path was installed
non-interactively (`INSTALL-RC=0`, `NO_SECRET_LEAK`) and booted **with the
ISO detached** (systemd running, 0 failed units, LUKS2, all Btrfs subvolumes,
network). A live AI provider call was **not** possible (no key and no local
model in this environment), so the **full graphical install past the AI step**
is not claimed; the AI step is verified as a blocked prerequisite and with a
fixture transport in unit tests. The **installed** Mango system (GURU +
compiled Quickshell/DMS) and the dwl fallback in a VM are not yet verified.
- **AI sandbox** is implemented (`systemd-run` hardening properties, tested at
the argv level) and fails closed without `systemd-run`; it has not been
exercised in a VM. Only typed actions and the privacy boundary were previously

66
docs/VERIFICATION.md Normal file
View file

@ -0,0 +1,66 @@
# Verification and findings register
Companion to `docs/STATUS.md`. The machine-readable per-run results live outside
git under `/var/tmp/phoebus-vm/<run-id>/results.json`; this file is the
human-readable register of what was found, fixed and still unverified.
## Run matrix (this session, 2026-09-22)
```json
{
"source_revision": "7e9fa9c",
"iso_sha256": "428dbd7547db8690596bf5c3a0d7a6fa8aee4c9f9eca1e926c216712dd050b36",
"static_binary_sha256": "2f9cd4b36a12e469d2b6187166acaf8b11f7f382cc19f7ad08bb2a809c855591",
"runs": [
{"scenario": "gui", "result": "PASS 23/23", "exit_code": 0,
"artifacts": "/var/tmp/phoebus-vm/gui-gui-20260922T025537Z-69f754cf"},
{"scenario": "make test (rust + vmsafety)", "result": "PASS", "exit_code": 0},
{"scenario": "cargo fmt --check", "result": "PASS", "exit_code": 0},
{"scenario": "cargo clippy --workspace --all-targets", "result": "PASS (warnings only)", "exit_code": 0},
{"scenario": "opencode probe (live 1.18.32)", "result": "ready", "exit_code": 0},
{"scenario": "opencode probe (unauth LAN bind)", "result": "authentication_required", "exit_code": 1},
{"scenario": "noninteractive install + detached boot", "result": "NOT RUN on the final ISO", "exit_code": null},
{"scenario": "full graphical install past AI", "result": "BLOCKED", "exit_code": null},
{"scenario": "rollback VM acceptance", "result": "NOT RUN", "exit_code": null},
{"scenario": "AI sandbox canary VM test", "result": "NOT RUN", "exit_code": null},
{"scenario": "second physical computer OpenCode transport", "result": "BLOCKED", "exit_code": null}
]
}
```
## Confirmed defects fixed
| ID | Defect | Symptom | Fix | Regression test |
|----|--------|---------|-----|-----------------|
| D1 | Disk safety was not revalidated before destroying the target | A disk that disappeared, was mounted, became the live medium, or was replaced under the same name between selection and install would be partitioned on the strength of a stale review | `Installer::revalidate_target_disk` re-probes and compares identity in `storage_prepare` | `orchestrate::tests::{revalidation_refuses_a_disappeared_disk,revalidation_refuses_a_now_protected_disk,revalidation_refuses_reused_device_name_with_a_new_size,...}` |
| D2 | `probe_disks` parsed human-readable `lsblk` sizes as bytes | Every disk displayed `0 B`; the size-identity check was blind | pass `-b` to `lsblk` | `probe::tests::probe_disks_classifies_optical_as_protected` asserts the byte size |
| D3 | The bridge could replay or overlap a destructive install | A second `start_install` (retry, second frontend, reconnect) could re-run storage preparation | approval is single-use, consumed before work; `installing`/`installed` guards | `start_install_cannot_be_replayed_after_success` |
| D4 | The welcome's primary action was not keyboard-focused | No focus ring; Return did not open the installer | request activation + `forceActiveFocus()`; regression test also rejects the invalid `onActiveChanged` signal | `welcome_primary_action_is_keyboard_reachable` |
| D5 | Escape during installation silently closed the frontend | A destructive operation could be abandoned with no explanation | Escape is refused during progress and the UI says so | `progress_cannot_be_abandoned_silently` |
| D6 | Provider transport accepted unsafe URL schemes / unbounded responses / followed no protocol allowlist | A config-supplied endpoint could target `file:`, inject curl config, or return a huge body | `validate_endpoint`, `proto = "=http,https"`, `max-filesize`, redirects disabled | `endpoint_validation_rejects_unsafe_schemes_and_injection`, `curl_transport_refuses_an_unsafe_endpoint`, `curl_transport_bounds_the_response_and_disables_redirects` |
| D7 | `TargetRoot` followed symlinks out of the target | A planted symlink could redirect an installer write to the host | `reject_symlink_components` in `write`/`ensure_dir` | `target::tests::{refuses_to_write_through_an_escaping_symlink,refuses_a_symlinked_leaf}` |
| D8 | The VM harness documented disk safety but did not enforce it, and reported observations rather than results | A mistyped `DISK` could point at a real device; a timeout could look like success; shell interpolation in screenshot conversion | `vmsafety.py`; per-run OVMF/QMP; structured results; argument arrays | `test_vmsafety.py` (16 tests), run by `make test` |
## Suspected risks (reproduced or bounded)
- **Prompt injection in device labels / model output.** Typed proposals pass
`deny_unknown_fields` and a closed action set; device labels are display-only.
Bounded by tests (`phoebus-ai` parse/allowlist). No VM canary run.
- **Live sudoers is `NOPASSWD: ALL` (live-only).** It does not reach the
installed system, but the GUI bridge uses it. Narrowing is a recorded follow-up.
- **OpenCode `/config/providers` returns provider credentials in cleartext.**
Upstream behaviour; the probe keeps only counts and docs mandate loopback +
tunnel. Not a Phoebus defect, but a deployment hazard.
## Missing verification (blocked / not run)
- Full graphical installation past the AI step and two fresh-disk graphical
installs: **BLOCKED** — no provider key and no local model; normal install
requires a connected model.
- `install`/`boot` modes on the final ISO: **NOT RUN** (the earlier appliance
build passed `INSTALL-RC=0` + detached boot; the final ISO's binary changed,
so this is not automatically re-verified).
- Rollback acceptance, AI sandbox canary, installed Mango/dwl, physical seat,
NVIDIA: **NOT RUN / unverified**.
- Second physical computer OpenCode transport: **BLOCKED**; host-local forwarded
hop and unauthenticated-LAN refusal were tested instead.

View file

@ -552,6 +552,43 @@ the kernel's `sort-key`, and the specification's final filename tie-break
pinning `loader.conf` to the newest real kernel entry and giving the recovery
entry `sort-key zzzz-phoebus-recovery`; unit tests pin both.
## 2026-09-22 — automated graphical journey (gui-driver) and hardened harness
The graphical live ISO was rebuilt and driven automatically by
`installer/tests/vm/gui-driver.py gui` in a graphical, seat-providing
QEMU/OVMF VM with a disposable qcow2 disk directory and a per-run OVMF variable
file.
- Source revision: `7e9fa9c` plus uncommitted work; build id recorded in
`/etc/phoebus/build` (`7e9fa9c+dirty…`).
- Static installer: `sha256 2f9cd4b3…` (4,716,544 bytes, static-pie).
- ISO: `installer/live/phoebus-installer-amd64.iso`,
`sha256 428dbd75…`, 1.6 GiB, built with
`PHOEBUS_REUSE_ROOTFS=1` (Mango 0.17.2 + DankMaterialShell 1.6.2).
- Result: **23/23 checks PASS**, exit status 0
(`/var/tmp/phoebus-vm/gui-gui-20260922T025537Z-69f754cf/`).
Asserted: welcome autostart; live/branding payload markers from command
output (not the echoed command); the live medium protected; "Install Phoebus
OS" launched the installer from a Return keypress; duplicate sessions
prevented (`n1=n2=1`); the frontend reported no bridge errors; keyboard
navigation reached the network and AI steps; advancing without a connected
model was refused and started no installation.
- Screenshots at every page (welcome focus, language, network, AI model, AI
blocked, final state) plus a `screenshot-manifest.json`; `report.py` builds a
browsable `report.html`. All artifacts stay under `/var/tmp/phoebus-vm/`
(outside git).
Harness safety verified in the same work: the drivers reject `/dev/*`, block
and character devices, raw images, symlinks escaping the disposable directory,
and outside backing chains, with a nonzero exit (`make test-vm`, 16 unit
tests). Screenshots use structured QMP and argument arrays; there is no shell
interpolation.
A host-local OpenCode transport test also ran: `phoebus-installer
--opencode-probe` returned `ready` against `opencode 1.18.32` through a
forwarded second loopback endpoint, and `authentication_required` (exit 1)
against a deliberately unauthenticated LAN bind.
## Known remaining work
- The graphical session was verified with the **headless** wlroots backend
@ -565,3 +602,13 @@ entry `sort-key zzzz-phoebus-recovery`; unit tests pin both.
- Desktop USE still does not match the signed binhost, so the desktop
transaction compiles a large amount from source (~26 minutes for the desktop
package set on 8 vCPUs in the test VM).
- **The full graphical install past the AI step is NOT verified.** No live
provider key and no downloadable local model were available in this
environment, and normal installation requires a connected model by design;
the automated journey stops at (and verifies) the blocked AI prerequisite.
Two fresh-disk graphical installations from the final candidate remain
unrun. The deterministic noninteractive install + detached boot remains the
proven boot path.
- **A separate physical computer for the OpenCode transport test is NOT
available**; that check is BLOCKED. The forwarded-hop and
unauthenticated-LAN-refusal tests are host-local.

View file

@ -0,0 +1,66 @@
# ADR 0011: OpenCode connection boundary
- **Status:** Accepted
- **Date:** 2026-09-22
## Context
The assignment requires a working OpenCode connection on the development/VM host
and from a separate user-controlled computer, while keeping the model untrusted
and the destructive broker local. OpenCode is an **agent application**, not an
OpenAI-compatible inference endpoint. Upstream's `opencode serve` exposes an
HTTP/JSON API (`/global/health`, `/session`, `/config/providers`, ...) with
optional basic authentication; `opencode attach` and `opencode run --attach`
connect a client to it.
Two facts shape the decision:
1. A successful TCP connect, a health check or an HTTP 200 does **not** prove
that a usable model is configured, nor that the model can emit a valid
Phoebus proposal. The skill set must distinguish those states explicitly.
2. The installed server, with no `OPENCODE_SERVER_PASSWORD`, binds loopback and
warns that it is unsecured. Its `/config/providers` response includes the
provider credentials in cleartext. Exposing that service to a LAN would leak
those credentials and hand an agent's tool surface to the network.
## Decision
1. **Four components are named separately** and may live on different machines:
the OpenCode *client*, the OpenCode *server*, the *model inference service*,
and the Phoebus *installer/broker*. An OpenCode server URL is never placed in
Phoebus's local-model endpoint field.
2. **Connection states are typed and honest.** `phoebus-executor::opencode_server`
probes `/global/health` and `/config/providers` and reports one of
`Disconnected`, `AuthenticationRequired`, `ReachableNoModel`,
`Incompatible`, or `Ready`. `Ready` means reachable, healthy, API-compatible
and holding at least one model; it still does not prove a valid proposal
round-trip. The probe keeps only counts from `/config/providers`, never the
credentials it may contain.
3. **Remote access is loopback plus an authenticated encrypted tunnel** (SSH
port-forward, WireGuard, or equivalent). The probe accepts plain `http://`
only, because a direct TLS-less LAN bind is not an approved transport.
4. **The OpenCode agent never inherits Phoebus privilege.** Its tools, shell,
file and plugin access are outside Phoebus's execution path. Destructive
product actions still go through the local typed broker and local human
approval. The OpenCode configuration is written mode 0600 and carries no
credentials.
5. **The installer's AI step keeps using its own bounded transport.** OpenCode
is an optional operator workflow, not a replacement for the typed proposal
transport; a future adapter must perform a real prompt round-trip and parse a
versioned proposal before it may claim compatibility.
## Consequences
- Remote OpenCode is not a one-click feature: the operator runs a tunnel. This
is deliberate; the alternative is an unauthenticated credential-leaking agent
endpoint on the LAN.
- The capability probe is testable against fake HTTP servers and against a real
`opencode serve` (env-gated `PHOEBUS_OPENCODE_PROBE`), so compatibility is
verified rather than assumed.
- Developer use (this repository) and assistant use (approved bounded facts and
typed proposals) remain clearly separated by tools and permissions.
## Status
Accepted. The probe and its tests are implemented; end-to-end installation does
not depend on OpenCode.

View file

@ -15,5 +15,7 @@ and link it here.
| [0007](0007-coherent-rollback.md) | Coherent rollback and recovery | Accepted |
| [0008](0008-nix-isolation-lifecycle.md) | Nix lifecycle, build isolation, and packaging | Accepted |
| [0009](0009-mango-dankmaterialshell-desktop.md) | Mango + DankMaterialShell desktop option | Accepted |
| [0010](0010-graphical-installer-frontend.md) | Graphical installer frontend and typed bridge | Accepted |
| [0011](0011-opencode-connection-boundary.md) | OpenCode connection boundary | Accepted |
Format: Context / Decision / Consequences / Status.

View file

@ -183,6 +183,41 @@ impl SystemFacts {
}
}
/// Maximum accepted provider response size (16 MiB). A larger response is
/// treated as hostile and refused rather than buffered.
pub const MAX_RESPONSE_BYTES: u64 = 16 * 1024 * 1024;
/// Validate a provider endpoint before it is handed to the transport.
///
/// Only `http(s)` is allowed, and the URL may not contain whitespace, control
/// characters, quotes or backslashes: the transport embeds it in a curl config
/// file, so those characters could otherwise inject curl directives. Local and
/// LAN endpoints remain valid (that is the point of the explicit endpoint), but
/// unsafe schemes such as `file:`, `gopher:` or `scp:` are refused.
pub fn validate_endpoint(url: &str) -> Result<(), AiError> {
let trimmed = url.trim();
if trimmed.is_empty() {
return Err(AiError::ProviderUnavailable(
"no provider endpoint configured".into(),
));
}
let lower = trimmed.to_ascii_lowercase();
if !(lower.starts_with("http://") || lower.starts_with("https://")) {
return Err(AiError::Provider(format!(
"refusing non-http(s) endpoint scheme: {trimmed}"
)));
}
if trimmed
.chars()
.any(|c| c.is_whitespace() || c.is_control() || c == '"' || c == '\\')
{
return Err(AiError::Provider(
"endpoint contains a character that is unsafe in a transport config".into(),
));
}
Ok(())
}
/// The instructions given to the model. They are deliberately explicit about
/// the closed action set and the evidence requirement.
pub const SYSTEM_PROMPT: &str = "\
@ -357,11 +392,7 @@ pub fn complete_proposal_at(
"no AI provider selected".into(),
));
}
if endpoint.trim().is_empty() {
return Err(AiError::ProviderUnavailable(
"no provider endpoint configured".into(),
));
}
validate_endpoint(endpoint)?;
facts.validate_no_forbidden()?;
let request = build_request(provider, model, facts);
let body = serde_json::to_string(&request)?;
@ -488,6 +519,18 @@ mod tests {
assert!(complete_proposal_at(ProviderKind::Local, "", "", &facts(), &transport).is_err());
}
#[test]
fn endpoint_validation_rejects_unsafe_schemes_and_injection() {
assert!(validate_endpoint("https://api.deepseek.com/chat/completions").is_ok());
assert!(validate_endpoint("http://192.168.1.10:11434/v1/chat/completions").is_ok());
assert!(validate_endpoint("http://127.0.0.1:8080/v1/chat/completions").is_ok());
assert!(validate_endpoint("file:///etc/shadow").is_err());
assert!(validate_endpoint("scp://host/path").is_err());
assert!(validate_endpoint("https://x/v1\"\nheader = \"A: b").is_err());
assert!(validate_endpoint("https://x/v1 with space").is_err());
assert!(validate_endpoint("").is_err());
}
#[test]
fn request_has_no_secret_and_pins_the_schema() {
let request = build_request(ProviderKind::DeepSeek, "", &facts());

View file

@ -68,7 +68,34 @@ impl TargetRoot {
self.resolve(&format!("home/{relative}"))
}
/// Refuse to traverse a symlink while writing beneath the target root.
///
/// A freshly installed target is created by the installer, but a stage3
/// archive (or a later, less careful writer) could leave a symlink whose
/// target lies outside the root. Following it would write to the host. The
/// write path therefore rejects symlinked components instead of resolving
/// them.
fn reject_symlink_components(&self, relative: &str) -> Result<()> {
let rel = Path::new(relative.trim_start_matches('/'));
let mut current = self.root.clone();
for component in rel.components() {
if let Component::Normal(part) = component {
current.push(part);
if let Ok(meta) = std::fs::symlink_metadata(&current) {
if meta.file_type().is_symlink() {
return Err(CoreError::Validation(format!(
"refusing to write through a symlink inside the target: {}",
current.display()
)));
}
}
}
}
Ok(())
}
pub fn ensure_dir(&self, relative: &str) -> Result<PathBuf> {
self.reject_symlink_components(relative)?;
let path = self.resolve(relative)?;
std::fs::create_dir_all(&path).map_err(|e| CoreError::io(path.clone(), e))?;
Ok(path)
@ -84,6 +111,7 @@ impl TargetRoot {
}
pub fn write(&self, relative: &str, contents: impl AsRef<[u8]>) -> Result<PathBuf> {
self.reject_symlink_components(relative)?;
let path = self.resolve(relative)?;
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).map_err(|e| CoreError::io(parent.to_path_buf(), e))?;
@ -140,4 +168,39 @@ mod tests {
assert!(p.starts_with(dir.path()));
assert_eq!(t.read_to_string("etc/fstab").unwrap(), "hello");
}
#[test]
fn refuses_to_write_through_an_escaping_symlink() {
let dir = tempfile::tempdir().unwrap();
let outside = tempfile::tempdir().unwrap();
let t = TargetRoot::new(dir.path());
std::os::unix::fs::symlink(outside.path(), dir.path().join("evil")).unwrap();
let err = t.write("evil/pwned", "owned").unwrap_err();
assert!(
matches!(err, CoreError::Validation(_)),
"expected a validation refusal, got {err:?}"
);
assert!(
!outside.path().join("pwned").exists(),
"the write escaped the target root"
);
// ensure_dir must refuse too.
assert!(t.ensure_dir("evil/subdir").is_err());
}
#[test]
fn refuses_a_symlinked_leaf() {
let dir = tempfile::tempdir().unwrap();
let outside = tempfile::tempdir().unwrap();
std::fs::write(outside.path().join("target"), "original").unwrap();
let t = TargetRoot::new(dir.path());
std::fs::create_dir_all(dir.path().join("etc")).unwrap();
std::os::unix::fs::symlink(outside.path().join("target"), dir.path().join("etc/passwd"))
.unwrap();
assert!(t.write("etc/passwd", "overwritten").is_err());
assert_eq!(
std::fs::read_to_string(outside.path().join("target")).unwrap(),
"original"
);
}
}

View file

@ -77,6 +77,9 @@ impl ModelTransport for CurlTransport<'_> {
url: &str,
body: &str,
) -> std::result::Result<String, AiError> {
// Fail closed on an unsafe scheme or a URL that could inject curl
// config directives before anything is written.
phoebus_ai::provider::validate_endpoint(url)?;
if self.sandboxed {
return self.send_sandboxed(url, body);
}
@ -96,13 +99,20 @@ impl ModelTransport for CurlTransport<'_> {
Some(key) => format!("header = \"Authorization: Bearer {}\"\n", key.expose()),
None => String::new(),
};
// `proto` restricts the transfer to http(s); `location` is deliberately
// absent so a redirect is never followed (a redirect could send the
// Authorization header to another origin). `max-filesize` bounds the
// response so a hostile or broken endpoint cannot exhaust memory.
let config = format!(
"url = \"{url}\"\n\
proto = \"=http,https\"\n\
header = \"Content-Type: application/json\"\n\
{auth}\
data = \"@{path}\"\n\
silent\nshow-error\nfail-with-body\nmax-time = 120\n",
path = request.path().display()
silent\nshow-error\nfail-with-body\nmax-time = 120\n\
connect-timeout = 30\nmax-filesize = {max}\n",
path = request.path().display(),
max = phoebus_ai::provider::MAX_RESPONSE_BYTES,
);
let spec = CommandSpec::new("ai", "query model", "curl")
.args(["-sS", "-K", "-"])
@ -127,10 +137,13 @@ impl CurlTransport<'_> {
let escaped = body.replace('\\', "\\\\").replace('"', "\\\"");
let config = format!(
"url = \"{url}\"\n\
proto = \"=http,https\"\n\
header = \"Content-Type: application/json\"\n\
{auth}\
data = \"{escaped}\"\n\
silent\nshow-error\nfail-with-body\nmax-time = 120\n"
silent\nshow-error\nfail-with-body\nmax-time = 120\n\
connect-timeout = 30\nmax-filesize = {max}\n",
max = phoebus_ai::provider::MAX_RESPONSE_BYTES,
);
let out = crate::sandbox::run(
self.exec,
@ -207,6 +220,62 @@ mod tests {
assert_eq!(exec.redactor().redact("sk-secret-value"), "<redacted>");
}
#[test]
fn curl_transport_refuses_an_unsafe_endpoint() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let transport = CurlTransport::new(&exec, None);
for bad in [
"file:///etc/passwd",
"gopher://127.0.0.1:70/",
"http://example.invalid/v1\"; header = \"X: y",
"https://example.invalid/v1\nheader = \"X: y\"",
] {
let err = transport
.send(ProviderKind::Local, bad, "{}")
.expect_err("unsafe endpoint must be refused");
assert!(
matches!(err, AiError::Provider(_)),
"unexpected error for {bad}: {err:?}"
);
}
assert!(
runner.recorded().is_empty(),
"curl must not run for a refused URL"
);
}
#[test]
fn curl_transport_bounds_the_response_and_disables_redirects() {
let runner = RecordingRunner::new();
runner.set_response(
"curl",
CommandOutput {
status: 0,
success: true,
stdout: b"{}".to_vec(),
stderr: Vec::new(),
duration: Duration::from_millis(1),
},
);
let exec = make_exec(runner.clone());
let transport = CurlTransport::new(&exec, None);
transport
.send(
ProviderKind::Local,
"http://127.0.0.1:11434/v1/chat/completions",
"{}",
)
.unwrap();
let stdin = String::from_utf8(runner.recorded()[0].stdin.clone().unwrap()).unwrap();
assert!(stdin.contains("max-filesize"), "{stdin}");
assert!(stdin.contains("proto = \"=http,https\""), "{stdin}");
assert!(
!stdin.contains("location"),
"redirects must stay disabled: {stdin}"
);
}
#[test]
fn curl_transport_omits_auth_without_a_key() {
let runner = RecordingRunner::new();

View file

@ -18,6 +18,7 @@ pub mod kernel;
pub mod log;
pub mod nix;
pub mod opencode;
pub mod opencode_server;
pub mod portage;
pub mod probe;
pub mod rollback;

View file

@ -0,0 +1,490 @@
//! OpenCode **server** capability probe.
//!
//! OpenCode is an agent application, not an OpenAI-compatible inference
//! endpoint. A successful TCP connect, a health check or an HTTP 200 is not
//! proof that a model is configured or that it can produce a valid Phoebus
//! proposal. This module makes those distinctions explicit so a caller can
//! report an honest connection state instead of assuming compatibility.
//!
//! It talks to the OpenCode HTTP API documented at <https://opencode.ai/docs/server/>
//! using a deliberately tiny HTTP/1.1 client (no TLS, no redirects, no
//! credentials in the URL). Remote access is expected through an authenticated,
//! encrypted tunnel to a loopback-bound server, never by exposing the server
//! directly.
//!
//! The probe never returns provider credentials: upstream's `/config/providers`
//! response includes them, so only counts are kept.
use std::io::{Read, Write};
use std::net::{SocketAddr, TcpStream, ToSocketAddrs};
use std::time::Duration;
use serde::{Deserialize, Serialize};
/// A parsed `http://host:port` server endpoint.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Endpoint {
pub host: String,
pub port: u16,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum EndpointError {
Empty,
NotHttp,
BadHost,
BadPort,
}
impl std::fmt::Display for EndpointError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let text = match self {
EndpointError::Empty => "empty endpoint",
EndpointError::NotHttp => "only http:// endpoints are accepted",
EndpointError::BadHost => "the host is missing or contains an unsafe character",
EndpointError::BadPort => "the port is missing or invalid",
};
f.write_str(text)
}
}
impl Endpoint {
/// Parse `http://host:port`. Plain HTTP only: remote access is over an
/// authenticated tunnel, not a direct TLS-less LAN bind.
pub fn parse(value: &str) -> Result<Self, EndpointError> {
let text = value.trim();
if text.is_empty() {
return Err(EndpointError::Empty);
}
let rest = text.strip_prefix("http://").ok_or(EndpointError::NotHttp)?;
// Reject userinfo, paths and control characters.
if rest.is_empty()
|| rest.contains('/')
|| rest.contains('@')
|| rest.contains('"')
|| rest.contains('\\')
|| rest.chars().any(|c| c.is_whitespace() || c.is_control())
{
return Err(EndpointError::BadHost);
}
let (host, port) = rest.rsplit_once(':').ok_or(EndpointError::BadPort)?;
if host.is_empty() {
return Err(EndpointError::BadHost);
}
let port: u16 = port.parse().map_err(|_| EndpointError::BadPort)?;
Ok(Endpoint {
host: host.to_string(),
port,
})
}
pub fn base(&self) -> String {
format!("http://{}:{}", self.host, self.port)
}
fn socket_addrs(&self) -> std::io::Result<Vec<SocketAddr>> {
(self.host.as_str(), self.port)
.to_socket_addrs()
.map(|it| it.collect())
}
}
/// The connection state a frontend should display. `Ready` means the server is
/// reachable, authenticated, API-compatible *and* has at least one model; it
/// still does not prove the model can emit a valid proposal (that needs a real
/// prompt round-trip).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ConnectionState {
Disconnected,
AuthenticationRequired,
ReachableNoModel,
Incompatible,
Ready,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Capability {
pub state: ConnectionState,
pub tcp_reachable: bool,
pub healthy: bool,
pub server_version: Option<String>,
pub provider_count: usize,
pub model_count: usize,
pub detail: String,
}
impl Capability {
fn disconnected(detail: impl Into<String>) -> Self {
Self {
state: ConnectionState::Disconnected,
tcp_reachable: false,
healthy: false,
server_version: None,
provider_count: 0,
model_count: 0,
detail: detail.into(),
}
}
}
#[derive(Debug, Deserialize)]
struct Health {
#[serde(default)]
healthy: bool,
#[serde(default)]
version: Option<String>,
}
#[derive(Debug, Deserialize)]
struct Providers {
#[serde(default)]
providers: Vec<Provider>,
}
#[derive(Debug, Deserialize)]
struct Provider {
#[serde(default)]
models: std::collections::BTreeMap<String, serde_json::Value>,
}
/// Probe an OpenCode server and classify the connection.
pub fn probe(endpoint: &Endpoint, timeout: Duration) -> Capability {
let addrs = match endpoint.socket_addrs() {
Ok(addrs) if !addrs.is_empty() => addrs,
Ok(_) => return Capability::disconnected("host did not resolve"),
Err(e) => return Capability::disconnected(format!("resolve failed: {e}")),
};
// A failed TCP connect is the only way to be certain the service is down.
if TcpStream::connect_timeout(&addrs[0], timeout).is_err() {
return Capability::disconnected("connect failed");
}
// Each request uses its own short-lived connection (Connection: close),
// which is what the health/config endpoints expect and keeps the client
// simple and redirect-free.
let timeout = timeout;
let request = |path: &str| -> std::io::Result<(u16, String)> {
let mut stream = TcpStream::connect_timeout(&addrs[0], timeout)?;
let _ = stream.set_read_timeout(Some(timeout));
let _ = stream.set_write_timeout(Some(timeout));
get(&mut stream, &endpoint.host, path)
};
// Health first: it is the API-compatibility signal.
let (status, body) = match request("/global/health") {
Ok(pair) => pair,
Err(e) => {
return Capability {
state: ConnectionState::Incompatible,
tcp_reachable: true,
healthy: false,
server_version: None,
provider_count: 0,
model_count: 0,
detail: format!("health request failed: {e}"),
}
}
};
if status == 401 || status == 403 {
return Capability {
state: ConnectionState::AuthenticationRequired,
tcp_reachable: true,
healthy: false,
server_version: None,
provider_count: 0,
model_count: 0,
detail: format!("server requires authentication (HTTP {status})"),
};
}
if status != 200 {
return Capability {
state: ConnectionState::Incompatible,
tcp_reachable: true,
healthy: false,
server_version: None,
provider_count: 0,
model_count: 0,
detail: format!("/global/health returned HTTP {status}"),
};
}
let health: Health = match serde_json::from_str(&body) {
Ok(h) => h,
Err(_) => {
return Capability {
state: ConnectionState::Incompatible,
tcp_reachable: true,
healthy: false,
server_version: None,
provider_count: 0,
model_count: 0,
detail: "/global/health was not the expected JSON".into(),
}
}
};
if !health.healthy {
return Capability {
state: ConnectionState::Incompatible,
tcp_reachable: true,
healthy: false,
server_version: health.version,
provider_count: 0,
model_count: 0,
detail: "server reported unhealthy".into(),
};
}
// Providers: authentication and model availability.
let (pstatus, pbody) = request("/config/providers").unwrap_or((0, String::new()));
if pstatus == 401 || pstatus == 403 {
return Capability {
state: ConnectionState::AuthenticationRequired,
tcp_reachable: true,
healthy: true,
server_version: health.version,
provider_count: 0,
model_count: 0,
detail: format!("provider list requires authentication (HTTP {pstatus})"),
};
}
let providers: Option<Providers> = serde_json::from_str(&pbody).ok();
let (provider_count, model_count) = match providers {
Some(p) => (
p.providers.iter().filter(|p| !p.models.is_empty()).count(),
p.providers.iter().map(|p| p.models.len()).sum(),
),
None => (0, 0),
};
let state = if model_count == 0 {
ConnectionState::ReachableNoModel
} else {
ConnectionState::Ready
};
Capability {
state,
tcp_reachable: true,
healthy: true,
server_version: health.version,
provider_count,
model_count,
detail: if model_count == 0 {
"server is healthy but no model is configured".into()
} else {
format!("{provider_count} provider(s), {model_count} model(s)")
},
}
}
/// Minimal HTTP/1.1 GET with connection close. Never follows redirects.
fn get(stream: &mut TcpStream, host: &str, path: &str) -> std::io::Result<(u16, String)> {
let request = format!(
"GET {path} HTTP/1.1\r\nHost: {host}\r\nAccept: application/json\r\nConnection: close\r\n\r\n"
);
stream.write_all(request.as_bytes())?;
stream.flush()?;
let mut raw = Vec::new();
stream.read_to_end(&mut raw)?;
let text = String::from_utf8_lossy(&raw).into_owned();
let Some(header_end) = text.find("\r\n\r\n") else {
return Err(std::io::Error::new(
std::io::ErrorKind::InvalidData,
"no HTTP header terminator",
));
};
let headers = &text[..header_end];
let body = &text[header_end + 4..];
let status = headers
.lines()
.next()
.and_then(|line| line.split_whitespace().nth(1))
.and_then(|code| code.parse::<u16>().ok())
.ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidData, "no status line"))?;
let chunked = headers
.to_ascii_lowercase()
.contains("transfer-encoding: chunked");
let body = if chunked {
decode_chunked(body).unwrap_or_else(|| body.to_string())
} else {
body.to_string()
};
Ok((status, body))
}
/// Decode an HTTP chunked body. Best-effort; returns `None` on malformed input.
fn decode_chunked(body: &str) -> Option<String> {
let mut out = String::new();
let mut rest = body;
loop {
let line_end = rest.find("\r\n")?;
let size_text = rest[..line_end].split(';').next()?.trim();
let size = usize::from_str_radix(size_text, 16).ok()?;
rest = &rest[line_end + 2..];
if size == 0 {
return Some(out);
}
if rest.len() < size {
return None;
}
out.push_str(&rest[..size]);
rest = &rest[size..];
rest = rest.strip_prefix("\r\n").unwrap_or(rest);
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::Read as _;
use std::net::TcpListener;
use std::thread;
fn spawn_server(routes: Vec<(&'static str, u16, &'static str)>) -> Endpoint {
use std::collections::HashMap;
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let port = listener.local_addr().unwrap().port();
let routes: HashMap<&'static str, (u16, &'static str)> =
routes.into_iter().map(|(p, s, b)| (p, (s, b))).collect();
thread::spawn(move || {
for stream in listener.incoming() {
let Ok(mut stream) = stream else { continue };
let mut buf = [0u8; 2048];
let n = stream.read(&mut buf).unwrap_or(0);
if n == 0 {
// The reachability probe connects and closes without a
// request; ignore it.
continue;
}
let request = String::from_utf8_lossy(&buf[..n]);
let want = request
.lines()
.next()
.and_then(|l| l.split_whitespace().nth(1))
.unwrap_or("");
let (code, payload) = routes.get(want).copied().unwrap_or((404, "{}"));
let response = format!(
"HTTP/1.1 {code} X\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{payload}",
payload.len()
);
let _ = stream.write_all(response.as_bytes());
}
});
Endpoint {
host: "127.0.0.1".into(),
port,
}
}
#[test]
fn parses_and_rejects_endpoints() {
assert_eq!(
Endpoint::parse("http://127.0.0.1:4096").unwrap(),
Endpoint {
host: "127.0.0.1".into(),
port: 4096
}
);
assert_eq!(
Endpoint::parse("https://127.0.0.1:4096"),
Err(EndpointError::NotHttp)
);
assert_eq!(
Endpoint::parse("http://user@host:1"),
Err(EndpointError::BadHost)
);
assert_eq!(Endpoint::parse("http://host"), Err(EndpointError::BadPort));
assert!(Endpoint::parse("http://host:1/../../etc").is_err());
assert!(Endpoint::parse("").is_err());
}
#[test]
fn probe_reports_ready_with_models() {
let endpoint = spawn_server(vec![
(
"/global/health",
200,
r#"{"healthy":true,"version":"1.18.32"}"#,
),
(
"/config/providers",
200,
r#"{"providers":[{"id":"deepseek","models":{"m1":{},"m2":{}}},{"id":"empty","models":{}}]}"#,
),
]);
let capability = probe(&endpoint, Duration::from_secs(2));
assert_eq!(capability.state, ConnectionState::Ready);
assert_eq!(capability.server_version.as_deref(), Some("1.18.32"));
assert_eq!(capability.provider_count, 1);
assert_eq!(capability.model_count, 2);
}
#[test]
fn probe_reports_reachable_but_model_less() {
let endpoint = spawn_server(vec![
(
"/global/health",
200,
r#"{"healthy":true,"version":"1.18.32"}"#,
),
("/config/providers", 200, r#"{"providers":[]}"#),
]);
let capability = probe(&endpoint, Duration::from_secs(2));
assert_eq!(capability.state, ConnectionState::ReachableNoModel);
}
#[test]
fn probe_reports_authentication_required() {
let endpoint = spawn_server(vec![("/global/health", 401, r#"{"error":"unauthorized"}"#)]);
let capability = probe(&endpoint, Duration::from_secs(2));
assert_eq!(capability.state, ConnectionState::AuthenticationRequired);
assert!(capability.tcp_reachable);
}
#[test]
fn probe_reports_incompatible_api() {
let endpoint = spawn_server(vec![("/global/health", 404, "{}")]);
let capability = probe(&endpoint, Duration::from_secs(2));
assert_eq!(capability.state, ConnectionState::Incompatible);
}
#[test]
fn probe_reports_disconnected_for_a_closed_port() {
let endpoint = Endpoint {
host: "127.0.0.1".into(),
port: 1,
};
let capability = probe(&endpoint, Duration::from_millis(300));
assert_eq!(capability.state, ConnectionState::Disconnected);
assert!(!capability.tcp_reachable);
}
/// Live check against a real `opencode serve`, enabled explicitly:
/// `PHOEBUS_OPENCODE_PROBE=http://127.0.0.1:4096 cargo test probe_live`.
#[test]
fn probe_live_server_when_configured() {
let Ok(url) = std::env::var("PHOEBUS_OPENCODE_PROBE") else {
return;
};
let endpoint = Endpoint::parse(&url).expect("valid probe endpoint");
let capability = probe(&endpoint, Duration::from_secs(3));
eprintln!("live opencode capability: {capability:?}");
assert!(
capability.tcp_reachable,
"server was not reachable: {capability:?}"
);
}
#[test]
fn capability_serialisation_has_no_credential_fields() {
let capability = Capability {
state: ConnectionState::Ready,
tcp_reachable: true,
healthy: true,
server_version: Some("1.18.32".into()),
provider_count: 1,
model_count: 3,
detail: "1 provider(s), 3 model(s)".into(),
};
let json = serde_json::to_string(&capability).unwrap();
assert!(!json.to_lowercase().contains("key"));
assert!(!json.contains("sk-"));
}
}

View file

@ -347,10 +347,12 @@ fn live_source_disks(runner: &dyn ProcessRunner) -> Vec<String> {
}
pub fn probe_disks(runner: &dyn ProcessRunner) -> Vec<Disk> {
// `-b` is required: without it lsblk prints human units ("30G") and the
// byte parse below silently yields 0, so every disk would report 0 B.
let out = capture(
runner,
"lsblk",
&["-dn", "-P", "-o", "NAME,MODEL,SIZE,TRAN,RM,RO"],
&["-bdn", "-P", "-o", "NAME,MODEL,SIZE,TRAN,RM,RO"],
);
let mounts = read_mounts();
let live = live_source_disks(runner);
@ -480,6 +482,9 @@ mod tests {
assert!(sr.is_protected());
let vda = disks.iter().find(|d| d.path == "/dev/vda").unwrap();
assert!(!vda.is_protected());
// Regression: the byte size must survive parsing (lsblk needs -b).
assert_eq!(vda.size_bytes, 32_212_254_720);
assert_eq!(vda.size_human(), "30.0 GiB");
}
#[test]

View file

@ -30,6 +30,11 @@ use serde_json::{json, Value};
pub const PROTOCOL_VERSION: u32 = 1;
const MAX_LOG_TAIL: usize = 200;
/// Upper bound on one request line. The frontend sends small, typed requests;
/// anything larger is refused before parsing rather than buffered blindly.
const MAX_LINE_BYTES: usize = 256 * 1024;
/// Upper bound on a single secret value (passwords/passphrases/API keys).
const MAX_SECRET_BYTES: usize = 16 * 1024;
// ---------------------------------------------------------------------------
// Protocol types
@ -161,6 +166,11 @@ pub struct Bridge {
api_key: Option<SecretString>,
approved_digest: Option<String>,
phase: std::rc::Rc<std::cell::Cell<DiskPhase>>,
/// One destructive transaction at a time. An approval is single-use: it is
/// consumed when the install starts so a replay, a second frontend or a
/// reconnected client cannot start a second overlapping installation.
installing: bool,
installed: bool,
quit: bool,
}
@ -175,6 +185,8 @@ impl Bridge {
api_key: None,
approved_digest: None,
phase: std::rc::Rc::new(std::cell::Cell::new(DiskPhase::BeforeStorage)),
installing: false,
installed: false,
quit: false,
}
}
@ -189,6 +201,8 @@ impl Bridge {
api_key: None,
approved_digest: None,
phase: std::rc::Rc::new(std::cell::Cell::new(DiskPhase::BeforeStorage)),
installing: false,
installed: false,
quit: false,
}
}
@ -204,6 +218,15 @@ impl Bridge {
if line.is_empty() {
return Ok(());
}
if line.len() > MAX_LINE_BYTES {
return write_json(
out,
&json!({
"ok": false,
"error": format!("request too large ({} bytes)", line.len()),
}),
);
}
let request: Request = match serde_json::from_str(line) {
Ok(request) => request,
Err(e) => {
@ -399,6 +422,19 @@ impl Bridge {
.secrets
.as_ref()
.ok_or_else(|| "set_secrets requires a `secrets` object".to_string())?;
for value in [
&patch.luks,
&patch.user_password,
&patch.root_password,
&patch.ai_api_key,
]
.into_iter()
.flatten()
{
if value.len() > MAX_SECRET_BYTES {
return Err("secret value is too large".into());
}
}
if let Some(v) = &patch.luks {
let s = SecretString::new(v.clone());
self.installer.exec.register_secret(&s);
@ -497,6 +533,16 @@ impl Bridge {
request: &Request,
out: &mut dyn Write,
) -> Result<Value, String> {
if self.installing {
return Err("an installation is already in progress".into());
}
if self.installed {
return Err(
"this session has already installed Phoebus; start a new session to \
install again"
.into(),
);
}
// The plan may not have changed since the user approved it.
let current = self.plan_digest();
match (&self.approved_digest, &request.plan_digest) {
@ -553,6 +599,10 @@ impl Bridge {
phase: self.phase.clone(),
};
self.phase.set(DiskPhase::BeforeStorage);
// Consume the approval and mark the session busy before any destructive
// work: a replay or a second frontend can never reach storage_prepare.
self.approved_digest = None;
self.installing = true;
let outcome = self.installer.install_observed(
&auth,
self.luks.as_ref(),
@ -560,17 +610,21 @@ impl Bridge {
self.root_password.as_ref(),
&mut observer,
);
self.installing = false;
match outcome {
Ok(()) => Ok(json!({
"complete": true,
"dry_run": dry_run,
"log_path": self.installer.exec.log_path().display().to_string(),
"next_actions": [
"Remove the installation medium.",
"Restart the computer and boot Phoebus OS.",
],
})),
Ok(()) => {
self.installed = true;
Ok(json!({
"complete": true,
"dry_run": dry_run,
"log_path": self.installer.exec.log_path().display().to_string(),
"next_actions": [
"Remove the installation medium.",
"Restart the computer and boot Phoebus OS.",
],
}))
}
Err(e) => {
let message = self.installer.exec.redactor().redact(&e.to_string());
let (disk_changed, next_actions) = disk_change_report(self.phase.get());
@ -1150,4 +1204,75 @@ mod tests {
assert_eq!(response(&lines)["data"]["bye"], json!(true));
assert!(bridge.should_quit());
}
#[test]
fn start_install_cannot_be_replayed_after_success() {
let mut bridge = test_bridge();
set_valid_config(&mut bridge);
let (digest, _) = approve(&mut bridge);
let first = call(
&mut bridge,
&json!({
"id": 20, "op": "start_install", "erase": "ERASE",
"final_confirm": true, "plan_digest": digest
})
.to_string(),
);
assert_eq!(response(&first)["ok"], json!(true));
assert!(bridge.installed);
// A second frontend (or a retry) re-approves and tries again: refused.
let (digest2, _) = approve(&mut bridge);
let second = call(
&mut bridge,
&json!({
"id": 21, "op": "start_install", "erase": "ERASE",
"final_confirm": true, "plan_digest": digest2
})
.to_string(),
);
assert_eq!(response(&second)["ok"], json!(false));
assert!(
response(&second)["error"]
.as_str()
.unwrap()
.contains("already installed"),
"unexpected error: {}",
response(&second)["error"]
);
}
#[test]
fn oversized_request_line_is_refused() {
let mut bridge = test_bridge();
let huge = format!(
r#"{{"id":1,"op":"handshake","pad":"{}"}}"#,
"x".repeat(MAX_LINE_BYTES)
);
let lines = call(&mut bridge, &huge);
let resp = response(&lines);
assert_eq!(resp["ok"], json!(false));
assert!(resp["error"].as_str().unwrap().contains("too large"));
}
#[test]
fn oversized_secret_is_refused() {
let mut bridge = test_bridge();
let secret = "x".repeat(MAX_SECRET_BYTES + 1);
let lines = call(
&mut bridge,
&json!({ "id": 22, "op": "set_secrets", "secrets": { "luks": secret } }).to_string(),
);
assert_eq!(response(&lines)["ok"], json!(false));
}
#[test]
fn deeply_nested_json_is_rejected_without_panicking() {
let mut bridge = test_bridge();
let depth = 300;
let nested = format!("{}{}{}", "[".repeat(depth), "0", "]".repeat(depth));
let line = format!(r#"{{"id":23,"op":"handshake","config":{nested}}}"#);
let lines = call(&mut bridge, &line);
assert_eq!(response(&lines)["ok"], json!(false));
}
}

View file

@ -120,6 +120,12 @@ struct Cli {
/// (stdin/stdout). Not intended for direct interactive use.
#[arg(long, hide = true)]
gui_bridge: bool,
/// Probe a running OpenCode server (e.g. `http://127.0.0.1:4096`) and print
/// its capability as JSON. Read-only; exits nonzero unless a model is
/// available. Never prints provider credentials.
#[arg(long, value_name = "URL")]
opencode_probe: Option<String>,
}
struct TerminalConfirm;
@ -275,6 +281,19 @@ fn run() -> std::result::Result<ExitCode, Box<dyn std::error::Error>> {
return Ok(ExitCode::SUCCESS);
}
if let Some(url) = &cli.opencode_probe {
use phoebus_executor::opencode_server::{probe, ConnectionState, Endpoint};
let endpoint =
Endpoint::parse(url).map_err(|e| format!("invalid OpenCode endpoint `{url}`: {e}"))?;
let capability = probe(&endpoint, std::time::Duration::from_secs(5));
println!("{}", serde_json::to_string_pretty(&capability)?);
return Ok(if capability.state == ConnectionState::Ready {
ExitCode::SUCCESS
} else {
ExitCode::FAILURE
});
}
if let Some(name) = &cli.emit_asset {
return match phoebus_core::system::desktop_asset(name) {
Some(text) => {

View file

@ -242,6 +242,74 @@ impl Installer {
}
}
/// Re-check the selected target disk immediately before the destructive
/// stage. An approval binds to a verified plan, not to a device name: the
/// device may have disappeared, been mounted, become the live medium, or
/// been replaced under the same name since it was chosen. Refuse to
/// partition unless the disk is present, unprotected and the same device.
pub fn revalidate_target_disk(&self) -> Result<()> {
let disk_path = &self.config.storage.disk;
if disk_path.trim().is_empty() {
return Err(phoebus_executor::ExecError::operation(
"storage_prepare",
"revalidate target disk",
"no target disk is selected",
));
}
let fresh = probe::probe_disks(self.exec.runner.as_ref());
let observed = match fresh.iter().find(|d| &d.path == disk_path) {
Some(d) => d,
None => {
return Err(phoebus_executor::ExecError::operation(
"storage_prepare",
"revalidate target disk",
format!(
"target disk {disk_path} disappeared since it was selected; \
refusing to partition"
),
))
}
};
if let Some(reason) = observed.protection() {
return Err(phoebus_executor::ExecError::operation(
"storage_prepare",
"revalidate target disk",
format!("refusing target {disk_path}: {}", reason.describe()),
));
}
// Device-name reuse: if the same path now describes a different device
// (size or model changed), the earlier review no longer applies.
if let Some(expected) = self.disks.iter().find(|d| &d.path == disk_path) {
if expected.size_bytes != 0
&& observed.size_bytes != 0
&& expected.size_bytes != observed.size_bytes
{
return Err(phoebus_executor::ExecError::operation(
"storage_prepare",
"revalidate target disk",
format!(
"target disk {disk_path} changed size since it was selected \
({} -> {} bytes); refusing to partition",
expected.size_bytes, observed.size_bytes
),
));
}
if let (Some(before), Some(now)) = (&expected.model, &observed.model) {
if before != now {
return Err(phoebus_executor::ExecError::operation(
"storage_prepare",
"revalidate target disk",
format!(
"target disk {disk_path} changed identity since it was \
selected ({before} -> {now}); refusing to partition"
),
));
}
}
}
Ok(())
}
fn storage_prepare(
&mut self,
auth: &phoebus_executor::DestructiveAuthorization,
@ -256,6 +324,7 @@ impl Installer {
self.state.luks_uuid = Some("<luks-uuid>".into());
return Ok(());
}
self.revalidate_target_disk()?;
storage::prepare(
&self.exec,
&self.config,
@ -560,6 +629,12 @@ impl Installer {
Ok(())
}
/// A controlled, reversible re-check used by tests and by callers that want
/// to gate a destructive action on the current disk identity.
pub fn current_disks(&self) -> Vec<phoebus_core::Disk> {
probe::probe_disks(self.exec.runner.as_ref())
}
/// Capture an initial known-good snapshot and point a boot entry at it, so
/// recovery does not depend on the (possibly later broken) live root.
fn create_initial_recovery_point(&self, auth: &phoebus_executor::DestructiveAuthorization) {
@ -606,3 +681,99 @@ impl Installer {
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use phoebus_core::{Disk, DiskKind, Redactor};
use phoebus_executor::command::{CommandOutput, RecordingRunner};
use phoebus_executor::Logger;
fn lsblk_output(lines: &str) -> CommandOutput {
CommandOutput {
status: 0,
success: true,
stdout: lines.as_bytes().to_vec(),
stderr: Vec::new(),
duration: std::time::Duration::from_millis(1),
}
}
fn installer(target: &str, lsblk: &str) -> Installer {
let runner = RecordingRunner::new();
runner.set_response("lsblk", lsblk_output(lsblk));
let dir = tempfile::tempdir().unwrap().keep();
let logger = Logger::open(dir.join("install.log"), Redactor::new(), false);
let mut config = InstallConfig::default();
config.storage.disk = target.to_string();
let exec = Exec::new(Box::new(runner), logger, false, dir.join("root"), dir);
Installer::new(config, exec)
}
const VDA_OK: &str =
"NAME=\"vda\" MODEL=\"QEMU HARDDISK\" SIZE=\"32212254720\" TRAN=\"virtio\" RM=\"0\" RO=\"0\"\n";
const VDA_READONLY: &str =
"NAME=\"vda\" MODEL=\"QEMU HARDDISK\" SIZE=\"32212254720\" TRAN=\"virtio\" RM=\"0\" RO=\"1\"\n";
const VDB_ONLY: &str =
"NAME=\"vdb\" MODEL=\"OTHER\" SIZE=\"10737418240\" TRAN=\"virtio\" RM=\"0\" RO=\"0\"\n";
#[test]
fn revalidation_accepts_the_same_observed_disk() {
let installer = installer("/dev/vda", VDA_OK);
assert!(installer.revalidate_target_disk().is_ok());
}
#[test]
fn revalidation_refuses_a_disappeared_disk() {
let installer = installer("/dev/vda", VDB_ONLY);
let err = installer.revalidate_target_disk().unwrap_err().to_string();
assert!(err.contains("disappeared"), "{err}");
}
#[test]
fn revalidation_refuses_a_now_protected_disk() {
let installer = installer("/dev/vda", VDA_READONLY);
let err = installer.revalidate_target_disk().unwrap_err().to_string();
assert!(err.contains("read-only"), "{err}");
}
#[test]
fn revalidation_refuses_reused_device_name_with_a_new_size() {
let mut installer = installer("/dev/vda", VDA_OK);
// The reviewed device had a different size; the name now points at a
// different disk.
installer.disks = vec![Disk {
path: "/dev/vda".into(),
model: Some("QEMU HARDDISK".into()),
size_bytes: 8 * 1024 * 1024 * 1024,
transport: Some("virtio".into()),
removable: false,
read_only: false,
mounted: false,
is_block_device: true,
kind: DiskKind::Physical,
live_media: false,
}];
let err = installer.revalidate_target_disk().unwrap_err().to_string();
assert!(err.contains("changed size"), "{err}");
}
#[test]
fn revalidation_refuses_reused_device_name_with_a_new_model() {
let mut installer = installer("/dev/vda", VDA_OK);
installer.disks = vec![Disk {
path: "/dev/vda".into(),
model: Some("A DIFFERENT DISK".into()),
size_bytes: 32_212_254_720,
transport: Some("virtio".into()),
removable: false,
read_only: false,
mounted: false,
is_block_device: true,
kind: DiskKind::Physical,
live_media: false,
}];
let err = installer.revalidate_target_disk().unwrap_err().to_string();
assert!(err.contains("changed identity"), "{err}");
}
}

View file

@ -226,3 +226,44 @@ fn installer_help_is_available_to_the_gui() {
assert!(help.contains("deterministic `sys`"));
assert!(help.contains("installation medium"));
}
#[test]
fn welcome_primary_action_is_keyboard_reachable() {
let qml = read("installer/live/desktop/phoebus-welcome/shell.qml");
// The tiled window may not be focused at session start, so the launcher
// must request activation and force focus on the primary action; without
// this the focus ring (and Enter) never reach it.
assert!(
qml.contains("forceActiveFocus"),
"welcome never forces focus"
);
assert!(
qml.contains("requestActivate"),
"welcome never requests activation"
);
assert!(
qml.contains("id: installButton") || qml.contains("id: window"),
"welcome has no identifiable primary action"
);
// Regression: `FloatingWindow` has no `onActiveChanged`; using it makes the
// whole configuration fail to load.
assert!(
!qml.contains("onActiveChanged"),
"welcome uses a non-existent FloatingWindow signal"
);
}
#[test]
fn progress_cannot_be_abandoned_silently() {
let qml = read("installer/live/desktop/phoebus-install/shell.qml");
// Escape during the destructive stage must not close the frontend without
// an explanation.
assert!(
qml.contains("cannot be cancelled"),
"no truthful cancellation message"
);
assert!(
qml.contains("shell.phase === \"progress\""),
"the guard against closing mid-install is missing"
);
}

View file

@ -200,7 +200,10 @@ ShellRoot {
}
if (s === 2) {
if (!shell.aiConnected) {
shell.status = "Connect and validate an AI model before continuing.";
// Show the guidance beside the AI controls, not only in the
// footer, so the fix is obvious.
shell.aiError = "Connect and validate a model before continuing.";
shell.status = "";
return;
}
saveAndAdvance();
@ -460,9 +463,25 @@ ShellRoot {
shell.advance();
}
Timer {
id: windowFocusTimer
interval: 700
repeat: false
running: false
onTriggered: {
if (typeof window.requestActivate === "function")
window.requestActivate();
page.forceActiveFocus();
}
}
FloatingWindow {
id: window
Component.onCompleted: { if (typeof window.requestActivate === "function") window.requestActivate(); }
Component.onCompleted: {
if (typeof window.requestActivate === "function")
window.requestActivate();
windowFocusTimer.start();
}
visible: true
color: Theme.charcoal
implicitWidth: 980
@ -491,7 +510,13 @@ ShellRoot {
shell.back();
event.accepted = true;
} else if (event.key === Qt.Key_Escape) {
shell.closeInstaller();
// Closing the frontend mid-install would abandon a
// destructive operation without explanation. Refuse it and
// say so truthfully instead.
if (shell.phase === "progress")
shell.status = "The installation is in progress and cannot be cancelled safely. Wait for it to finish or for an error report."
else
shell.closeInstaller();
event.accepted = true;
} else if (event.key === Qt.Key_Return || event.key === Qt.Key_Enter) {
shell.nextAction();
@ -895,6 +920,7 @@ ShellRoot {
visible: shell.phase === "progress"
Text { text: "Installing Phoebus OS"; color: Theme.warmWhite; font.family: Theme.family; font.pixelSize: Theme.fontTitle; font.weight: Font.DemiBold }
Text { width: parent.width; text: "The stages below are the real backend stages. Downloads, compilation, configuration and verification are reported as they happen; no percentage is estimated."; color: Theme.muted; font.family: Theme.family; font.pixelSize: Theme.fontSmall; wrapMode: Text.WordWrap }
Text { width: parent.width; text: "This cannot be cancelled safely once disk changes begin. Leave the window open until the installation finishes or reports an error."; color: Theme.warning; font.family: Theme.family; font.pixelSize: Theme.fontSmall; wrapMode: Text.WordWrap }
Rectangle {
id: progressTrack
width: parent.width; height: 6; radius: 3; color: Theme.border

View file

@ -48,9 +48,28 @@ ShellRoot {
}
}
// The compositor may not have focused the tiled window yet at session
// start; request activation and, shortly after, force focus on the primary
// action so it is reachable with the keyboard (Enter).
Timer {
id: focusTimer
interval: 700
repeat: false
running: false
onTriggered: {
if (typeof window.requestActivate === "function")
window.requestActivate();
installButton.forceActiveFocus();
}
}
FloatingWindow {
id: window
Component.onCompleted: { if (typeof window.requestActivate === "function") window.requestActivate(); }
Component.onCompleted: {
if (typeof window.requestActivate === "function")
window.requestActivate();
focusTimer.start();
}
visible: true
color: Theme.charcoal
implicitWidth: 940
@ -167,6 +186,7 @@ ShellRoot {
spacing: 20
PhoebusButton {
id: installButton
label: "Install Phoebus OS"
primary: true
implicitHeight: 58

View file

@ -62,9 +62,35 @@ To patch a console into an existing entry for observation, the BLS entry in
`/efi/loader/entries/*.conf` takes an `options` line; the installer can also
embed a console via `KERNEL_CONSOLE` (`GENTOO_KERNEL_CONSOLE` equivalent).
## Safety
## Safety (enforced, not just documented)
- `DISK` must be a qcow2 image; never point it at `/dev/*`.
- The installer itself classifies the ISO's device as protected.
- Secrets are passed through 0600 files and are checked for leakage in the
installer log by `install.sh`.
`vmsafety.py` validates every writable drive before QEMU starts:
- `DISK`/`DISKS` must name **qcow2** files inside the disposable directory
`PHOEBUS_VM_DISKS` (default `$PHOEBUS_VM_STATE/disks`).
- `/dev/*` paths, block and character devices, non-regular files, raw images,
symlinks that resolve outside the directory, and disks whose backing chain
reaches outside it are **refused** with a nonzero exit.
- Each run gets a private state directory (mode 0700), its own writable OVMF
variable file and a unique QMP monitor socket.
- Screenshots use structured QMP and argument arrays; there is no shell
interpolation (`os.system`) in the harness.
- Secrets are passed through 0600 files and checked for leakage in the
installer log by the guest script.
## Results
Every driver writes `results.json` (and a `screenshot-manifest.json` for the
GUI driver) under its run directory and exits nonzero on any `FAIL` (and, with
`PHOEBUS_VM_STRICT=1`, on `BLOCKED`/`NOT RUN`). Statuses are `PASS`, `FAIL`,
`BLOCKED`, `SKIPPED` and `NOT RUN`; a timeout is always a `FAIL`, never a pass.
```sh
make test-vm # unit-test the safety and result logic (no VM needed)
PHOEBUS_VM_DISKS=/var/tmp/phoebus-vm/disks \
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
OVMF_VARS=/usr/share/OVMF/OVMF_VARS_4M.fd \
DISK=/var/tmp/phoebus-vm/disks/target.qcow2 \
ISO=installer/live/phoebus-installer-amd64.iso \
python3 installer/tests/vm/gui-driver.py gui
```

View file

@ -13,10 +13,12 @@ Two modes:
boot : boot the installed disk alone (no ISO), unlock LUKS, log in and run
verification commands.
Everything is parameterised through environment variables. `DISK` must be a
qcow2 image; this script never touches a physical disk. Secrets are served from
the host as 0600 files and fetched inside the guest, so they never appear in
the serial transcript.
Everything is parameterised through environment variables. `DISK`/`DISKS` must
be qcow2 files inside the disposable directory named by `PHOEBUS_VM_DISKS`
(default `$PHOEBUS_VM_STATE/disks`); block devices, `/dev/*`, escaping
symlinks, raw images and outside backing chains are refused. Secrets are served
from the host as 0600 files and fetched inside the guest, so they never appear
in the serial transcript.
Host setup (see docs/DEVELOPMENT.md):
@ -31,15 +33,18 @@ Host setup (see docs/DEVELOPMENT.md):
"""
import os
import sys
from pathlib import Path
import pexpect
import vmsafety
from vmsafety import Results
QEMU = os.environ.get("QEMU_BIN", "qemu-system-x86_64")
OVMF_CODE = os.environ["OVMF_CODE"]
OVMF_VARS = os.environ["OVMF_VARS"]
DISK = os.environ["DISK"]
OVMF_VARS_TEMPLATE = os.environ["OVMF_VARS"]
DISKS = os.environ.get("DISKS") or os.environ.get("DISK", "")
ISO = os.environ.get("ISO", "")
SERIAL_LOG = os.environ.get("SERIAL_LOG", "/tmp/phoebus-appliance-serial.log")
SERVE_URL = os.environ.get("SERVE_URL", "http://10.0.2.2:8000")
LUKS_PW = os.environ.get("LUKS_PASSPHRASE", "phoebus-luks-test")
USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test")
@ -51,29 +56,37 @@ SMP = os.environ.get("VM_SMP", "8")
INSTALL_TIMEOUT = int(os.environ.get("INSTALL_TIMEOUT", "10800"))
def base_args():
return [
def disposable_dir() -> Path:
base = os.environ.get("PHOEBUS_VM_STATE", "/var/tmp/phoebus-vm")
return Path(os.environ.get("PHOEBUS_VM_DISKS", base + "/disks"))
def base_args(ovmf_vars, disks):
args = [
"-machine", "q35,accel=kvm",
"-cpu", "host", "-smp", SMP, "-m", MEM,
"-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}",
"-drive", f"if=pflash,format=raw,file={OVMF_VARS}",
"-drive", f"file={DISK},if=virtio,format=qcow2",
"-drive", f"if=pflash,format=raw,file={ovmf_vars}",
]
for disk in disks:
args += ["-drive", f"file={disk},if=virtio,format=qcow2"]
args += [
"-netdev", "user,id=n0", "-device", "virtio-net-pci,netdev=n0,romfile=",
"-device", "virtio-rng-pci", "-vga", "std", "-display", "none",
"-serial", "stdio", "-monitor", "none", "-no-reboot",
]
return args
def spawn(args):
def spawn(args, log):
child = pexpect.spawn(QEMU, args, timeout=900, encoding="utf-8",
codec_errors="replace", maxread=65536)
child.delaybeforesend = 0.4
child.logfile = log
return child
def login_live(child):
# The live medium may auto-login or present a login prompt; its hostname is
# typically `debian` (standard live) or `live`.
idx = child.expect([r"(?:live|debian) login:", r"[$#] $"], timeout=900)
if idx == 0:
child.sendline(LIVE_USER)
@ -82,16 +95,17 @@ def login_live(child):
child.expect(r"[$#] $", timeout=120)
def do_install():
args = base_args()
def do_install(results, paths, disks):
if not ISO:
raise SystemExit("ISO is required for install mode")
results.blocked("iso-required", "ISO is required for install mode")
return
args = base_args(str(paths.ovmf_vars), disks)
args += ["-drive", f"file={ISO},media=cdrom,readonly=on"]
log = open(SERIAL_LOG, "w")
child = spawn(args)
child.logfile = log
log = open(paths.serial_log, "w")
child = spawn(args, log)
try:
login_live(child)
results.pass_("live-login")
child.sendline(
f"curl -fsSL {SERVE_URL}/appliance-guest.sh -o /tmp/gi.sh && bash /tmp/gi.sh"
)
@ -99,18 +113,25 @@ def do_install():
"Kernel panic", pexpect.EOF, pexpect.TIMEOUT],
timeout=INSTALL_TIMEOUT)
if "INSTALL-RC" in (child.after or ""):
print("INSTALL_RC", child.match.group(1), flush=True)
rc = child.match.group(1)
results.assert_true("install-rc-zero", rc == "0", f"INSTALL-RC={rc}")
else:
print("INSTALL did not report a status", flush=True)
results.fail("install-rc-zero", "install did not report a status")
serial = paths.serial_log.read_text(errors="replace")
results.assert_true("no-secret-leak", "SECRET_LEAK_FOUND" not in serial,
"guest reported a secret leak")
child.expect(["===POWEROFF===", pexpect.EOF, pexpect.TIMEOUT], timeout=600)
child.expect(pexpect.EOF, timeout=300)
except pexpect.TIMEOUT as exc:
results.fail("install", f"timeout: {exc}")
except pexpect.EOF:
results.fail("install", "unexpected EOF")
finally:
child.close(force=True)
log.close()
def do_boot():
args = base_args() + ["-boot", "order=c"]
def do_boot(results, paths, disks):
args = base_args(str(paths.ovmf_vars), disks) + ["-boot", "order=c"]
checks = os.environ.get(
"BOOT_CHECKS",
"echo ===CHECKS-$(printf START)===; "
@ -120,13 +141,13 @@ def do_boot():
"/usr/local/bin/sys rollback status 2>&1 || true; "
"echo ===CHECKS-$(printf END)===",
)
log = open(SERIAL_LOG, "w")
child = spawn(args)
child.logfile = log
log = open(paths.serial_log, "w")
child = spawn(args, log)
try:
child.expect([r"[Pp]assphrase", r"login:"], timeout=600)
if "assphrase" in (child.after or ""):
child.sendline(LUKS_PW)
logged_in = False
for _ in range(5):
child.expect(r"phoebus login:", timeout=300)
child.sendline(USER)
@ -136,21 +157,52 @@ def do_boot():
child.sendline(USER_PW)
if child.expect([r"[$#] $", r"Login incorrect", r"phoebus login:"],
timeout=120) == 0:
logged_in = True
break
results.assert_true("detached-boot-login", logged_in, "could not log in")
child.sendline(checks)
child.expect("===CHECKS-END===", timeout=int(os.environ.get("CHECKS_TIMEOUT", "300")))
print("checks complete", flush=True)
serial = paths.serial_log.read_text(errors="replace")
results.assert_true("boot-systemd-running", "running" in serial,
"systemd did not report running")
except pexpect.TIMEOUT as exc:
results.fail("boot", f"timeout: {exc}")
except pexpect.EOF:
results.fail("boot", "unexpected EOF")
finally:
child.close(force=True)
log.close()
if __name__ == "__main__":
def main() -> int:
mode = sys.argv[1] if len(sys.argv) > 1 else ""
if mode == "install":
do_install()
elif mode == "boot":
do_boot()
else:
if mode not in ("install", "boot"):
print(__doc__)
sys.exit(2)
return 2
results = Results(f"appliance-{mode}")
paths = vmsafety.make_run_paths(
f"appliance-{mode}",
base=os.environ.get("PHOEBUS_VM_STATE", "/var/tmp/phoebus-vm"),
ovmf_vars_template=OVMF_VARS_TEMPLATE,
)
try:
disks = vmsafety.validate_writable_drives(DISKS.split(","), disposable_dir())
except vmsafety.UnsafeDiskError as exc:
results.blocked("disposable-disk", str(exc))
results.write(paths.results_json)
print(f"harness error: {exc}", file=sys.stderr)
return 2
results.pass_("disposable-disk", ", ".join(str(d) for d in disks))
try:
if mode == "install":
do_install(results, paths, disks)
else:
do_boot(results, paths, disks)
finally:
results.write(paths.results_json)
print(results.summary(), flush=True)
return results.exit_code()
if __name__ == "__main__":
sys.exit(main())

View file

@ -4,343 +4,645 @@
The live medium boots into Mango + DankMaterialShell and opens the branded
welcome window. This driver boots it with a graphical device and a serial
console, checks the launcher/branding payload, drives the graphical installer
with `wtype` over the live session, and captures QEMU framebuffer screenshots.
over the live session, and captures QEMU framebuffer screenshots through QMP.
Modes:
gui : boot, log in on serial, verify the welcome/branding payload, open
the installer, prove duplicate prevention, walk the first steps and
capture screenshots.
the installer from the welcome action, prove duplicate prevention,
walk the wizard steps and capture screenshots.
install : boot, log in on serial, fetch a non-interactive config and 0600
secrets over QEMU user networking, run the deterministic install
with the static binary, scan the log for a secret leak, power off.
boot : boot the installed disk alone (no ISO), unlock LUKS, log in and run
verification commands.
`DISK` must always be a disposable qcow2 image. This script never touches a
physical disk.
Safety: every writable drive must be a qcow2 file inside the disposable
directory named by `PHOEBUS_VM_DISKS` (default
`$PHOEBUS_VM_STATE/disks`). The driver refuses block devices, `/dev/*`,
symlinks that escape the directory, raw images and images with an outside
backing chain. Each run gets its own private state directory, a fresh writable
OVMF variable file and a unique QMP monitor socket. Results are structured and
the process exits nonzero on any failed assertion, timeout, unexpected EOF or
missing result.
"""
from __future__ import annotations
import json
import os
import socket
import re
import shutil
import sys
import time
from pathlib import Path
import pexpect
import vmsafety
from vmsafety import BLOCKED, FAIL, PASS, Results, HarnessError
QEMU = os.environ.get("QEMU_BIN", "qemu-system-x86_64")
OVMF_CODE = os.environ["OVMF_CODE"]
OVMF_VARS = os.environ["OVMF_VARS"]
OVMF_VARS_TEMPLATE = os.environ["OVMF_VARS"]
ISO = os.environ.get("ISO", "")
DISK = os.environ.get("DISK", "")
SERIAL_LOG = os.environ.get("SERIAL_LOG", "/tmp/phoebus-gui-serial.log")
MONITOR = os.environ.get("MONITOR", "/tmp/phoebus-gui-monitor.sock")
SHOT_DIR = os.environ.get("SHOT_DIR", "/tmp/phoebus-gui-shots")
DISKS = os.environ.get("DISKS") or os.environ.get("DISK", "")
SERVE_URL = os.environ.get("SERVE_URL", "http://10.0.2.2:8000")
LIVE_USER = os.environ.get("LIVE_USER", "phoebus")
LIVE_PW = os.environ.get("LIVE_PASSWORD", "phoebus")
USER = os.environ.get("USERNAME", "phoebus")
USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test")
LUKS_PW = os.environ.get("LUKS_PASSPHRASE", "phoebus-luks-test")
SERVE_URL = os.environ.get("SERVE_URL", "http://10.0.2.2:8000")
MEM = os.environ.get("VM_MEM", "8192")
SMP = os.environ.get("VM_SMP", "8")
BOOT_TIMEOUT = int(os.environ.get("BOOT_TIMEOUT", "900"))
INSTALL_TIMEOUT = int(os.environ.get("INSTALL_TIMEOUT", "10800"))
WAYLAND_ENV = "XDG_RUNTIME_DIR=/run/user/1000"
SESSION_SETTLE = int(os.environ.get("SESSION_SETTLE", "20"))
BACKEND_SETTLE = int(os.environ.get("BACKEND_SETTLE", "30"))
def args(attach_iso=True, boot_disk=False):
a = [
"-machine", "q35,accel=kvm",
"-cpu", "host", "-smp", SMP, "-m", MEM,
"-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}",
"-drive", f"if=pflash,format=raw,file={OVMF_VARS}",
]
if DISK:
a += ["-drive", f"file={DISK},if=virtio,format=qcow2"]
a += [
# A real GPU device so the compositor gets a DRM node and a seat.
"-device", "virtio-gpu-pci",
"-netdev", "user,id=n0", "-device", "virtio-net-pci,netdev=n0,romfile=",
"-device", "virtio-rng-pci",
]
if attach_iso and ISO:
a += ["-drive", f"file={ISO},media=cdrom,readonly=on"]
a += [
"-boot", "order=c" if boot_disk else "order=d",
"-vga", "none", "-display", "none",
"-serial", "stdio",
"-monitor", f"unix:{MONITOR},server,nowait",
"-no-reboot",
]
return a
def spawn(attach_iso=True, boot_disk=False):
if os.path.exists(MONITOR):
os.unlink(MONITOR)
child = pexpect.spawn(QEMU, args(attach_iso, boot_disk), timeout=BOOT_TIMEOUT,
encoding="utf-8", codec_errors="replace", maxread=65536)
child.delaybeforesend = 0.4
return child
def screendump(name):
"""Capture the QEMU framebuffer to SHOT_DIR/<name>.ppm (and .png if
ImageMagick is available)."""
os.makedirs(SHOT_DIR, exist_ok=True)
target = os.path.join(SHOT_DIR, name + ".ppm")
if not os.path.exists(MONITOR):
return None
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.settimeout(20)
try:
s.connect(MONITOR)
time.sleep(0.5)
try:
s.recv(65536)
except socket.timeout:
pass
s.sendall(b"screendump %s\n" % target.encode())
time.sleep(2)
try:
s.recv(65536)
except socket.timeout:
pass
finally:
s.close()
if not os.path.exists(target):
return None
os.system(f"magick '{target}' '{target[:-4]}.png' 2>/dev/null || "
f"convert '{target}' '{target[:-4]}.png' 2>/dev/null")
return target
def login_live(child):
# The live serial getty shows `<hostname> login:` and the password is the
# known live-only credential.
idx = child.expect([r"login:", r"[$#] $"], timeout=BOOT_TIMEOUT)
if idx == 0:
child.sendline(LIVE_USER)
child.expect(r"[Pp]assword:", timeout=90)
child.sendline(LIVE_PW)
child.expect(r"[$#] $", timeout=180)
def live_shell(child, command, end_marker, timeout=180):
child.sendline(command)
child.expect(end_marker, timeout=timeout)
def set_wayland(child):
# Export the live user's Wayland socket for wtype-based GUI driving.
child.sendline(
'export XDG_RUNTIME_DIR=/run/user/1000; '
'export WAYLAND_DISPLAY="$(basename "$(ls /run/user/1000/wayland-* 2>/dev/null | head -1)")"; '
'echo WAYLAND=$WAYLAND_DISPLAY'
def _template_dir() -> Path:
return Path(
os.environ.get("PHOEBUS_VM_STATE", "/var/tmp/phoebus-vm")
)
child.expect(r"WAYLAND=wayland-\d+", timeout=60)
def sendkey(*keys):
"""Inject keys through the QEMU monitor (hardware keyboard level). This is
independent of the guest's input-method/portal setup."""
if not os.path.exists(MONITOR):
return
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.settimeout(10)
try:
s.connect(MONITOR)
time.sleep(0.3)
def _disposable_dir() -> Path:
return Path(os.environ.get("PHOEBUS_VM_DISKS", str(_template_dir() / "disks")))
class Driver:
def __init__(self, mode: str):
self.mode = mode
self.results = Results(f"gui-{mode}")
self.paths = vmsafety.make_run_paths(
f"gui-{mode}", base=_template_dir(), ovmf_vars_template=OVMF_VARS_TEMPLATE
)
self.manifest: list[dict] = []
self.seq = 0
self.child: pexpect.spawn | None = None
self.log = None
self.spawned = False
self.disks: list[Path] = []
self.boot_disk = False
self._prepare()
# -- setup -------------------------------------------------------------
def _prepare(self) -> None:
if not Path(QEMU).exists() and shutil.which(QEMU) is None:
raise HarnessError(f"QEMU binary not found: {QEMU}")
if DISKS:
try:
self.disks = vmsafety.validate_writable_drives(
DISKS.split(","), _disposable_dir()
)
except vmsafety.UnsafeDiskError as exc:
raise HarnessError(str(exc)) from exc
if ISO:
iso = Path(ISO)
if not iso.is_file():
raise HarnessError(f"ISO is not a regular file: {iso}")
if not Path(OVMF_CODE).is_file():
raise HarnessError(f"OVMF_CODE is not a file: {OVMF_CODE}")
if not Path(OVMF_VARS_TEMPLATE).is_file():
raise HarnessError(f"OVMF_VARS template is not a file: {OVMF_VARS_TEMPLATE}")
# -- qemu --------------------------------------------------------------
def qemu_args(self, attach_iso: bool, boot_disk: bool) -> list[str]:
args = [
"-machine", "q35,accel=kvm",
"-cpu", "host", "-smp", SMP, "-m", MEM,
"-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}",
"-drive", f"if=pflash,format=raw,file={self.paths.ovmf_vars}",
]
for disk in self.disks:
args += ["-drive", f"file={disk},if=virtio,format=qcow2"]
args += [
# A real GPU device so the compositor gets a DRM node and a seat.
"-device", "virtio-gpu-pci",
"-netdev", "user,id=n0", "-device", "virtio-net-pci,netdev=n0,romfile=",
"-device", "virtio-rng-pci",
]
if attach_iso and ISO:
args += ["-drive", f"file={ISO},media=cdrom,readonly=on"]
args += [
"-boot", "order=c" if boot_disk else "order=d",
"-vga", "none", "-display", "none",
"-serial", "stdio",
"-qmp", f"unix:{self.paths.monitor_sock},server,nowait",
"-no-reboot",
]
return args
def spawn(self, attach_iso: bool = True, boot_disk: bool = False) -> None:
if self.paths.monitor_sock.exists():
self.paths.monitor_sock.unlink()
args = self.qemu_args(attach_iso, boot_disk)
print(f"[run {self.paths.run_id}] {QEMU} " + " ".join(args), flush=True)
self.child = pexpect.spawn(
QEMU, args, timeout=BOOT_TIMEOUT, encoding="utf-8",
codec_errors="replace", maxread=65536,
)
self.child.delaybeforesend = 0.4
self.log = open(self.paths.serial_log, "w")
self.child.logfile = self.log
self.spawned = True
self.results.pass_(
"qemu-spawned", f"{len(self.disks)} writable disk(s); iso={bool(ISO)}"
)
# -- assertions and screenshots ---------------------------------------
def run_id(self) -> str:
return self.paths.run_id
def shot(
self,
slug: str,
ui_state: str,
action: str,
expected: str,
observed: str | None = None,
) -> Path | None:
self.seq += 1
name = vmsafety.screenshot_name(self.seq, slug)
ppm = self.paths.shot_dir / (name + ".ppm")
png = self.paths.shot_dir / (name + ".png")
if not self.paths.monitor_sock.exists():
self.results.skip(f"screenshot-{name}", "no monitor socket (not spawned)")
return None
ok = False
try:
s.recv(65536)
except socket.timeout:
pass
for k in keys:
s.sendall(("sendkey %s\n" % k).encode())
with vmsafety.QmpClient(self.paths.monitor_sock) as client:
client.screendump(ppm)
vmsafety.convert_ppm(ppm, png)
ok = ppm.exists() and ppm.stat().st_size > 0
except Exception as exc: # noqa: BLE001 - report, never crash the run
self.results.fail(f"screenshot-{name}", str(exc))
self.manifest.append({
"run_id": self.paths.run_id,
"scenario": self.mode,
"sequence": self.seq,
"timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
"ui_state": ui_state,
"action": action,
"expected": expected,
"observed": observed if observed is not None else ("captured" if ok else "capture failed"),
"ppm": str(ppm) if ppm.exists() else None,
"png": str(png) if png.exists() else None,
})
if ok:
self.results.pass_(f"screenshot-{name}", str(png if png.exists() else ppm))
return ppm if ok else None
def write_manifest(self) -> None:
path = self.paths.directory / "screenshot-manifest.json"
path.write_text(json.dumps(self.manifest, indent=2) + "\n")
# -- pexpect helpers ---------------------------------------------------
def expect(self, patterns, timeout: int, label: str):
assert self.child is not None
try:
index = self.child.expect(patterns, timeout=timeout)
except pexpect.TIMEOUT as exc:
self.results.fail(label, f"timeout after {timeout}s")
raise HarnessError(f"timeout: {label}") from exc
except pexpect.EOF as exc:
self.results.fail(label, "unexpected EOF from the VM")
raise HarnessError(f"unexpected EOF: {label}") from exc
self.last_match = self.child.match
return index
def last_group(self, index: int) -> str:
match = getattr(self, "last_match", None)
if match is None:
return ""
try:
return match.group(index)
except (IndexError, AttributeError):
return ""
def last_text(self) -> str:
match = getattr(self, "last_match", None)
return match.group(0) if match is not None else ""
def shell(self, command: str, end_marker: str, timeout: int = 180, label: str = "") -> str:
assert self.child is not None
self.child.sendline(command)
self.expect(end_marker, timeout=timeout, label=label or f"shell:{end_marker}")
return self.child.before or ""
def poll_shell(
self, command: str, pattern: str, timeout: int, label: str, record: bool = True
) -> str | None:
"""Send a command and retry until `pattern` matches or the deadline.
Bounded readiness polling instead of blind sleeps. `record=False` lets a
caller retry without recording an intermediate failure.
"""
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
assert self.child is not None
self.child.sendline(command)
try:
self.child.expect(pattern, timeout=15)
return self.child.match.group(0)
except (pexpect.TIMEOUT, pexpect.EOF):
time.sleep(2)
if record:
self.results.fail(label, f"readiness not reached within {timeout}s")
return None
def qmp(self, action: str, *args, **kwargs) -> None:
assert self.child is not None
try:
with vmsafety.QmpClient(self.paths.monitor_sock) as client:
getattr(client, action)(*args, **kwargs)
except Exception as exc: # noqa: BLE001
self.results.fail(f"qmp-{action}", str(exc))
raise
def sendkey(self, *keys: str) -> None:
for key in keys:
self.qmp("sendkey", key)
time.sleep(0.2)
time.sleep(0.3)
# -- guest login -------------------------------------------------------
def login_live(self) -> None:
assert self.child is not None
idx = self.expect([r"login:", r"[$#] $"], timeout=BOOT_TIMEOUT, label="live-login-prompt")
if idx == 0:
self.child.sendline(LIVE_USER)
self.expect(r"[Pp]assword:", timeout=90, label="live-password-prompt")
self.child.sendline(LIVE_PW)
self.expect(r"[$#] $", timeout=180, label="live-shell")
self.results.pass_("live-login")
def set_wayland(self) -> None:
out = self.shell(
'export XDG_RUNTIME_DIR=/run/user/1000; '
'export WAYLAND_DISPLAY="$(basename "$(ls /run/user/1000/wayland-* 2>/dev/null | head -1)")"; '
'echo WAYLAND=$WAYLAND_DISPLAY',
r"WAYLAND=wayland-\d+",
timeout=60,
label="wayland-session",
)
self.results.pass_("wayland-session", out.strip()[-40:])
# -- modes -------------------------------------------------------------
def run(self) -> int:
try:
s.recv(65536)
except socket.timeout:
if self.mode == "gui":
self.do_gui()
elif self.mode == "install":
self.do_install()
elif self.mode == "boot":
self.do_boot()
else:
print(__doc__)
return 2
except HarnessError as exc:
self.results.fail("harness", str(exc))
except Exception as exc: # noqa: BLE001
self.results.fail("harness-exception", repr(exc))
finally:
if self.spawned:
try:
self.shot("final-state", "final", "end of run", "last observed state")
except Exception: # noqa: BLE001
pass
self.teardown()
self.write_manifest()
results_path = self.results.write(self.paths.results_json)
print(self.results.summary(), flush=True)
print(f"results: {results_path}", flush=True)
print(f"serial: {self.paths.serial_log}", flush=True)
print(f"shots: {self.paths.shot_dir}", flush=True)
return self.results.exit_code()
def teardown(self) -> None:
if self.child is not None:
try:
self.child.close(force=True)
except Exception: # noqa: BLE001
pass
if self.log is not None:
try:
self.log.close()
except Exception: # noqa: BLE001
pass
# Cleanup is limited to this run's own socket.
try:
if self.paths.monitor_sock.exists():
self.paths.monitor_sock.unlink()
except OSError:
pass
finally:
s.close()
# -- GUI journey -------------------------------------------------------
def do_gui(self) -> None:
self.spawn(attach_iso=True, boot_disk=False)
self.login_live()
def key(child, *wtype_args):
quoted = " ".join(f"'{a}'" for a in wtype_args)
child.sendline(f"wtype {quoted} >/dev/null 2>&1; echo KEY-DONE")
child.expect("KEY-DONE", timeout=60)
welcome = self.poll_shell(
"echo WELCOME=$(pgrep -fc 'quickshell.*phoebus-welcome' 2>/dev/null || echo 0)",
r"WELCOME=([1-9][0-9]*)",
timeout=int(os.environ.get("WELCOME_TIMEOUT", "180")),
label="welcome-window",
)
self.results.assert_true(
"welcome-autostarted", welcome is not None, "welcome window did not appear"
)
self.shot("01-welcome", "welcome window", "observe at startup",
"branded welcome window with a dominant Install action")
def do_gui():
child = spawn()
log = open(SERIAL_LOG, "w")
child.logfile = log
try:
login_live(child)
# Give greetd/the session time to bring up Mango + DMS + the welcome
# window (it starts after the shell is ready).
time.sleep(int(os.environ.get("SESSION_SETTLE", "30")))
for _ in range(12):
child.sendline(
"echo WELCOME=$(pgrep -fc 'quickshell.*phoebus-welcome' 2>/dev/null || echo 0)"
)
child.expect(r"WELCOME=(\d+)", timeout=60)
if int(child.match.group(1)) > 0:
break
time.sleep(5)
# Payload checks (no secrets here).
# Markers are built with command substitution so the shell's echo of the
# typed command cannot contain them; a match therefore proves output.
checks = (
"echo ===GUI-CHECKS-$(printf START)===; "
"test -e /etc/phoebus/live && echo LIVE-MARKER; "
"test -s /usr/share/phoebus/branding/wallpaper.svg && echo BRAND-WALLPAPER; "
"test -s /usr/share/icons/hicolor/scalable/apps/phoebus.svg && echo BRAND-ICON; "
"test -s /etc/xdg/quickshell/phoebus-install/shell.qml && echo INSTALL-QML; "
"test -s /usr/share/applications/phoebus-install.desktop && echo DESKTOP-ENTRY; "
"test -f /home/phoebus/.config/DankMaterialShell/.firstlaunch && echo ONBOARDING-SUPPRESSED; "
"test -e /etc/phoebus/live && echo LIVE-$(printf MARKER); "
"test -s /usr/share/phoebus/branding/wallpaper.svg && echo BRAND-$(printf WALLPAPER); "
"test -s /usr/share/icons/hicolor/scalable/apps/phoebus.svg && echo BRAND-$(printf ICON); "
"test -s /etc/xdg/quickshell/phoebus-install/shell.qml && echo INSTALL-$(printf QML); "
"test -s /usr/share/applications/phoebus-install.desktop && echo DESKTOP-$(printf ENTRY); "
"test -f /home/phoebus/.config/DankMaterialShell/.firstlaunch && echo ONBOARDING-$(printf SUPPRESSED); "
"echo ===GUI-CHECKS-$(printf END)==="
)
live_shell(child, checks, "===GUI-CHECKS-END===", timeout=180)
shot = screendump("01-welcome")
print("welcome screenshot:", shot, flush=True)
set_wayland(child)
# Backend disk protection on the real VM: the live medium must be
# reported protected and never selectable.
child.sendline(
"printf '%s\\n%s\\n' '{\"id\":1,\"op\":\"disks\"}' '{\"id\":2,\"op\":\"quit\"}' "
"| sudo -n /usr/local/bin/phoebus-installer --gui-bridge 2>/dev/null "
"| head -1 > /tmp/disks.json; "
"echo DISKS=$(wc -c </tmp/disks.json); cat /tmp/disks.json"
)
child.expect(r"DISKS=(\d+)", timeout=120)
print("disks probe bytes:", child.match.group(1), flush=True)
# Activate the focused "Install Phoebus OS" button with Return. This is
# the real launcher-to-installer journey (no shell shortcut).
sendkey("ret")
time.sleep(8)
child.sendline("echo INST=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)")
child.expect(r"INST=(\d+)", timeout=60)
if int(child.match.group(1)) == 0:
# The window manager may not have focused the welcome; fall back to
# the launcher so the rest of the journey can still be exercised.
child.sendline(
"setsid /usr/local/bin/phoebus-install >/tmp/install-gui.log 2>&1 & echo LAUNCHED"
payload = self.shell(checks, "===GUI-CHECKS-END===", timeout=180, label="payload-checks")
for marker in (
"LIVE-MARKER", "BRAND-WALLPAPER", "BRAND-ICON", "INSTALL-QML", "DESKTOP-ENTRY",
):
self.results.assert_true(
f"payload-{marker.lower()}", marker in payload, f"{marker} not in command output"
)
if "ONBOARDING-SUPPRESSED" not in payload:
self.results.skip("onboarding-suppressed", "first-run marker not present")
self.set_wayland()
# Disk protection is a deterministic backend property. The bridge JSON
# is long and the serial console wraps it, so a small guest-side summary
# is emitted instead of parsing wrapped JSON. Every marker is built with
# command substitution so the echoed command cannot be mistaken for it.
self.shell(
"printf '%s\\n%s\\n' '{\"id\":1,\"op\":\"disks\"}' '{\"id\":2,\"op\":\"quit\"}' "
"> /tmp/req.json; echo REQ-$(printf DONE)",
"REQ-DONE",
timeout=30,
label="disk-probe-request",
)
summary = self.shell(
"sudo -n /usr/local/bin/phoebus-installer --gui-bridge < /tmp/req.json "
"2>/dev/null | head -1 > /tmp/disks.json; "
"echo DISKS-$(printf COUNT)=$(grep -o '{[^{}]*}' /tmp/disks.json | wc -l); "
"echo LIVE-$(printf COUNT)=$(grep -o '{[^{}]*\"live_medium\":true[^{}]*}' "
"/tmp/disks.json | wc -l); "
"echo LIVE-$(printf PROTECTED)=$(grep -o '{[^{}]*\"live_medium\":true[^{}]*}' "
"/tmp/disks.json | grep -c '\"protected\":true'); "
"echo PROBE-$(printf DONE)",
"PROBE-DONE",
timeout=120,
label="disk-probe",
)
self._assert_live_medium_protected(summary)
# Activate the focused welcome action with Return (the real launcher).
# Retry a few times; a transient focus race must not be recorded as a
# passing launcher test, and the fallback launch is recorded as a FAIL.
self.shot("01b-focus", "welcome focused", "before launcher key",
"primary Install action visibly focused")
installed = None
for _attempt in range(3):
self.sendkey("ret")
installed = self.poll_shell(
"echo INST=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)",
r"INST=([1-9][0-9]*)",
timeout=30,
label="launcher-opens-installer",
record=False,
)
if installed is not None:
break
if installed is None:
# Fallback launch for diagnostics only: the launcher test stays failed.
self.results.fail(
"launcher-opens-installer",
"Return did not open the installer; using a diagnostic fallback launch",
)
self.shell(
"setsid /usr/local/bin/phoebus-install >/tmp/install-gui.log 2>&1 & echo LAUNCHED",
"LAUNCHED",
timeout=30,
label="fallback-launch",
)
child.expect("LAUNCHED", timeout=30)
time.sleep(7)
# Surface the installer frontend's own log (it contains bridge errors).
child.sendline(
else:
self.results.pass_("launcher-opens-installer", "welcome action opened the installer")
# The frontend log must not contain bridge errors or a crash.
logdump = self.shell(
"echo QMLLOG-$(printf START); "
"cat /run/user/1000/quickshell/by-id/*/log.qslog 2>/dev/null | "
"grep -aiE 'phoebus-bridge|error|failed|sudo|handshake' | tail -30; "
"echo NOTTY-SUDO; setsid sh -c 'sudo -n true' ; echo NOTTYSUDO=$?; "
"echo QMLLOG-$(printf END)"
"grep -aiE 'phoebus-bridge|error|failed|handshake' | tail -30; "
"echo QMLLOG-$(printf END)",
"QMLLOG-END",
timeout=60,
label="frontend-log",
)
child.expect("QMLLOG-END", timeout=60)
screendump("02-installer-language")
# The first handshake probes hardware and disks; wait for it before
# driving the wizard so the backend is ready to validate.
time.sleep(int(os.environ.get("BACKEND_SETTLE", "30")))
# Close the welcome so the installer window has the keyboard focus
# (Mango tiles both windows; the welcome would otherwise receive keys).
child.sendline("pkill -f 'quickshell.*phoebus-wel[c]ome' || true; sleep 2; echo CLOSED")
child.expect("CLOSED", timeout=30)
hard = [ln for ln in logdump.splitlines()
if "phoebus-bridge:" in ln and "error" in ln.lower()]
self.results.assert_true("frontend-no-bridge-errors", not hard, "; ".join(hard[:3]))
self.shot("02-installer-start", "installer wizard", "opened from the welcome",
"language and region step with visible focus")
time.sleep(BACKEND_SETTLE)
# Close the welcome so the tiled installer holds the keyboard.
self.shell(
"pkill -f 'quickshell.*phoebus-wel[c]ome' || true; sleep 2; echo CLOSED",
"CLOSED",
timeout=30,
label="close-welcome",
)
# Duplicate prevention: a second launch must not create a second session.
child.sendline(
self.shell(
"pgrep -f 'quickshell.*phoebus-install' | wc -l > /tmp/n1; "
"/usr/local/bin/phoebus-install >/tmp/install-gui2.log 2>&1; "
"pgrep -f 'quickshell.*phoebus-install' | wc -l > /tmp/n2; "
"echo DUP n1=$(cat /tmp/n1) n2=$(cat /tmp/n2)"
"echo DUP n1=$(cat /tmp/n1) n2=$(cat /tmp/n2)",
r"DUP n1=(\d+) n2=(\d+)",
timeout=60,
label="duplicate-launch",
)
child.expect(r"DUP n1=(\d+) n2=(\d+)", timeout=60)
print("duplicate check:", child.match.group(0), flush=True)
# Move forward through the wizard with the keyboard shortcut.
sendkey("ctrl-right")
time.sleep(2)
screendump("03-network-prerequisites")
sendkey("ctrl-right")
time.sleep(2)
screendump("04-ai-model")
# Advancing without a connected model must be refused (blocked prereq).
sendkey("ctrl-right")
time.sleep(2)
screendump("05-ai-blocked")
print("gui checks complete", flush=True)
finally:
child.close(force=True)
log.close()
def do_install():
child = spawn()
log = open(SERIAL_LOG, "w")
child.logfile = log
try:
login_live(child)
child.sendline(
f"curl -fsSL {SERVE_URL}/appliance-guest-gui.sh -o /tmp/gi.sh && bash /tmp/gi.sh"
n1, n2 = int(self.last_group(1)), int(self.last_group(2))
self.results.assert_true(
"duplicate-sessions-prevented", n1 == n2 and n1 >= 1,
f"n1={n1} n2={n2}",
)
child.expect([r"===INSTALL-RC=([0-9]+)===", "===FETCH-FAIL===",
"Kernel panic", pexpect.EOF, pexpect.TIMEOUT],
timeout=INSTALL_TIMEOUT)
if "INSTALL-RC" in (child.after or ""):
print("INSTALL_RC", child.match.group(1), flush=True)
# Keyboard-walk the wizard, capturing each step.
for slug, state in [
("03-network", "network and prerequisites"),
("04-ai-model", "AI model connection"),
]:
self.sendkey("ctrl-right")
time.sleep(2)
self.shot(slug, state, "Ctrl+Right", "next wizard step")
if not self._installer_alive():
self.results.fail("installer-survived-navigation", f"crashed at {slug}")
return
# Advancing without a connected model must be refused: the process must
# still be alive and the backend must not have started an install.
self.sendkey("ctrl-right")
time.sleep(2)
self.shot("06-ai-blocked", "AI model blocked", "Ctrl+Right without a model",
"advance refused; no install started")
blocked = self._bridge_has_no_install_start()
self.results.assert_true(
"ai-step-blocks-install", blocked,
"the AI step allowed advancement without a connected model",
)
self.results.pass_("gui-walk-completed")
def _installer_alive(self) -> bool:
assert self.child is not None
self.child.sendline(
"echo ALIVE=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)"
)
try:
self.child.expect(r"ALIVE=(\d+)", timeout=30)
except (pexpect.TIMEOUT, pexpect.EOF):
return False
return int(self.child.match.group(1)) >= 1
def _bridge_has_no_install_start(self) -> bool:
# The installer log records storage_prepare only when a backend run
# actually starts; at this point it must not have completed it. The
# marker is built with command substitution so the echoed command cannot
# be mistaken for the result.
assert self.child is not None
self.child.sendline(
"echo NOSTART=$(grep -l 'stage complete: storage_prepare' "
"/run/phoebus-installer/install.log /tmp/phoebus-installer/install.log "
"2>/dev/null | wc -l)"
)
try:
self.child.expect(r"NOSTART=(\d+)", timeout=30)
except (pexpect.TIMEOUT, pexpect.EOF):
return False
return self.child.match.group(1).strip() == "0"
@staticmethod
def _first_int(text: str, key: str) -> int | None:
match = re.search(re.escape(key) + r"=(\d+)", text)
return int(match.group(1)) if match else None
def _assert_live_medium_protected(self, summary: str) -> None:
total = self._first_int(summary, "DISKS-COUNT")
live = self._first_int(summary, "LIVE-COUNT")
protected = self._first_int(summary, "LIVE-PROTECTED")
if total is None or live is None or protected is None:
self.results.fail(
"disks-probe",
f"could not read the disk summary (total={total} live={live} protected={protected})",
)
return
self.results.assert_true("disks-listed", total >= 1, "no disks reported")
if live >= 1:
self.results.assert_true(
"live-medium-protected",
protected == live,
f"{protected}/{live} live media were protected",
)
else:
print("INSTALL did not report a status", flush=True)
child.expect(["===POWEROFF===", pexpect.EOF, pexpect.TIMEOUT], timeout=600)
child.expect(pexpect.EOF, timeout=300)
finally:
child.close(force=True)
log.close()
self.results.skip("live-medium-protected", "no live medium in the probe")
# -- non-interactive install ------------------------------------------
def do_install(self) -> None:
if not self.disks:
self.results.blocked("install-disk", "no writable disk configured")
return
self.spawn(attach_iso=True, boot_disk=False)
self.login_live()
self.shell(
f"curl -fsSL {SERVE_URL}/appliance-guest-gui.sh -o /tmp/gi.sh && bash /tmp/gi.sh",
r"===INSTALL-RC=([0-9]+)===",
timeout=INSTALL_TIMEOUT,
label="install-completes",
)
rc = self.child.match.group(1) if self.child else "?"
self.results.assert_true("install-rc-zero", rc == "0", f"INSTALL-RC={rc}")
# The secret-leak marker is emitted by the guest script.
assert self.child is not None
try:
self.child.expect(r"===NO_SECRET_LEAK===", timeout=120)
self.results.pass_("no-secret-leak")
except (pexpect.TIMEOUT, pexpect.EOF):
self.results.fail("no-secret-leak", "the guest did not report NO_SECRET_LEAK")
try:
self.child.expect(["===POWEROFF===", pexpect.EOF], timeout=600)
except pexpect.TIMEOUT:
self.results.fail("poweroff", "the guest did not power off")
try:
self.child.expect(pexpect.EOF, timeout=300)
except pexpect.TIMEOUT:
self.results.fail("install-eof", "QEMU did not exit after poweroff")
def do_boot():
# Detached: no ISO, boot from the installed disk only.
child = spawn(attach_iso=False, boot_disk=True)
log = open(SERIAL_LOG, "w")
child.logfile = log
checks = os.environ.get(
"BOOT_CHECKS",
"echo ===CHECKS-$(printf START)===; "
"cat /proc/1/comm; systemctl is-system-running; "
"systemctl --failed --no-pager; ip -brief addr; "
"lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; echo ===CHECKS-$(printf END)===",
)
try:
child.expect([r"[Pp]assphrase", r"login:"], timeout=BOOT_TIMEOUT)
if "assphrase" in (child.after or ""):
child.sendline(LUKS_PW)
# -- detached boot -----------------------------------------------------
def do_boot(self) -> None:
if not self.disks:
self.results.blocked("boot-disk", "no writable disk configured")
return
self.spawn(attach_iso=False, boot_disk=True)
checks = os.environ.get(
"BOOT_CHECKS",
"echo ===CHECKS-$(printf START)===; "
"cat /proc/1/comm; systemctl is-system-running; "
"systemctl --failed --no-pager; ip -brief addr; "
"lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; echo ===CHECKS-$(printf END)===",
)
assert self.child is not None
idx = self.expect([r"[Pp]assphrase", r"login:"], timeout=BOOT_TIMEOUT, label="boot-prompt")
if idx == 0:
self.child.sendline(LUKS_PW)
logged_in = False
for _ in range(5):
child.expect(r"phoebus login:", timeout=300)
child.sendline(USER)
idx = child.expect([r"[Pp]assword:", r"phoebus login:", r"Login incorrect"],
timeout=60)
if idx == 0:
child.sendline(USER_PW)
if child.expect([r"[$#] $", r"Login incorrect", r"phoebus login:"],
timeout=120) == 0:
try:
self.child.expect(r"phoebus login:", timeout=300)
except (pexpect.TIMEOUT, pexpect.EOF):
break
self.child.sendline(USER)
choice = self.child.expect(
[r"[Pp]assword:", r"phoebus login:", r"Login incorrect"], timeout=60
)
if choice == 0:
self.child.sendline(USER_PW)
if self.child.expect([r"[$#] $", r"Login incorrect", r"phoebus login:"],
timeout=120) == 0:
logged_in = True
break
child.sendline(checks)
child.expect("===CHECKS-END===", timeout=int(os.environ.get("CHECKS_TIMEOUT", "300")))
print("checks complete", flush=True)
finally:
child.close(force=True)
log.close()
self.results.assert_true("detached-boot-login", logged_in, "could not log in")
self.shell(checks, "===CHECKS-END===",
timeout=int(os.environ.get("CHECKS_TIMEOUT", "300")), label="boot-checks")
serial = self.paths.serial_log.read_text(errors="replace")
self.results.assert_true(
"boot-systemd-running", "running" in serial, "systemd did not report running"
)
def main() -> int:
mode = sys.argv[1] if len(sys.argv) > 1 else ""
if mode not in ("gui", "install", "boot"):
print(__doc__)
return 2
if mode in ("install", "boot") and not DISKS:
print("error: DISK/DISKS must name a disposable qcow2 image", file=sys.stderr)
return 2
try:
return Driver(mode).run()
except HarnessError as exc:
print(f"harness error: {exc}", file=sys.stderr)
return 2
if __name__ == "__main__":
mode = sys.argv[1] if len(sys.argv) > 1 else ""
if mode == "gui":
do_gui()
elif mode == "install":
do_install()
elif mode == "boot":
do_boot()
else:
print(__doc__)
sys.exit(2)
sys.exit(main())

View file

@ -0,0 +1,108 @@
#!/usr/bin/env python3
"""Build a browsable HTML report for one VM run.
Combines `results.json` (structured checks) with `screenshot-manifest.json`
(per-capture metadata) into a single page that links each check to its
screenshots. Output goes next to the run directory's artifacts and is meant to
stay outside git.
python3 installer/tests/vm/report.py /var/tmp/phoebus-vm/<run-id>
"""
from __future__ import annotations
import html
import json
import sys
from pathlib import Path
STATUS_CLASS = {
"PASS": "pass",
"FAIL": "fail",
"BLOCKED": "blocked",
"SKIPPED": "skip",
"NOT RUN": "skip",
}
def build(run_dir: Path) -> Path:
results = json.loads((run_dir / "results.json").read_text())
manifest_path = run_dir / "screenshot-manifest.json"
manifest = json.loads(manifest_path.read_text()) if manifest_path.exists() else []
def esc(value) -> str:
return html.escape(str(value))
rows = []
for check in results.get("checks", []):
cls = STATUS_CLASS.get(check["status"], "skip")
detail = f'<span class="detail">{esc(check.get("detail", ""))}</span>' if check.get("detail") else ""
rows.append(
f'<tr class="{cls}"><td class="status">{esc(check["status"])}</td>'
f'<td>{esc(check["name"])}</td><td>{detail}</td></tr>'
)
shots = []
for shot in manifest:
png = shot.get("png")
rel = None
if png:
try:
rel = str(Path(png).relative_to(run_dir))
except ValueError:
rel = Path(png).name
image = f'<a href="{esc(rel)}"><img src="{esc(rel)}" loading="lazy"></a>' if rel else "<em>no image</em>"
shots.append(
"<figure>"
f'{image}<figcaption><b>{esc(shot.get("ui_state"))}</b><br>'
f'<small>{esc(shot.get("action"))} → expected: {esc(shot.get("expected"))}; '
f'observed: {esc(shot.get("observed"))}</small></figcaption></figure>'
)
counts = results.get("counts", {})
summary = " · ".join(f"{k}={v}" for k, v in counts.items() if v)
page = f"""<!doctype html>
<html lang="en"><head><meta charset="utf-8">
<title>Phoebus VM report · {esc(results.get('run_id'))}</title>
<style>
:root {{ color-scheme: dark; }}
body {{ background:#17171b; color:#f4efe6; font:14px/1.5 system-ui,sans-serif; margin:0; padding:24px; }}
h1 {{ font-size:20px; }} h2 {{ font-size:16px; margin-top:28px; color:#e8a33d; }}
table {{ border-collapse:collapse; width:100%; margin-top:8px; }}
td {{ padding:6px 10px; border-bottom:1px solid #3a3a42; vertical-align:top; }}
.status {{ font-weight:700; }}
tr.pass .status {{ color:#7fb069; }} tr.fail .status {{ color:#d2564b; }}
tr.blocked .status {{ color:#e0a24a; }} tr.skip .status {{ color:#a8a29a; }}
.detail {{ color:#a8a29a; }} .meta {{ color:#a8a29a; }}
.gallery {{ display:flex; flex-wrap:wrap; gap:16px; margin-top:12px; }}
figure {{ margin:0; width:420px; background:#232329; border:1px solid #3a3a42; border-radius:10px; overflow:hidden; }}
figure img {{ width:100%; display:block; }}
figcaption {{ padding:8px 10px; }}
</style></head><body>
<h1>Phoebus VM report · {esc(results.get('run_id'))}</h1>
<p class="meta">scenario: {esc(results.get('scenario'))} · exit_code: {esc(results.get('exit_code'))} · {esc(summary)}</p>
<h2>Checks</h2>
<table>{''.join(rows) or '<tr><td>no checks</td></tr>'}</table>
<h2>Screenshots ({len(shots)})</h2>
<div class="gallery">{''.join(shots)}</div>
</body></html>
"""
out = run_dir / "report.html"
out.write_text(page)
return out
def main() -> int:
if len(sys.argv) != 2:
print(__doc__)
return 2
run_dir = Path(sys.argv[1])
if not (run_dir / "results.json").exists():
print(f"no results.json in {run_dir}", file=sys.stderr)
return 1
print(build(run_dir))
return 0
if __name__ == "__main__":
sys.exit(main())

View file

@ -11,22 +11,28 @@ Two modes:
Everything is parameterised through environment variables so the script is not
tied to one host. See tests/vm/README.md for the variables.
This script never touches a physical disk: DISK is always a qcow2 image.
Safety: `DISK`/`DISKS` must be qcow2 files inside the disposable directory named
by `PHOEBUS_VM_DISKS` (default `$PHOEBUS_VM_STATE/disks`); block devices,
`/dev/*`, escaping symlinks, raw images and outside backing chains are refused.
Results are structured and the exit status is nonzero on failure.
"""
import os
import sys
import pexpect
import vmsafety
from vmsafety import Results
QEMU = os.environ.get("QEMU_BIN", "qemu-system-x86_64")
LIBDIR = os.environ.get("QEMU_LIBDIR", "")
DATADIR = os.environ.get("QEMU_DATADIR", "")
OVMF_CODE = os.environ["OVMF_CODE"]
OVMF_VARS = os.environ["OVMF_VARS"]
DISK = os.environ["DISK"]
OVMF_VARS_TEMPLATE = os.environ["OVMF_VARS"]
DISKS = os.environ.get("DISKS") or os.environ.get("DISK", "")
ISO = os.environ.get("ISO", "")
KERNEL = os.environ.get("KERNEL", "")
INITRD = os.environ.get("INITRD", "")
SERIAL_LOG = os.environ.get("SERIAL_LOG", "/tmp/phoebus-vm-serial.log")
LUKS_PW = os.environ.get("LUKS_PASSPHRASE", "phoebus-luks-test")
USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test")
USER = os.environ.get("USERNAME", "phoebus")
@ -39,7 +45,14 @@ BLS_APPEND = (
)
def base_args():
def disposable_dir():
import pathlib
base = os.environ.get("PHOEBUS_VM_STATE", "/var/tmp/phoebus-vm")
return pathlib.Path(os.environ.get("PHOEBUS_VM_DISKS", base + "/disks"))
def base_args(ovmf_vars):
env = dict(os.environ)
if LIBDIR:
env["LD_LIBRARY_PATH"] = LIBDIR
@ -49,8 +62,7 @@ def base_args():
args += [
"-cpu", "host", "-smp", SMP, "-m", MEM,
"-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}",
"-drive", f"if=pflash,format=raw,file={OVMF_VARS}",
"-drive", f"file={DISK},if=virtio,format=qcow2",
"-drive", f"if=pflash,format=raw,file={ovmf_vars}",
"-netdev", "user,id=n0", "-device", "virtio-net-pci,netdev=n0,romfile=",
"-device", "virtio-rng-pci", "-vga", "std", "-display", "none",
"-serial", "stdio", "-monitor", "none", "-no-reboot",
@ -58,38 +70,52 @@ def base_args():
return env, args
def spawn(args, env):
def spawn(args, env, log):
child = pexpect.spawn(QEMU, args, env=env, timeout=600,
encoding="utf-8", codec_errors="replace",
maxread=65536)
child.delaybeforesend = 0.3
child.logfile = log
return child
def do_install():
env, args = base_args()
def do_install(results, paths, disks):
env, args = base_args(str(paths.ovmf_vars))
for disk in disks:
args += ["-drive", f"file={disk},if=virtio,format=qcow2"]
args += ["-drive", f"file={ISO},media=cdrom,readonly=on",
"-kernel", KERNEL, "-initrd", INITRD, "-append", BLS_APPEND]
log = open(SERIAL_LOG, "w")
child = spawn(args, env)
child.logfile = log
log = open(paths.serial_log, "w")
child = spawn(args, env, log)
try:
child.expect(r"root@livecd[^\n]*# ", timeout=600)
results.pass_("live-shell")
url = os.environ.get("INSTALL_URL", "http://10.0.2.2:8000/install.sh")
child.sendline(f"curl -fsSL {url} -o /tmp/run.sh && bash /tmp/run.sh")
child.expect([r"===INSTALL-RC=([0-9]+)===", "===FETCH-FAIL===",
"Kernel panic", pexpect.EOF, pexpect.TIMEOUT], timeout=9000)
if "INSTALL-RC" in (child.after or ""):
print("INSTALL_RC", child.match.group(1), flush=True)
rc = child.match.group(1)
results.assert_true("install-rc-zero", rc == "0", f"INSTALL-RC={rc}")
else:
results.fail("install-rc-zero", "install did not report a status")
serial = paths.serial_log.read_text(errors="replace")
results.assert_true("no-secret-leak", "SECRET_LEAK_FOUND" not in serial,
"the guest reported a secret leak")
child.expect(["===POWEROFF===", pexpect.EOF, pexpect.TIMEOUT], timeout=600)
child.expect(pexpect.EOF, timeout=300)
except pexpect.TIMEOUT as exc:
results.fail("install", f"timeout: {exc}")
except pexpect.EOF:
results.fail("install", "unexpected EOF")
finally:
child.close(force=True)
log.close()
def do_boot():
env, args = base_args()
def do_boot(results, paths, disks):
env, args = base_args(str(paths.ovmf_vars))
for disk in disks:
args += ["-drive", f"file={disk},if=virtio,format=qcow2"]
args += ["-boot", "order=c"]
# The end marker is built with a command substitution so the shell's echo of
# the typed line does not itself contain it; otherwise `expect` would match
@ -101,13 +127,13 @@ def do_boot():
"systemctl --failed --no-pager; ip -brief addr; "
"lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; echo ===CHECKS-$(printf END)===",
)
log = open(SERIAL_LOG, "w")
child = spawn(args, env)
child.logfile = log
log = open(paths.serial_log, "w")
child = spawn(args, env, log)
try:
child.expect([r"[Pp]assphrase", r"login:"], timeout=300)
if "assphrase" in (child.after or ""):
child.sendline(LUKS_PW)
logged_in = False
for _ in range(5):
child.expect(r"phoebus login:", timeout=180)
child.sendline(USER)
@ -117,22 +143,51 @@ def do_boot():
child.sendline(USER_PW)
if child.expect([r"[$#] $", r"Login incorrect",
r"phoebus login:"], timeout=60) == 0:
logged_in = True
break
results.assert_true("detached-boot-login", logged_in, "could not log in")
child.sendline(checks)
checks_timeout = int(os.environ.get("CHECKS_TIMEOUT", "180"))
child.expect("===CHECKS-END===", timeout=checks_timeout)
print("checks complete", flush=True)
child.expect("===CHECKS-END===", timeout=int(os.environ.get("CHECKS_TIMEOUT", "180")))
serial = paths.serial_log.read_text(errors="replace")
results.assert_true("boot-systemd-running", "running" in serial,
"systemd did not report running")
except pexpect.TIMEOUT as exc:
results.fail("boot", f"timeout: {exc}")
except pexpect.EOF:
results.fail("boot", "unexpected EOF")
finally:
child.close(force=True)
log.close()
if __name__ == "__main__":
def main() -> int:
mode = sys.argv[1] if len(sys.argv) > 1 else ""
if mode == "install":
do_install()
elif mode == "boot":
do_boot()
else:
if mode not in ("install", "boot"):
print(__doc__)
sys.exit(2)
return 2
results = Results(f"serial-{mode}")
paths = vmsafety.make_run_paths(
f"serial-{mode}", base=os.environ.get("PHOEBUS_VM_STATE", "/var/tmp/phoebus-vm"),
ovmf_vars_template=OVMF_VARS_TEMPLATE,
)
try:
disks = vmsafety.validate_writable_drives(DISKS.split(","), disposable_dir())
except vmsafety.UnsafeDiskError as exc:
results.blocked("disposable-disk", str(exc))
results.write(paths.results_json)
print(f"harness error: {exc}", file=sys.stderr)
return 2
results.pass_("disposable-disk", ", ".join(str(d) for d in disks))
try:
if mode == "install":
do_install(results, paths, disks)
else:
do_boot(results, paths, disks)
finally:
results.write(paths.results_json)
print(results.summary(), flush=True)
return results.exit_code()
if __name__ == "__main__":
sys.exit(main())

View file

@ -0,0 +1,227 @@
#!/usr/bin/env python3
"""Unit tests for the VM harness safety and result logic.
These run on any host (no VM, no QEMU required) so the safety rules are checked
in CI, not only during a live install:
python3 installer/tests/vm/test_vmsafety.py
"""
from __future__ import annotations
import os
import socket
import subprocess
import tempfile
import threading
import unittest
from pathlib import Path
import vmsafety
from vmsafety import (
BLOCKED,
FAIL,
PASS,
Results,
UnsafeDiskError,
validate_disposable_disk,
validate_writable_drives,
)
def make_qcow2(path: Path, size: str = "8M") -> Path:
subprocess.run(
["qemu-img", "create", "-f", "qcow2", str(path), size],
check=True,
capture_output=True,
)
return path
class DisposableDiskTests(unittest.TestCase):
def setUp(self):
self._tmp = tempfile.TemporaryDirectory()
self.dir = Path(self._tmp.name)
def tearDown(self):
self._tmp.cleanup()
def test_rejects_dev_path(self):
with self.assertRaises(UnsafeDiskError):
validate_disposable_disk("/dev/sda", self.dir)
def test_rejects_block_device(self):
# /dev/loop-control or /dev/null are char/regular; the explicit /dev
# check fires first. Use a char device outside /dev to isolate.
with self.assertRaises(UnsafeDiskError):
validate_disposable_disk("/dev/null", self.dir)
def test_rejects_non_qcow2_regular_file(self):
raw = self.dir / "raw.img"
raw.write_bytes(b"\x00" * 4096)
with self.assertRaises(UnsafeDiskError):
validate_disposable_disk(raw, self.dir)
def test_rejects_qcow2_outside_test_dir(self):
outside = self.dir.parent / "outside-disposable.qcow2"
make_qcow2(outside)
self.addCleanup(outside.unlink)
with self.assertRaises(UnsafeDiskError):
validate_disposable_disk(outside, self.dir)
def test_rejects_symlink_escaping_test_dir(self):
target = self.dir.parent / "real-disk.qcow2"
make_qcow2(target)
self.addCleanup(target.unlink)
link = self.dir / "link.qcow2"
link.symlink_to(target)
with self.assertRaises(UnsafeDiskError):
validate_disposable_disk(link, self.dir)
def test_accepts_qcow2_inside_test_dir(self):
good = make_qcow2(self.dir / "good.qcow2")
self.assertEqual(validate_disposable_disk(good, self.dir), good)
def test_rejects_backing_chain_outside_test_dir(self):
backing = self.dir.parent / "backing.qcow2"
make_qcow2(backing)
self.addCleanup(backing.unlink)
overlay = self.dir / "overlay.qcow2"
subprocess.run(
["qemu-img", "create", "-f", "qcow2", "-b", str(backing), "-F", "qcow2",
str(overlay)],
check=True,
capture_output=True,
)
with self.assertRaises(UnsafeDiskError):
validate_disposable_disk(overlay, self.dir)
def test_accepts_backing_chain_inside_test_dir(self):
backing = make_qcow2(self.dir / "backing.qcow2")
overlay = self.dir / "overlay.qcow2"
subprocess.run(
["qemu-img", "create", "-f", "qcow2", "-b", str(backing), "-F", "qcow2",
str(overlay)],
check=True,
capture_output=True,
)
self.assertEqual(validate_disposable_disk(overlay, self.dir), overlay)
def test_rejects_root_as_test_dir(self):
good = make_qcow2(self.dir / "good.qcow2")
with self.assertRaises(UnsafeDiskError):
validate_disposable_disk(good, "/")
def test_validate_all_drives_not_just_disk(self):
a = make_qcow2(self.dir / "a.qcow2")
b = make_qcow2(self.dir / "b.qcow2")
checked = validate_writable_drives([a, "", None, b], self.dir)
self.assertEqual(checked, [a, b])
with self.assertRaises(UnsafeDiskError):
validate_writable_drives([a, "/dev/sdb"], self.dir)
class ResultsTests(unittest.TestCase):
def test_fail_sets_nonzero_exit(self):
results = Results("unit")
results.assert_true("ok", True)
results.assert_true("bad", False, "boom")
self.assertTrue(results.failed)
self.assertEqual(results.exit_code(), 1)
def test_all_pass_is_zero(self):
results = Results("unit")
results.assert_true("ok", True)
self.assertEqual(results.exit_code(), 0)
def test_blocked_only_fails_when_strict(self):
results = Results("unit", strict=False)
results.blocked("needs hardware", "no GPU")
self.assertEqual(results.exit_code(), 0)
strict = Results("unit", strict=True)
strict.blocked("needs hardware", "no GPU")
self.assertEqual(strict.exit_code(), 2)
def test_no_checks_is_not_run(self):
results = Results("unit")
self.assertEqual(results.counts()[vmsafety.NOT_RUN], 0)
self.assertEqual(results.exit_code(), 0)
self.assertEqual(results.summary().split(": ")[1], "no checks")
def test_write_round_trips(self):
results = Results("unit")
results.pass_("one")
path = results.write(self._tmp_results())
import json
data = json.loads(path.read_text())
self.assertEqual(data["scenario"], "unit")
self.assertEqual(data["counts"][PASS], 1)
self.assertEqual(data["exit_code"], 0)
def _tmp_results(self):
tmp = tempfile.NamedTemporaryFile(delete=False, suffix=".json")
tmp.close()
self.addCleanup(os.unlink, tmp.name)
return Path(tmp.name)
class FakeQmpServer(threading.Thread):
"""A tiny QMP server that records HMP commands and answers them."""
def __init__(self):
super().__init__(daemon=True)
self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
self.path = tempfile.mktemp(prefix="fake-qmp-", suffix=".sock")
self.sock.bind(self.path)
self.sock.listen(1)
self.commands = []
self.screendump_path = None
def run(self):
conn, _ = self.sock.accept()
with conn:
conn.sendall(b'{"QMP": {"version": {"qemu": {"major": 8}}}}' + b"\r\n")
reader = conn.makefile("rb")
writer = conn.makefile("wb")
for line in reader:
message = __import__("json").loads(line)
if message.get("execute") == "qmp_capabilities":
writer.write(b'{"return": {}}\r\n')
elif message.get("execute") == "human-monitor-command":
cmd = message["arguments"]["command-line"]
self.commands.append(cmd)
if cmd.startswith("screendump"):
# Emulate QEMU writing the file.
name = cmd.split(" ", 1)[1].strip().strip('"')
Path(name).write_bytes(b"P6 fake-ppm")
writer.write(b'{"return": ""}\r\n')
else:
writer.write(b'{"return": {}}\r\n')
writer.flush()
class QmpClientTests(unittest.TestCase):
def test_hmp_and_screendump(self):
server = FakeQmpServer()
server.start()
self.addCleanup(lambda: (server.sock.close(), os.path.exists(server.path) and os.unlink(server.path)))
deadline = 50
while not os.path.exists(server.path) and deadline:
deadline -= 1
with vmsafety.QmpClient(server.path) as client:
client.sendkey("ret")
# Wait until the fake server has created the file before returning.
target = Path(tempfile.mkdtemp()) / "shot with spaces.ppm"
client.hmp(f'screendump "{target}"')
# Give the server thread a moment to record the command.
for _ in range(50):
if len(server.commands) >= 2:
break
__import__("time").sleep(0.05)
self.assertTrue(any(cmd.startswith("sendkey ret") for cmd in server.commands))
self.assertTrue(any(cmd.startswith("screendump") for cmd in server.commands))
if __name__ == "__main__":
unittest.main(verbosity=2)

View file

@ -0,0 +1,492 @@
#!/usr/bin/env python3
"""Safety, structured-result and QEMU-control helpers for the VM harnesses.
The VM drivers are test equipment: their own safety rules must be enforced, not
merely documented. This module centralises those rules so every driver shares
one implementation:
* every writable disk must be a regular **qcow2** file inside an explicitly
designated disposable directory, with a backing chain that is fully inside
that directory. Block devices, ``/dev/*`` paths, character devices, unsafe
symlinks and writable storage outside the test area are rejected;
* each run gets its own writable OVMF variable file and monitor socket;
* screenshots and monitor commands are issued without a shell, with argument
arrays, over structured QMP where possible;
* results are structured (PASS/FAIL/BLOCKED/SKIPPED/NOT RUN) and a failed,
timed-out or incomplete run exits nonzero.
Nothing here depends on pexpect, so the safety logic is unit-testable on any
host (see ``test_vmsafety.py``).
"""
from __future__ import annotations
import dataclasses
import json
import os
import shutil
import socket
import stat
import subprocess
import sys
import time
import uuid
from pathlib import Path
# ---------------------------------------------------------------------------
# Statuses
# ---------------------------------------------------------------------------
PASS = "PASS"
FAIL = "FAIL"
BLOCKED = "BLOCKED"
SKIPPED = "SKIPPED"
NOT_RUN = "NOT RUN"
_TERMINAL = (PASS, FAIL, BLOCKED, SKIPPED)
class UnsafeDiskError(Exception):
"""A writable target violated the disposable-disk rules."""
class HarnessError(Exception):
"""A harness precondition failed (bad environment, unsafe path, ...)."""
# ---------------------------------------------------------------------------
# Structured results
# ---------------------------------------------------------------------------
@dataclasses.dataclass
class Check:
name: str
status: str
detail: str = ""
def to_dict(self) -> dict:
return {"name": self.name, "status": self.status, "detail": self.detail}
class Results:
"""A run's assertions and their outcome.
A check may be recorded once. ``assert_true`` records PASS or FAIL; the
helpers ``blocked``/``skip`` record those explicit states. Any FAIL (and,
when strict, any BLOCKED or NOT RUN) makes :meth:`exit_code` nonzero.
"""
def __init__(self, scenario: str, run_id: str | None = None, strict: bool | None = None):
self.scenario = scenario
self.run_id = run_id or new_run_id(scenario)
self.checks: list[Check] = []
if strict is None:
strict = os.environ.get("PHOEBUS_VM_STRICT", "").lower() in ("1", "yes", "true")
self.strict = bool(strict)
# -- recording ---------------------------------------------------------
def _add(self, name: str, status: str, detail: str) -> Check:
if status not in _TERMINAL:
raise ValueError(f"invalid result status: {status}")
check = Check(name=name, status=status, detail=detail)
self.checks.append(check)
stream = sys.stderr if status == FAIL else sys.stdout
print(f"[{status:<7}] {name}" + (f": {detail}" if detail else ""), file=stream, flush=True)
return check
def assert_true(self, name: str, condition: bool, detail: str = "") -> bool:
ok = bool(condition)
# `detail` describes the failure; never print it on a pass, which would
# make a passing check read as if it had failed.
self._add(name, PASS if ok else FAIL, "" if ok else detail)
return ok
def fail(self, name: str, detail: str = "") -> Check:
return self._add(name, FAIL, detail)
def pass_(self, name: str, detail: str = "") -> Check:
return self._add(name, PASS, detail)
def blocked(self, name: str, detail: str = "") -> Check:
return self._add(name, BLOCKED, detail)
def skip(self, name: str, detail: str = "") -> Check:
return self._add(name, SKIPPED, detail)
# -- outcome -----------------------------------------------------------
@property
def failed(self) -> bool:
return any(c.status == FAIL for c in self.checks)
@property
def has_blockers(self) -> bool:
return any(c.status == BLOCKED for c in self.checks)
@property
def not_run(self) -> bool:
return not self.checks or any(c.status == NOT_RUN for c in self.checks)
def counts(self) -> dict:
out = {s: 0 for s in (PASS, FAIL, BLOCKED, SKIPPED, NOT_RUN)}
for c in self.checks:
out[c.status] += 1
return out
def exit_code(self) -> int:
if self.failed:
return 1
if self.strict and (self.has_blockers or self.not_run):
return 2
return 0
def summary(self) -> str:
counts = self.counts()
parts = [f"{k}={v}" for k, v in counts.items() if v]
return f"{self.scenario} [{self.run_id}]: " + (", ".join(parts) if parts else "no checks")
def write(self, path: str | Path) -> Path:
path = Path(path)
path.parent.mkdir(parents=True, exist_ok=True)
payload = {
"scenario": self.scenario,
"run_id": self.run_id,
"strict": self.strict,
"exit_code": self.exit_code(),
"counts": self.counts(),
"checks": [c.to_dict() for c in self.checks],
}
path.write_text(json.dumps(payload, indent=2) + "\n")
return path
def new_run_id(scenario: str) -> str:
stamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
return f"{scenario}-{stamp}-{uuid.uuid4().hex[:8]}"
# ---------------------------------------------------------------------------
# Disposable disk rules
# ---------------------------------------------------------------------------
def _require_regular_and_safe(path: Path, test_dir: Path) -> os.stat_result:
text = str(path)
if text.startswith("/dev/") or text == "/dev":
raise UnsafeDiskError(f"refusing a /dev path: {text}")
# Symlink chains must stay inside the disposable directory when resolved.
real = Path(os.path.realpath(path))
if not _is_within(real, test_dir):
raise UnsafeDiskError(
f"writable disk resolves outside the disposable test directory "
f"({real} not under {test_dir})"
)
st = os.stat(path) # follows symlinks; realpath already checked containment
if stat.S_ISBLK(st.st_mode) or stat.S_ISCHR(st.st_mode):
raise UnsafeDiskError(f"refusing a block/character device: {text}")
if not stat.S_ISREG(st.st_mode):
raise UnsafeDiskError(f"refusing a non-regular file: {text}")
return st
def _is_within(child: Path, parent: Path) -> bool:
try:
child.relative_to(parent)
return True
except ValueError:
return False
def test_dir_is_safe(test_dir: Path) -> Path:
real = Path(os.path.realpath(test_dir))
if real == Path("/"):
raise UnsafeDiskError("the disposable test directory may not be /")
for bad in ("/dev", "/proc", "/sys"):
if real == Path(bad) or _is_within(real, Path(bad)):
raise UnsafeDiskError(f"the disposable test directory may not be under {bad}")
return real
def qcow2_magic(path: Path) -> bool:
try:
with open(path, "rb") as handle:
return handle.read(4) == b"QFI\xfb"
except OSError:
return False
def _qemu_img_backing_chain(path: Path) -> list[str]:
"""Return the backing-file paths reported by qemu-img (empty if none)."""
qemu_img = shutil.which("qemu-img")
if not qemu_img:
return []
proc = subprocess.run(
[qemu_img, "info", "--backing-chain", "--output=json", str(path)],
capture_output=True,
text=True,
)
if proc.returncode != 0:
return []
try:
data = json.loads(proc.stdout)
except json.JSONDecodeError:
return []
entries = data if isinstance(data, list) else [data]
chain: list[str] = []
for entry in entries:
for key in ("backing-filename", "full-backing-filename"):
value = entry.get(key)
if value:
chain.append(value)
return chain
def validate_disposable_disk(
path: str | os.PathLike,
test_dir: str | os.PathLike,
*,
require_qcow2: bool = True,
allow_missing: bool = False,
qemu_img: bool = True,
) -> Path:
"""Validate that ``path`` is a disposable qcow2 inside ``test_dir``.
Raises :class:`UnsafeDiskError` on any violation. On success returns the
resolved path.
"""
if path is None or str(path).strip() == "":
raise UnsafeDiskError("no writable disk path was provided")
test_real = test_dir_is_safe(Path(test_dir))
disk = Path(path)
if not disk.exists():
if allow_missing:
if not _is_within(Path(os.path.realpath(disk.parent)), test_real):
raise UnsafeDiskError(
f"new disk would be created outside the test directory: {disk}"
)
return disk
raise UnsafeDiskError(f"writable disk does not exist: {disk}")
st = _require_regular_and_safe(disk, test_real)
if st.st_size == 0:
raise UnsafeDiskError(f"writable disk is empty: {disk}")
if require_qcow2 and not qcow2_magic(disk):
raise UnsafeDiskError(
f"writable disk is not a qcow2 image (bad magic): {disk}; "
"refusing to hand a raw image to QEMU as writable"
)
if qemu_img:
for backing in _qemu_img_backing_chain(disk):
backing_real = Path(os.path.realpath(backing))
if not _is_within(backing_real, test_real):
raise UnsafeDiskError(
f"disk backing file is outside the test directory: {backing}"
)
if not os.access(disk, os.W_OK):
raise UnsafeDiskError(f"writable disk is not writable: {disk}")
return disk
def validate_writable_drives(paths, test_dir, *, qemu_img=True) -> list[Path]:
"""Validate every writable drive, not just one variable named DISK."""
checked = []
for path in paths:
if path is None or str(path).strip() == "":
continue
checked.append(validate_disposable_disk(path, test_dir, qemu_img=qemu_img))
if not checked:
raise UnsafeDiskError("no writable drives were provided to validate")
return checked
# ---------------------------------------------------------------------------
# Run-scoped state
# ---------------------------------------------------------------------------
@dataclasses.dataclass
class RunPaths:
run_id: str
directory: Path
serial_log: Path
monitor_sock: Path
shot_dir: Path
ovmf_vars: Path
results_json: Path
def ensure(self) -> "RunPaths":
self.directory.mkdir(parents=True, exist_ok=True)
os.chmod(self.directory, 0o700)
self.shot_dir.mkdir(parents=True, exist_ok=True)
os.chmod(self.shot_dir, 0o700)
return self
def make_run_paths(
scenario: str,
*,
base: str | os.PathLike | None = None,
ovmf_vars_template: str | os.PathLike | None = None,
run_id: str | None = None,
) -> RunPaths:
"""Create a private per-run directory and a fresh writable OVMF var file.
``base`` defaults to ``$PHOEBUS_VM_STATE`` or ``/var/tmp/phoebus-vm``.
"""
base_dir = Path(base or os.environ.get("PHOEBUS_VM_STATE", "/var/tmp/phoebus-vm"))
base_dir.mkdir(parents=True, exist_ok=True)
os.chmod(base_dir, 0o700)
run = new_run_id(scenario) if run_id is None else run_id
directory = base_dir / run
paths = RunPaths(
run_id=run,
directory=directory,
serial_log=directory / "serial.log",
monitor_sock=directory / "monitor.sock",
shot_dir=directory / "shots",
ovmf_vars=directory / "OVMF_VARS.fd",
results_json=directory / "results.json",
).ensure()
if ovmf_vars_template:
shutil.copyfile(ovmf_vars_template, paths.ovmf_vars)
os.chmod(paths.ovmf_vars, 0o600)
return paths
# ---------------------------------------------------------------------------
# Screenshots (no shell)
# ---------------------------------------------------------------------------
def _reject_control_chars(value: str) -> str:
if "\n" in value or "\r" in value or "\x00" in value:
raise HarnessError("path contains a control character")
return value
def convert_ppm(ppm: str | os.PathLike, png: str | os.PathLike) -> Path | None:
"""Convert a PPM to PNG with an argument array (never a shell)."""
png = Path(_reject_control_chars(str(png)))
for program in ("magick", "convert"):
binary = shutil.which(program)
if not binary:
continue
proc = subprocess.run([binary, str(ppm), str(png)], capture_output=True)
if proc.returncode == 0 and png.exists():
return png
return None
def screenshot_name(seq: int, slug: str) -> str:
safe = "".join(c if (c.isalnum() or c in "-_") else "-" for c in slug).strip("-")
return f"{seq:02d}-{safe or 'shot'}"
# ---------------------------------------------------------------------------
# QMP client
# ---------------------------------------------------------------------------
class QmpError(Exception):
pass
class QmpClient:
"""A minimal structured QMP client over a UNIX socket.
Uses JSON framing (the monitor protocol deletes shell/quoting concerns) and
issues HMP commands through ``human-monitor-command`` for ``screendump`` and
``sendkey``.
"""
def __init__(self, sock_path: str | os.PathLike, timeout: float = 20.0):
self.sock_path = str(sock_path)
self.timeout = timeout
def __enter__(self) -> "QmpClient":
if not os.path.exists(self.sock_path):
raise QmpError(f"monitor socket does not exist: {self.sock_path}")
self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
self.sock.settimeout(self.timeout)
self.sock.connect(self.sock_path)
self._file = self.sock.makefile("rwb")
greeting = self._read_json()
if "QMP" not in greeting:
raise QmpError("server did not send a QMP greeting")
self._command({"execute": "qmp_capabilities"})
return self
def __exit__(self, *_exc) -> None:
try:
self._file.close()
finally:
self.sock.close()
def _read_json(self) -> dict:
line = self._file.readline()
if not line:
raise QmpError("unexpected EOF from the QMP monitor")
try:
return json.loads(line)
except json.JSONDecodeError as exc:
raise QmpError(f"invalid QMP message: {line[:200]!r}") from exc
def _command(self, command: dict) -> dict:
self._file.write(json.dumps(command).encode() + b"\n")
self._file.flush()
while True:
message = self._read_json()
if "event" in message:
continue
if "error" in message:
raise QmpError(str(message["error"]))
return message
def hmp(self, command: str) -> str:
reply = self._command({"execute": "human-monitor-command", "arguments": {"command-line": command}})
return reply.get("return", "")
def screendump(self, target: str | os.PathLike) -> Path:
target = Path(_reject_control_chars(str(target)))
target.parent.mkdir(parents=True, exist_ok=True)
# QEMU's HMP screendump takes a single filename argument, so a path with
# spaces is quoted for QEMU's own tiny parser, not for a shell.
quoted = '"' + str(target).replace("\\", "\\\\").replace('"', '\\"') + '"'
self.hmp(f"screendump {quoted}")
deadline = time.monotonic() + self.timeout
while time.monotonic() < deadline:
if target.exists() and target.stat().st_size > 0:
return target
time.sleep(0.2)
raise QmpError(f"screendump did not produce {target}")
def sendkey(self, key: str) -> None:
self.hmp(f"sendkey {key}")
def screendump(monitor_sock, target, *, convert: bool = True) -> Path | None:
"""Capture the framebuffer and optionally convert it to PNG.
Returns the PPM path, or ``None`` if capture failed. Never raises for a
missing PNG converter (the PPM is still evidence).
"""
target = Path(_reject_control_chars(str(target)))
try:
with QmpClient(monitor_sock) as client:
ppm = client.screendump(target)
except (QmpError, OSError):
return None
if convert:
convert_ppm(ppm, ppm.with_suffix(".png"))
return ppm
def wait_for_file(path: str | os.PathLike, timeout: float, interval: float = 0.5) -> bool:
deadline = time.monotonic() + timeout
p = Path(path)
while time.monotonic() < deadline:
if p.exists():
return True
time.sleep(interval)
return False