Compare commits

..

No commits in common. "fb4dcc5683bc17cb713c1ddf0e396cf6046c157b" and "7e9fa9c2a306027e63b7cf81d9a955a2a7c488bb" have entirely different histories.

28 changed files with 406 additions and 3148 deletions

View file

@ -8,15 +8,14 @@
SHELL := /bin/bash SHELL := /bin/bash
.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 .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
help: help:
@printf 'Phoebus OS targets:\n' @printf 'Phoebus OS targets:\n'
@printf ' make context session briefing (state, roadmap, handoff)\n' @printf ' make context session briefing (state, roadmap, handoff)\n'
@printf ' make doctor check host prerequisites\n' @printf ' make doctor check host prerequisites\n'
@printf ' make test run the Rust and VM-harness test suites\n' @printf ' make test run the Rust test suite\n'
@printf ' make test-rust cargo test --workspace\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 fmt cargo fmt --all\n'
@printf ' make check fmt-check + clippy + tests\n' @printf ' make check fmt-check + clippy + tests\n'
@printf ' make build release Rust installer\n' @printf ' make build release Rust installer\n'
@ -36,14 +35,11 @@ context:
doctor: doctor:
scripts/doctor.sh scripts/doctor.sh
test: test-rust test-vm test: test-rust
test-rust: test-rust:
cd installer-rs && cargo test --workspace cd installer-rs && cargo test --workspace
test-vm:
python3 installer/tests/vm/test_vmsafety.py
fmt: fmt:
cd installer-rs && cargo fmt --all cd installer-rs && cargo fmt --all

View file

@ -7,65 +7,6 @@ Format: Keep a Changelog. Dates are UTC.
## Unreleased ## 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 ### Added
- **Graphical installation experience.** The live ISO now boots into a branded - **Graphical installation experience.** The live ISO now boots into a branded
Phoebus welcome window (`phoebus-welcome`) that makes "Install Phoebus OS" the Phoebus welcome window (`phoebus-welcome`) that makes "Install Phoebus OS" the

View file

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

View file

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

View file

