#!/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, ...).""" class RedactingTextLog: """Write guest output without recording registered credentials. pexpect can split one echoed credential across reads, so redact complete terminal lines rather than each write call. The final fragment is flushed by ``finish`` when QEMU closes. Extremely long unterminated lines are discarded instead of risking an unbounded buffer or a partial secret. """ def __init__(self, sink, secrets): self.sink = sink self.secrets = tuple(sorted({s for s in secrets if s}, key=len, reverse=True)) self.pending = "" self.discarding = False def _redact(self, value): for secret in self.secrets: value = value.replace(secret, "[REDACTED]") return value def write(self, value): if not isinstance(value, str): value = str(value) self.pending += value while True: newline = self.pending.find("\n") carriage = self.pending.find("\r") endings = [at for at in (newline, carriage) if at >= 0] if not endings: break end = min(endings) + 1 line, self.pending = self.pending[:end], self.pending[end:] if self.discarding: self.discarding = False else: self.sink.write(self._redact(line)) if len(self.pending) > 1_000_000: self.sink.write("[REDACTED overlong serial line]\n") self.pending = "" self.discarding = True def flush(self): self.sink.flush() def finish(self): if self.pending and not self.discarding: self.sink.write(self._redact(self.pending)) self.pending = "" self.discarding = False self.sink.flush() # --------------------------------------------------------------------------- # 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, secrets=()): self.scenario = scenario self.run_id = run_id or new_run_id(scenario) self.checks: list[Check] = [] self.secrets = tuple(sorted({s for s in secrets if s}, key=len, reverse=True)) 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}") for secret in self.secrets: detail = detail.replace(secret, "[REDACTED]") 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 def validate_independent_disk_sets(first, second, test_dir) -> list[Path]: """Return validated second-install disks only when no image is reused.""" first_checked = validate_writable_drives(first, test_dir) second_checked = validate_writable_drives(second, test_dir) if {path.resolve() for path in first_checked} & { path.resolve() for path in second_checked }: raise UnsafeDiskError("second install resolves to a disk used by the first install") return second_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