@ -1,66 +0,0 @@
# 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,43 +552,6 @@ 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 pinning `loader.conf` to the newest real kernel entry and giving the recovery
entry `sort-key zzzz-phoebus-recovery`; unit tests pin both. 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 ## Known remaining work
- The graphical session was verified with the **headless** wlroots backend - The graphical session was verified with the **headless** wlroots backend
@ -602,13 +565,3 @@ against a deliberately unauthenticated LAN bind.
- Desktop USE still does not match the signed binhost, so the desktop - Desktop USE still does not match the signed binhost, so the desktop
transaction compiles a large amount from source (~26 minutes for the desktop transaction compiles a large amount from source (~26 minutes for the desktop
package set on 8 vCPUs in the test VM). 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

@ -1,66 +0,0 @@
# 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,7 +15,5 @@ and link it here.
| [0007](0007-coherent-rollback.md) | Coherent rollback and recovery | Accepted | | [0007](0007-coherent-rollback.md) | Coherent rollback and recovery | Accepted |
| [0008](0008-nix-isolation-lifecycle.md) | Nix lifecycle, build isolation, and packaging | 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 | | [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. Format: Context / Decision / Consequences / Status.

View file

@ -183,41 +183,6 @@ 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 instructions given to the model. They are deliberately explicit about
/// the closed action set and the evidence requirement. /// the closed action set and the evidence requirement.
pub const SYSTEM_PROMPT: &str = "\ pub const SYSTEM_PROMPT: &str = "\
@ -392,7 +357,11 @@ pub fn complete_proposal_at(
"no AI provider selected".into(), "no AI provider selected".into(),
)); ));
} }
validate_endpoint(endpoint)?; if endpoint.trim().is_empty() {
return Err(AiError::ProviderUnavailable(
"no provider endpoint configured".into(),
));
}
facts.validate_no_forbidden()?; facts.validate_no_forbidden()?;
let request = build_request(provider, model, facts); let request = build_request(provider, model, facts);
let body = serde_json::to_string(&request)?; let body = serde_json::to_string(&request)?;
@ -519,18 +488,6 @@ mod tests {
assert!(complete_proposal_at(ProviderKind::Local, "", "", &facts(), &transport).is_err()); 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] #[test]
fn request_has_no_secret_and_pins_the_schema() { fn request_has_no_secret_and_pins_the_schema() {
let request = build_request(ProviderKind::DeepSeek, "", &facts()); let request = build_request(ProviderKind::DeepSeek, "", &facts());

View file

@ -68,34 +68,7 @@ impl TargetRoot {
self.resolve(&format!("home/{relative}")) 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> { pub fn ensure_dir(&self, relative: &str) -> Result<PathBuf> {
self.reject_symlink_components(relative)?;
let path = self.resolve(relative)?; let path = self.resolve(relative)?;
std::fs::create_dir_all(&path).map_err(|e| CoreError::io(path.clone(), e))?; std::fs::create_dir_all(&path).map_err(|e| CoreError::io(path.clone(), e))?;
Ok(path) Ok(path)
@ -111,7 +84,6 @@ impl TargetRoot {
} }
pub fn write(&self, relative: &str, contents: impl AsRef<[u8]>) -> Result<PathBuf> { pub fn write(&self, relative: &str, contents: impl AsRef<[u8]>) -> Result<PathBuf> {
self.reject_symlink_components(relative)?;
let path = self.resolve(relative)?; let path = self.resolve(relative)?;
if let Some(parent) = path.parent() { if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).map_err(|e| CoreError::io(parent.to_path_buf(), e))?; std::fs::create_dir_all(parent).map_err(|e| CoreError::io(parent.to_path_buf(), e))?;
@ -168,39 +140,4 @@ mod tests {
assert!(p.starts_with(dir.path())); assert!(p.starts_with(dir.path()));
assert_eq!(t.read_to_string("etc/fstab").unwrap(), "hello"); 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,9 +77,6 @@ impl ModelTransport for CurlTransport<'_> {
url: &str, url: &str,
body: &str, body: &str,
) -> std::result::Result<String, AiError> { ) -> 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 { if self.sandboxed {
return self.send_sandboxed(url, body); return self.send_sandboxed(url, body);
} }
@ -99,20 +96,13 @@ impl ModelTransport for CurlTransport<'_> {
Some(key) => format!("header = \"Authorization: Bearer {}\"\n", key.expose()), Some(key) => format!("header = \"Authorization: Bearer {}\"\n", key.expose()),
None => String::new(), 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!( let config = format!(
"url = \"{url}\"\n\ "url = \"{url}\"\n\
proto = \"=http,https\"\n\
header = \"Content-Type: application/json\"\n\ header = \"Content-Type: application/json\"\n\
{auth}\ {auth}\
data = \"@{path}\"\n\ data = \"@{path}\"\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", path = request.path().display()
path = request.path().display(),
max = phoebus_ai::provider::MAX_RESPONSE_BYTES,
); );
let spec = CommandSpec::new("ai", "query model", "curl") let spec = CommandSpec::new("ai", "query model", "curl")
.args(["-sS", "-K", "-"]) .args(["-sS", "-K", "-"])
@ -137,13 +127,10 @@ impl CurlTransport<'_> {
let escaped = body.replace('\\', "\\\\").replace('"', "\\\""); let escaped = body.replace('\\', "\\\\").replace('"', "\\\"");
let config = format!( let config = format!(
"url = \"{url}\"\n\ "url = \"{url}\"\n\
proto = \"=http,https\"\n\
header = \"Content-Type: application/json\"\n\ header = \"Content-Type: application/json\"\n\
{auth}\ {auth}\
data = \"{escaped}\"\n\ 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( let out = crate::sandbox::run(
self.exec, self.exec,
@ -220,62 +207,6 @@ mod tests {
assert_eq!(exec.redactor().redact("sk-secret-value"), "<redacted>"); 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] #[test]
fn curl_transport_omits_auth_without_a_key() { fn curl_transport_omits_auth_without_a_key() {
let runner = RecordingRunner::new(); let runner = RecordingRunner::new();

View file

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

View file

@ -1,490 +0,0 @@
//! 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,12 +347,10 @@ fn live_source_disks(runner: &dyn ProcessRunner) -> Vec<String> {
} }
pub fn probe_disks(runner: &dyn ProcessRunner) -> Vec<Disk> { 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( let out = capture(
runner, runner,
"lsblk", "lsblk",
&["-bdn", "-P", "-o", "NAME,MODEL,SIZE,TRAN,RM,RO"], &["-dn", "-P", "-o", "NAME,MODEL,SIZE,TRAN,RM,RO"],
); );
let mounts = read_mounts(); let mounts = read_mounts();
let live = live_source_disks(runner); let live = live_source_disks(runner);
@ -482,9 +480,6 @@ mod tests {
assert!(sr.is_protected()); assert!(sr.is_protected());
let vda = disks.iter().find(|d| d.path == "/dev/vda").unwrap(); let vda = disks.iter().find(|d| d.path == "/dev/vda").unwrap();
assert!(!vda.is_protected()); 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] #[test]

View file

@ -30,11 +30,6 @@ use serde_json::{json, Value};
pub const PROTOCOL_VERSION: u32 = 1; pub const PROTOCOL_VERSION: u32 = 1;
const MAX_LOG_TAIL: usize = 200; 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 // Protocol types
@ -166,11 +161,6 @@ pub struct Bridge {
api_key: Option<SecretString>, api_key: Option<SecretString>,
approved_digest: Option<String>, approved_digest: Option<String>,
phase: std::rc::Rc<std::cell::Cell<DiskPhase>>, 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, quit: bool,
} }
@ -185,8 +175,6 @@ impl Bridge {
api_key: None, api_key: None,
approved_digest: None, approved_digest: None,
phase: std::rc::Rc::new(std::cell::Cell::new(DiskPhase::BeforeStorage)), phase: std::rc::Rc::new(std::cell::Cell::new(DiskPhase::BeforeStorage)),
installing: false,
installed: false,
quit: false, quit: false,
} }
} }
@ -201,8 +189,6 @@ impl Bridge {
api_key: None, api_key: None,
approved_digest: None, approved_digest: None,
phase: std::rc::Rc::new(std::cell::Cell::new(DiskPhase::BeforeStorage)), phase: std::rc::Rc::new(std::cell::Cell::new(DiskPhase::BeforeStorage)),
installing: false,
installed: false,
quit: false, quit: false,
} }
} }
@ -218,15 +204,6 @@ impl Bridge {
if line.is_empty() { if line.is_empty() {
return Ok(()); 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) { let request: Request = match serde_json::from_str(line) {
Ok(request) => request, Ok(request) => request,
Err(e) => { Err(e) => {
@ -422,19 +399,6 @@ impl Bridge {
.secrets .secrets
.as_ref() .as_ref()
.ok_or_else(|| "set_secrets requires a `secrets` object".to_string())?; .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 { if let Some(v) = &patch.luks {
let s = SecretString::new(v.clone()); let s = SecretString::new(v.clone());
self.installer.exec.register_secret(&s); self.installer.exec.register_secret(&s);
@ -533,16 +497,6 @@ impl Bridge {
request: &Request, request: &Request,
out: &mut dyn Write, out: &mut dyn Write,
) -> Result<Value, String> { ) -> 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. // The plan may not have changed since the user approved it.
let current = self.plan_digest(); let current = self.plan_digest();
match (&self.approved_digest, &request.plan_digest) { match (&self.approved_digest, &request.plan_digest) {
@ -599,10 +553,6 @@ impl Bridge {
phase: self.phase.clone(), phase: self.phase.clone(),
}; };
self.phase.set(DiskPhase::BeforeStorage); 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( let outcome = self.installer.install_observed(
&auth, &auth,
self.luks.as_ref(), self.luks.as_ref(),
@ -610,12 +560,9 @@ impl Bridge {
self.root_password.as_ref(), self.root_password.as_ref(),
&mut observer, &mut observer,
); );
self.installing = false;
match outcome { match outcome {
Ok(()) => { Ok(()) => Ok(json!({
self.installed = true;
Ok(json!({
"complete": true, "complete": true,
"dry_run": dry_run, "dry_run": dry_run,
"log_path": self.installer.exec.log_path().display().to_string(), "log_path": self.installer.exec.log_path().display().to_string(),
@ -623,8 +570,7 @@ impl Bridge {
"Remove the installation medium.", "Remove the installation medium.",
"Restart the computer and boot Phoebus OS.", "Restart the computer and boot Phoebus OS.",
], ],
})) })),
}
Err(e) => { Err(e) => {
let message = self.installer.exec.redactor().redact(&e.to_string()); let message = self.installer.exec.redactor().redact(&e.to_string());
let (disk_changed, next_actions) = disk_change_report(self.phase.get()); let (disk_changed, next_actions) = disk_change_report(self.phase.get());
@ -1204,75 +1150,4 @@ mod tests {
assert_eq!(response(&lines)["data"]["bye"], json!(true)); assert_eq!(response(&lines)["data"]["bye"], json!(true));
assert!(bridge.should_quit()); 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,12 +120,6 @@ struct Cli {
/// (stdin/stdout). Not intended for direct interactive use. /// (stdin/stdout). Not intended for direct interactive use.
#[arg(long, hide = true)] #[arg(long, hide = true)]
gui_bridge: bool, 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; struct TerminalConfirm;
@ -281,19 +275,6 @@ fn run() -> std::result::Result<ExitCode, Box<dyn std::error::Error>> {
return Ok(ExitCode::SUCCESS); 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 { if let Some(name) = &cli.emit_asset {
return match phoebus_core::system::desktop_asset(name) { return match phoebus_core::system::desktop_asset(name) {
Some(text) => { Some(text) => {

View file

@ -242,74 +242,6 @@ 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( fn storage_prepare(
&mut self, &mut self,
auth: &phoebus_executor::DestructiveAuthorization, auth: &phoebus_executor::DestructiveAuthorization,
@ -324,7 +256,6 @@ impl Installer {
self.state.luks_uuid = Some("<luks-uuid>".into()); self.state.luks_uuid = Some("<luks-uuid>".into());
return Ok(()); return Ok(());
} }
self.revalidate_target_disk()?;
storage::prepare( storage::prepare(
&self.exec, &self.exec,
&self.config, &self.config,
@ -629,12 +560,6 @@ impl Installer {
Ok(()) 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 /// 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. /// recovery does not depend on the (possibly later broken) live root.
fn create_initial_recovery_point(&self, auth: &phoebus_executor::DestructiveAuthorization) { fn create_initial_recovery_point(&self, auth: &phoebus_executor::DestructiveAuthorization) {
@ -681,99 +606,3 @@ 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,44 +226,3 @@ fn installer_help_is_available_to_the_gui() {
assert!(help.contains("deterministic `sys`")); assert!(help.contains("deterministic `sys`"));
assert!(help.contains("installation medium")); 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,10 +200,7 @@ ShellRoot {
} }
if (s === 2) { if (s === 2) {
if (!shell.aiConnected) { if (!shell.aiConnected) {
// Show the guidance beside the AI controls, not only in the shell.status = "Connect and validate an AI model before continuing.";
// footer, so the fix is obvious.
shell.aiError = "Connect and validate a model before continuing.";
shell.status = "";
return; return;
} }
saveAndAdvance(); saveAndAdvance();
@ -463,25 +460,9 @@ ShellRoot {
shell.advance(); shell.advance();
} }
Timer {
id: windowFocusTimer
interval: 700
repeat: false
running: false
onTriggered: {
if (typeof window.requestActivate === "function")
window.requestActivate();
page.forceActiveFocus();
}
}
FloatingWindow { FloatingWindow {
id: window id: window
Component.onCompleted: { Component.onCompleted: { if (typeof window.requestActivate === "function") window.requestActivate(); }
if (typeof window.requestActivate === "function")
window.requestActivate();
windowFocusTimer.start();
}
visible: true visible: true
color: Theme.charcoal color: Theme.charcoal
implicitWidth: 980 implicitWidth: 980
@ -510,12 +491,6 @@ ShellRoot {
shell.back(); shell.back();
event.accepted = true; event.accepted = true;
} else if (event.key === Qt.Key_Escape) { } else if (event.key === Qt.Key_Escape) {
// 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(); shell.closeInstaller();
event.accepted = true; event.accepted = true;
} else if (event.key === Qt.Key_Return || event.key === Qt.Key_Enter) { } else if (event.key === Qt.Key_Return || event.key === Qt.Key_Enter) {
@ -920,7 +895,6 @@ ShellRoot {
visible: shell.phase === "progress" 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 { 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: "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 { Rectangle {
id: progressTrack id: progressTrack
width: parent.width; height: 6; radius: 3; color: Theme.border width: parent.width; height: 6; radius: 3; color: Theme.border

View file

@ -48,28 +48,9 @@ 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 { FloatingWindow {
id: window id: window
Component.onCompleted: { Component.onCompleted: { if (typeof window.requestActivate === "function") window.requestActivate(); }
if (typeof window.requestActivate === "function")
window.requestActivate();
focusTimer.start();
}
visible: true visible: true
color: Theme.charcoal color: Theme.charcoal
implicitWidth: 940 implicitWidth: 940
@ -186,7 +167,6 @@ ShellRoot {
spacing: 20 spacing: 20
PhoebusButton { PhoebusButton {
id: installButton
label: "Install Phoebus OS" label: "Install Phoebus OS"
primary: true primary: true
implicitHeight: 58 implicitHeight: 58

View file

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

View file

@ -4,595 +4,306 @@
The live medium boots into Mango + DankMaterialShell and opens the branded The live medium boots into Mango + DankMaterialShell and opens the branded
welcome window. This driver boots it with a graphical device and a serial welcome window. This driver boots it with a graphical device and a serial
console, checks the launcher/branding payload, drives the graphical installer console, checks the launcher/branding payload, drives the graphical installer
over the live session, and captures QEMU framebuffer screenshots through QMP. with `wtype` over the live session, and captures QEMU framebuffer screenshots.
Modes: Modes:
gui : boot, log in on serial, verify the welcome/branding payload, open gui : boot, log in on serial, verify the welcome/branding payload, open
the installer from the welcome action, prove duplicate prevention, the installer, prove duplicate prevention, walk the first steps and
walk the wizard steps and capture screenshots. capture screenshots.
install : boot, log in on serial, fetch a non-interactive config and 0600 install : boot, log in on serial, fetch a non-interactive config and 0600
secrets over QEMU user networking, run the deterministic install secrets over QEMU user networking, run the deterministic install
with the static binary, scan the log for a secret leak, power off. 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 boot : boot the installed disk alone (no ISO), unlock LUKS, log in and run
verification commands. verification commands.
Safety: every writable drive must be a qcow2 file inside the disposable `DISK` must always be a disposable qcow2 image. This script never touches a
directory named by `PHOEBUS_VM_DISKS` (default physical disk.
`$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 os
import re import socket
import shutil
import sys import sys
import time import time
from pathlib import Path
import pexpect import pexpect
import vmsafety
from vmsafety import BLOCKED, FAIL, PASS, Results, HarnessError
QEMU = os.environ.get("QEMU_BIN", "qemu-system-x86_64") QEMU = os.environ.get("QEMU_BIN", "qemu-system-x86_64")
OVMF_CODE = os.environ["OVMF_CODE"] OVMF_CODE = os.environ["OVMF_CODE"]
OVMF_VARS_TEMPLATE = os.environ["OVMF_VARS"] OVMF_VARS = os.environ["OVMF_VARS"]
ISO = os.environ.get("ISO", "") ISO = os.environ.get("ISO", "")
DISKS = os.environ.get("DISKS") or os.environ.get("DISK", "") DISK = os.environ.get("DISK", "")
SERVE_URL = os.environ.get("SERVE_URL", "http://10.0.2.2:8000") 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")
LIVE_USER = os.environ.get("LIVE_USER", "phoebus") LIVE_USER = os.environ.get("LIVE_USER", "phoebus")
LIVE_PW = os.environ.get("LIVE_PASSWORD", "phoebus") LIVE_PW = os.environ.get("LIVE_PASSWORD", "phoebus")
USER = os.environ.get("USERNAME", "phoebus") USER = os.environ.get("USERNAME", "phoebus")
USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test") USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test")
LUKS_PW = os.environ.get("LUKS_PASSPHRASE", "phoebus-luks-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") MEM = os.environ.get("VM_MEM", "8192")
SMP = os.environ.get("VM_SMP", "8") SMP = os.environ.get("VM_SMP", "8")
BOOT_TIMEOUT = int(os.environ.get("BOOT_TIMEOUT", "900")) BOOT_TIMEOUT = int(os.environ.get("BOOT_TIMEOUT", "900"))
INSTALL_TIMEOUT = int(os.environ.get("INSTALL_TIMEOUT", "10800")) INSTALL_TIMEOUT = int(os.environ.get("INSTALL_TIMEOUT", "10800"))
SESSION_SETTLE = int(os.environ.get("SESSION_SETTLE", "20"))
BACKEND_SETTLE = int(os.environ.get("BACKEND_SETTLE", "30")) WAYLAND_ENV = "XDG_RUNTIME_DIR=/run/user/1000"
def _template_dir() -> Path: def args(attach_iso=True, boot_disk=False):
return Path( a = [
os.environ.get("PHOEBUS_VM_STATE", "/var/tmp/phoebus-vm")
)
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", "-machine", "q35,accel=kvm",
"-cpu", "host", "-smp", SMP, "-m", MEM, "-cpu", "host", "-smp", SMP, "-m", MEM,
"-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}", "-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}",
"-drive", f"if=pflash,format=raw,file={self.paths.ovmf_vars}", "-drive", f"if=pflash,format=raw,file={OVMF_VARS}",
] ]
for disk in self.disks: if DISK:
args += ["-drive", f"file={disk},if=virtio,format=qcow2"] a += ["-drive", f"file={DISK},if=virtio,format=qcow2"]
args += [ a += [
# A real GPU device so the compositor gets a DRM node and a seat. # A real GPU device so the compositor gets a DRM node and a seat.
"-device", "virtio-gpu-pci", "-device", "virtio-gpu-pci",
"-netdev", "user,id=n0", "-device", "virtio-net-pci,netdev=n0,romfile=", "-netdev", "user,id=n0", "-device", "virtio-net-pci,netdev=n0,romfile=",
"-device", "virtio-rng-pci", "-device", "virtio-rng-pci",
] ]
if attach_iso and ISO: if attach_iso and ISO:
args += ["-drive", f"file={ISO},media=cdrom,readonly=on"] a += ["-drive", f"file={ISO},media=cdrom,readonly=on"]
args += [ a += [
"-boot", "order=c" if boot_disk else "order=d", "-boot", "order=c" if boot_disk else "order=d",
"-vga", "none", "-display", "none", "-vga", "none", "-display", "none",
"-serial", "stdio", "-serial", "stdio",
"-qmp", f"unix:{self.paths.monitor_sock},server,nowait", "-monitor", f"unix:{MONITOR},server,nowait",
"-no-reboot", "-no-reboot",
] ]
return args return a
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 spawn(attach_iso=True, boot_disk=False):
def run_id(self) -> str: if os.path.exists(MONITOR):
return self.paths.run_id 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 shot(
self, def screendump(name):
slug: str, """Capture the QEMU framebuffer to SHOT_DIR/<name>.ppm (and .png if
ui_state: str, ImageMagick is available)."""
action: str, os.makedirs(SHOT_DIR, exist_ok=True)
expected: str, target = os.path.join(SHOT_DIR, name + ".ppm")
observed: str | None = None, if not os.path.exists(MONITOR):
) -> 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 return None
ok = False s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.settimeout(20)
try: try:
with vmsafety.QmpClient(self.paths.monitor_sock) as client: s.connect(MONITOR)
client.screendump(ppm) time.sleep(0.5)
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: try:
index = self.child.expect(patterns, timeout=timeout) s.recv(65536)
except pexpect.TIMEOUT as exc: except socket.timeout:
self.results.fail(label, f"timeout after {timeout}s") pass
raise HarnessError(f"timeout: {label}") from exc s.sendall(b"screendump %s\n" % target.encode())
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) 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: try:
with vmsafety.QmpClient(self.paths.monitor_sock) as client: s.recv(65536)
getattr(client, action)(*args, **kwargs) except socket.timeout:
except Exception as exc: # noqa: BLE001 pass
self.results.fail(f"qmp-{action}", str(exc)) finally:
raise 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 sendkey(self, *keys: str) -> None:
for key in keys:
self.qmp("sendkey", key)
time.sleep(0.2)
# -- guest login ------------------------------------------------------- def login_live(child):
def login_live(self) -> None: # The live serial getty shows `<hostname> login:` and the password is the
assert self.child is not None # known live-only credential.
idx = self.expect([r"login:", r"[$#] $"], timeout=BOOT_TIMEOUT, label="live-login-prompt") idx = child.expect([r"login:", r"[$#] $"], timeout=BOOT_TIMEOUT)
if idx == 0: if idx == 0:
self.child.sendline(LIVE_USER) child.sendline(LIVE_USER)
self.expect(r"[Pp]assword:", timeout=90, label="live-password-prompt") child.expect(r"[Pp]assword:", timeout=90)
self.child.sendline(LIVE_PW) child.sendline(LIVE_PW)
self.expect(r"[$#] $", timeout=180, label="live-shell") child.expect(r"[$#] $", timeout=180)
self.results.pass_("live-login")
def set_wayland(self) -> None:
out = self.shell( 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 XDG_RUNTIME_DIR=/run/user/1000; '
'export WAYLAND_DISPLAY="$(basename "$(ls /run/user/1000/wayland-* 2>/dev/null | head -1)")"; ' 'export WAYLAND_DISPLAY="$(basename "$(ls /run/user/1000/wayland-* 2>/dev/null | head -1)")"; '
'echo WAYLAND=$WAYLAND_DISPLAY', 'echo WAYLAND=$WAYLAND_DISPLAY'
r"WAYLAND=wayland-\d+",
timeout=60,
label="wayland-session",
) )
self.results.pass_("wayland-session", out.strip()[-40:]) child.expect(r"WAYLAND=wayland-\d+", timeout=60)
# -- modes -------------------------------------------------------------
def run(self) -> int: 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: try:
if self.mode == "gui": s.connect(MONITOR)
self.do_gui() time.sleep(0.3)
elif self.mode == "install": try:
self.do_install() s.recv(65536)
elif self.mode == "boot": except socket.timeout:
self.do_boot() pass
else: for k in keys:
print(__doc__) s.sendall(("sendkey %s\n" % k).encode())
return 2 time.sleep(0.2)
except HarnessError as exc: time.sleep(0.3)
self.results.fail("harness", str(exc)) try:
except Exception as exc: # noqa: BLE001 s.recv(65536)
self.results.fail("harness-exception", repr(exc)) except socket.timeout:
pass
finally: finally:
if self.spawned: s.close()
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
# -- GUI journey ------------------------------------------------------- def key(child, *wtype_args):
def do_gui(self) -> None: quoted = " ".join(f"'{a}'" for a in wtype_args)
self.spawn(attach_iso=True, boot_disk=False) child.sendline(f"wtype {quoted} >/dev/null 2>&1; echo KEY-DONE")
self.login_live() child.expect("KEY-DONE", timeout=60)
welcome = self.poll_shell(
"echo WELCOME=$(pgrep -fc 'quickshell.*phoebus-welcome' 2>/dev/null || echo 0)", def do_gui():
r"WELCOME=([1-9][0-9]*)", child = spawn()
timeout=int(os.environ.get("WELCOME_TIMEOUT", "180")), log = open(SERIAL_LOG, "w")
label="welcome-window", 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)"
) )
self.results.assert_true( child.expect(r"WELCOME=(\d+)", timeout=60)
"welcome-autostarted", welcome is not None, "welcome window did not appear" if int(child.match.group(1)) > 0:
) break
self.shot("01-welcome", "welcome window", "observe at startup", time.sleep(5)
"branded welcome window with a dominant Install action") # 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 = ( checks = (
"echo ===GUI-CHECKS-$(printf START)===; " "echo ===GUI-CHECKS-$(printf START)===; "
"test -e /etc/phoebus/live && echo LIVE-$(printf MARKER); " "test -e /etc/phoebus/live && echo LIVE-MARKER; "
"test -s /usr/share/phoebus/branding/wallpaper.svg && echo BRAND-$(printf WALLPAPER); " "test -s /usr/share/phoebus/branding/wallpaper.svg && echo BRAND-WALLPAPER; "
"test -s /usr/share/icons/hicolor/scalable/apps/phoebus.svg && echo BRAND-$(printf ICON); " "test -s /usr/share/icons/hicolor/scalable/apps/phoebus.svg && echo BRAND-ICON; "
"test -s /etc/xdg/quickshell/phoebus-install/shell.qml && echo INSTALL-$(printf QML); " "test -s /etc/xdg/quickshell/phoebus-install/shell.qml && echo INSTALL-QML; "
"test -s /usr/share/applications/phoebus-install.desktop && echo DESKTOP-$(printf ENTRY); " "test -s /usr/share/applications/phoebus-install.desktop && echo DESKTOP-ENTRY; "
"test -f /home/phoebus/.config/DankMaterialShell/.firstlaunch && echo ONBOARDING-$(printf SUPPRESSED); " "test -f /home/phoebus/.config/DankMaterialShell/.firstlaunch && echo ONBOARDING-SUPPRESSED; "
"echo ===GUI-CHECKS-$(printf END)===" "echo ===GUI-CHECKS-$(printf END)==="
) )
payload = self.shell(checks, "===GUI-CHECKS-END===", timeout=180, label="payload-checks") live_shell(child, checks, "===GUI-CHECKS-END===", timeout=180)
for marker in ( shot = screendump("01-welcome")
"LIVE-MARKER", "BRAND-WALLPAPER", "BRAND-ICON", "INSTALL-QML", "DESKTOP-ENTRY", print("welcome screenshot:", shot, flush=True)
):
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() set_wayland(child)
# Backend disk protection on the real VM: the live medium must be
# Disk protection is a deterministic backend property. The bridge JSON # reported protected and never selectable.
# is long and the serial console wraps it, so a small guest-side summary child.sendline(
# 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\"}' " "printf '%s\\n%s\\n' '{\"id\":1,\"op\":\"disks\"}' '{\"id\":2,\"op\":\"quit\"}' "
"> /tmp/req.json; echo REQ-$(printf DONE)", "| sudo -n /usr/local/bin/phoebus-installer --gui-bridge 2>/dev/null "
"REQ-DONE", "| head -1 > /tmp/disks.json; "
timeout=30, "echo DISKS=$(wc -c </tmp/disks.json); cat /tmp/disks.json"
label="disk-probe-request",
) )
summary = self.shell( child.expect(r"DISKS=(\d+)", timeout=120)
"sudo -n /usr/local/bin/phoebus-installer --gui-bridge < /tmp/req.json " print("disks probe bytes:", child.match.group(1), flush=True)
"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). # Activate the focused "Install Phoebus OS" button with Return. This is
# Retry a few times; a transient focus race must not be recorded as a # the real launcher-to-installer journey (no shell shortcut).
# passing launcher test, and the fallback launch is recorded as a FAIL. sendkey("ret")
self.shot("01b-focus", "welcome focused", "before launcher key", time.sleep(8)
"primary Install action visibly focused") child.sendline("echo INST=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)")
installed = None child.expect(r"INST=(\d+)", timeout=60)
for _attempt in range(3): if int(child.match.group(1)) == 0:
self.sendkey("ret") # The window manager may not have focused the welcome; fall back to
installed = self.poll_shell( # the launcher so the rest of the journey can still be exercised.
"echo INST=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)", child.sendline(
r"INST=([1-9][0-9]*)", "setsid /usr/local/bin/phoebus-install >/tmp/install-gui.log 2>&1 & echo LAUNCHED"
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) time.sleep(7)
else: # Surface the installer frontend's own log (it contains bridge errors).
self.results.pass_("launcher-opens-installer", "welcome action opened the installer") child.sendline(
# The frontend log must not contain bridge errors or a crash.
logdump = self.shell(
"echo QMLLOG-$(printf START); " "echo QMLLOG-$(printf START); "
"cat /run/user/1000/quickshell/by-id/*/log.qslog 2>/dev/null | " "cat /run/user/1000/quickshell/by-id/*/log.qslog 2>/dev/null | "
"grep -aiE 'phoebus-bridge|error|failed|handshake' | tail -30; " "grep -aiE 'phoebus-bridge|error|failed|sudo|handshake' | tail -30; "
"echo QMLLOG-$(printf END)", "echo NOTTY-SUDO; setsid sh -c 'sudo -n true' ; echo NOTTYSUDO=$?; "
"QMLLOG-END", "echo QMLLOG-$(printf END)"
timeout=60,
label="frontend-log",
) )
hard = [ln for ln in logdump.splitlines() child.expect("QMLLOG-END", timeout=60)
if "phoebus-bridge:" in ln and "error" in ln.lower()] screendump("02-installer-language")
self.results.assert_true("frontend-no-bridge-errors", not hard, "; ".join(hard[:3])) # The first handshake probes hardware and disks; wait for it before
# driving the wizard so the backend is ready to validate.
self.shot("02-installer-start", "installer wizard", "opened from the welcome", time.sleep(int(os.environ.get("BACKEND_SETTLE", "30")))
"language and region step with visible focus") # Close the welcome so the installer window has the keyboard focus
time.sleep(BACKEND_SETTLE) # (Mango tiles both windows; the welcome would otherwise receive keys).
child.sendline("pkill -f 'quickshell.*phoebus-wel[c]ome' || true; sleep 2; echo CLOSED")
# Close the welcome so the tiled installer holds the keyboard. child.expect("CLOSED", timeout=30)
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. # Duplicate prevention: a second launch must not create a second session.
self.shell( child.sendline(
"pgrep -f 'quickshell.*phoebus-install' | wc -l > /tmp/n1; " "pgrep -f 'quickshell.*phoebus-install' | wc -l > /tmp/n1; "
"/usr/local/bin/phoebus-install >/tmp/install-gui2.log 2>&1; " "/usr/local/bin/phoebus-install >/tmp/install-gui2.log 2>&1; "
"pgrep -f 'quickshell.*phoebus-install' | wc -l > /tmp/n2; " "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",
)
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"DUP n1=(\d+) n2=(\d+)", timeout=60)
print("duplicate check:", child.match.group(0), flush=True)
# Keyboard-walk the wizard, capturing each step. # Move forward through the wizard with the keyboard shortcut.
for slug, state in [ sendkey("ctrl-right")
("03-network", "network and prerequisites"),
("04-ai-model", "AI model connection"),
]:
self.sendkey("ctrl-right")
time.sleep(2) time.sleep(2)
self.shot(slug, state, "Ctrl+Right", "next wizard step") screendump("03-network-prerequisites")
if not self._installer_alive(): sendkey("ctrl-right")
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) time.sleep(2)
self.shot("06-ai-blocked", "AI model blocked", "Ctrl+Right without a model", screendump("04-ai-model")
"advance refused; no install started") # Advancing without a connected model must be refused (blocked prereq).
blocked = self._bridge_has_no_install_start() sendkey("ctrl-right")
self.results.assert_true( time.sleep(2)
"ai-step-blocks-install", blocked, screendump("05-ai-blocked")
"the AI step allowed advancement without a connected model", print("gui checks complete", flush=True)
) finally:
self.results.pass_("gui-walk-completed") child.close(force=True)
log.close()
def _installer_alive(self) -> bool:
assert self.child is not None def do_install():
self.child.sendline( child = spawn()
"echo ALIVE=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)" log = open(SERIAL_LOG, "w")
) child.logfile = log
try: try:
self.child.expect(r"ALIVE=(\d+)", timeout=30) login_live(child)
except (pexpect.TIMEOUT, pexpect.EOF): child.sendline(
return False f"curl -fsSL {SERVE_URL}/appliance-guest-gui.sh -o /tmp/gi.sh && bash /tmp/gi.sh"
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",
) )
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)
else: else:
self.results.skip("live-medium-protected", "no live medium in the probe") 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()
# -- 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")
# -- detached boot ----------------------------------------------------- def do_boot():
def do_boot(self) -> None: # Detached: no ISO, boot from the installed disk only.
if not self.disks: child = spawn(attach_iso=False, boot_disk=True)
self.results.blocked("boot-disk", "no writable disk configured") log = open(SERIAL_LOG, "w")
return child.logfile = log
self.spawn(attach_iso=False, boot_disk=True)
checks = os.environ.get( checks = os.environ.get(
"BOOT_CHECKS", "BOOT_CHECKS",
"echo ===CHECKS-$(printf START)===; " "echo ===CHECKS-$(printf START)===; "
@ -600,49 +311,36 @@ class Driver:
"systemctl --failed --no-pager; ip -brief addr; " "systemctl --failed --no-pager; ip -brief addr; "
"lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; echo ===CHECKS-$(printf END)===", "lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; echo ===CHECKS-$(printf END)===",
) )
assert self.child is not None try:
idx = self.expect([r"[Pp]assphrase", r"login:"], timeout=BOOT_TIMEOUT, label="boot-prompt") child.expect([r"[Pp]assphrase", r"login:"], timeout=BOOT_TIMEOUT)
if idx == 0: if "assphrase" in (child.after or ""):
self.child.sendline(LUKS_PW) child.sendline(LUKS_PW)
logged_in = False
for _ in range(5): for _ in range(5):
try: child.expect(r"phoebus login:", timeout=300)
self.child.expect(r"phoebus login:", timeout=300) child.sendline(USER)
except (pexpect.TIMEOUT, pexpect.EOF): idx = child.expect([r"[Pp]assword:", r"phoebus login:", r"Login incorrect"],
break timeout=60)
self.child.sendline(USER) if idx == 0:
choice = self.child.expect( child.sendline(USER_PW)
[r"[Pp]assword:", r"phoebus login:", r"Login incorrect"], timeout=60 if child.expect([r"[$#] $", r"Login incorrect", r"phoebus login:"],
)
if choice == 0:
self.child.sendline(USER_PW)
if self.child.expect([r"[$#] $", r"Login incorrect", r"phoebus login:"],
timeout=120) == 0: timeout=120) == 0:
logged_in = True
break break
self.results.assert_true("detached-boot-login", logged_in, "could not log in") child.sendline(checks)
self.shell(checks, "===CHECKS-END===", child.expect("===CHECKS-END===", timeout=int(os.environ.get("CHECKS_TIMEOUT", "300")))
timeout=int(os.environ.get("CHECKS_TIMEOUT", "300")), label="boot-checks") print("checks complete", flush=True)
serial = self.paths.serial_log.read_text(errors="replace") finally:
self.results.assert_true( child.close(force=True)
"boot-systemd-running", "running" in serial, "systemd did not report running" log.close()
)
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__": if __name__ == "__main__":
sys.exit(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)

View file

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

View file

@ -1,227 +0,0 @@
#!/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

@ -1,492 +0,0 @@
#!/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