The hardware list: what a listing says, who may vouch, and a check that holds each row to its report

build/config/image-programs.txt

@@ -1116,6 +1116,7 @@ usr/libexec/kryptik/dhcpcd-hook
 usr/libexec/kryptik/esp-records.sh
 usr/libexec/kryptik/eudev-trigger.sh
 usr/libexec/kryptik/firstboot.sh
+usr/libexec/kryptik/hw-report.sh
 usr/libexec/kryptik/image-store.sh
 usr/libexec/kryptik/installer-run.sh
 usr/libexec/kryptik/keyboard.sh
@@ -1215,6 +1216,7 @@ usr/sbin/integritysetup
 usr/sbin/ip
 usr/sbin/iw
 usr/sbin/kryptik-efiboot
+usr/sbin/kryptik-hwreport
 usr/sbin/kryptik-install
 usr/sbin/kryptik-recover
 usr/sbin/kryptik-update

build/recipes/hwreport.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# hwreport: a stage 04 recipe, sourced by build/stages/04-base-system.sh,
+# which runs it in the order its list gives.
+
+# kryptik-hwreport runs on the machine under test; here it only has to parse
+# and to head a report of an empty tree, not of the build machine.
+s_hwreport() {
+    local src="${KRYPTIK_ROOT}/tools/install/kryptik-hwreport.sh"
+    [[ -f "$src" ]] || { echo "no report tool at ${src}"; return 1; }
+    echo "source sha256: ${1:-unknown}"
+    install -D -m 0755 "$src" /usr/sbin/kryptik-hwreport
+    sh -n /usr/sbin/kryptik-hwreport || { echo "the report tool does not parse under the target sh"; return 1; }
+    local empty out
+    empty="$(mktemp -d)"
+    # Captured, not piped into head: pipefail would report the closed pipe.
+    out="$(KRYPTIK_HWREPORT_ROOT="$empty" /usr/sbin/kryptik-hwreport 2>&1 || true)"
+    rmdir "$empty"
+    case "$out" in
+        "kryptik-hwreport 1"*"== missing =="*"== kernel log =="*) echo "ok: kryptik-hwreport runs" ;;
+        *) echo "FAIL: kryptik-hwreport does not run: ${out}"; return 1 ;;
+    esac
+}

build/service-scripts/hw-report.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+# A hardware report onto the USB medium, for a stick whose first partition
+# carries a kryptik-report directory: whoever prepared it asked, and a machine
+# with no working screen or keyboard can still be reported on. No other stick
+# is written, nor a CD, nor an installed system. Never fails: the boot goes on.
+set -u
+. /usr/libexec/kryptik/devices.sh
+. /usr/libexec/kryptik/ask.sh
+
+grep -qs '^media=usb$' /run/kryptik/boot-identity || exit 0
+esp="$(kryptik_part kryptik-esp)" || exit 0
+[ -b "$esp" ] || exit 0
+
+look=/run/kryptik/hwreport-look
+mkdir -p "$look"
+# As FAT and nothing else, here and where the report is written: FAT holds no
+# links, so a prepared stick cannot send root's write anywhere but itself.
+mount -t vfat -o ro,nosuid,nodev,noexec "$esp" "$look" 2>/dev/null || exit 0
+asked=no
+[ -d "$look/kryptik-report" ] && asked=yes
+umount "$look"
+rmdir "$look" 2>/dev/null
+[ "$asked" = yes ] || exit 0
+
+echo "hw-report: this stick asks for a hardware report: one is written once the drivers have settled"
+# Drivers load at coldplug and ask for their firmware as they start; the ten
+# seconds are for the slow ones, so the log the report quotes has their words.
+/usr/sbin/udevadm settle --timeout=30 || true
+sleep 10
+if out="$(/usr/sbin/kryptik-hwreport --save 2>&1)"; then
+    tell "" "$out" "The report is on the stick: switch the machine off, or pull the stick." ""
+else
+    tell "" "$out" "No hardware report was written." ""
+fi
+exit 0

build/services/default/contents

@@ -12,6 +12,7 @@ power
 net-zone
 getty-tty1
 getty-tty2
+hw-report
 installer-run
 boot-success
 boot-smoke

build/services/hw-report/dependencies

@@ -0,0 +1,2 @@
+sysinit
+eudev-trigger

build/services/hw-report/type

@@ -0,0 +1 @@
+oneshot

build/services/hw-report/up

@@ -0,0 +1 @@
+/usr/libexec/kryptik/hw-report.sh

build/services/installer-run/dependencies

@@ -1,2 +1,3 @@
 sysinit
 eudev-trigger
+hw-report

build/stages/04-base-system.sh

@@ -207,6 +207,7 @@ PACKAGES=(
     "efiboot"     "s_efiboot $(sha256_of "${KRYPTIK_ROOT}/tools/efi/kryptik-efiboot.c" 2>/dev/null || echo none)"
     "netzone"     "s_netzone $(sha256_of "${KRYPTIK_ROOT}/tools/net/netzone-init.sh" 2>/dev/null || echo none)-$(sha256_of "${KRYPTIK_ROOT}/tools/net/sntp-offset.py" 2>/dev/null || echo none)-$(sha256_of "${KRYPTIK_ROOT}/tools/net/update-fetch.py" 2>/dev/null || echo none)"
     "installer"   "s_installer $(sha256_of "${KRYPTIK_ROOT}/tools/install/kryptik-install.sh" 2>/dev/null || echo none)"
+    "hwreport"    "s_hwreport $(sha256_of "${KRYPTIK_ROOT}/tools/install/kryptik-hwreport.sh" 2>/dev/null || echo none)"
     "stick"       "s_stick ${KRYPTIK_STICK_BIN:-none} $([[ -f "${KRYPTIK_STICK_BIN:-}" ]] && sha256_of "${KRYPTIK_STICK_BIN}" || echo absent)"
     # The binary's path and hash, and a digest of the zone files: kryptikd
     # validates them at install time, so the two must move together.

docs/hardware.md

@@ -0,0 +1,150 @@
+# Hardware
+
+Which machines Kryptik has been run on, who ran it, and what each run
+showed. The list is `docs/hardware/list.tsv`; beside it sits one report per
+row, made on the machine by `kryptik-hwreport`, and
+`tools/check-hardware.sh --list` holds every row to its report. The list is
+empty. Testing on physical hardware is planned for October 2026.
+
+What the kernel is built to drive is in the [README](../README.md#hardware).
+This page is about what was seen to work.
+
+## A report
+
+`kryptik-hwreport` prints what a machine is made of and what the image lacks
+for it: the maker and model, the firmware's Secure Boot state, the watchdogs
+and whether one reset the boot before, the processor and its microcode, every
+PCI and USB device with the driver that took it, the
+disks and the drivers under them, the display and each graphics controller's
+power state, the sound hardware, a laptop's
+backlights, batteries and what they draw, sleep states and camera parts,
+network and input
+devices, the loaded modules and the kernel log. Its `missing` section is
+the part to act on: the firmware the kernel asked for and did not find, each a
+line for `build/config/firmware.list`, and the devices and disks that want a
+driver's line in `build/config/kernel/boot.fragment`.
+
+Nothing in it is one machine's alone. No serial number is read, and the
+hardware addresses, serial numbers and UUIDs the kernel log prints are struck
+before the report is written. Read it before you send it all the same.
+
+There are two ways to take one:
+
+- **From the USB medium, with no keyboard or screen.** Write the image to a
+  stick, then make a folder named `kryptik-report` on the stick's first
+  partition, from any computer. Boot the stick on the machine, wait a minute
+  and switch off. The report is `kryptik-report/report-1.txt` on that
+  partition, and the next boot writes `report-2.txt`. A stick without the
+  folder is never written.
+- **By command.** At the medium's root shell, `kryptik-hwreport --save` writes
+  the same file. On an installed system, as root, `kryptik-hwreport > FILE`
+  writes the report where you say.
+
+## What a listing says
+
+| level | what its report shows |
+| --- | --- |
+| `reported` | The machine by maker and model, the release and the kernel that ran, and every section whole, from the medium or an installed system. It says what the machine has and what the image lacks for it, not that Kryptik works there. |
+| `certified` | All of that on an installed system: a release, not a dated build; booted by UEFI with Secure Boot on and the kernel locked down; the encrypted state partition in use; a display with an output connected; the default route leaving by a wired or wireless interface that has a carrier; and nothing under `missing`. |
+
+A `certified` row says that the release installs on that model, boots there
+with Secure Boot on, has a display to draw the desktop on and reaches a
+network. It does not speak for what the report does not exercise (sound,
+suspend, a camera), for Bluetooth, which 1.0 does not drive, for another
+firmware version, or for the same model sold with another network card: the
+report names the firmware version and every device, so a reader can compare.
+
+A listing also says what confines a device's DMA: the IOMMUs in use, and
+how a Thunderbolt port lets a device in, on a build with a Thunderbolt
+driver, which 1.0 is not. The kernel turns the IOMMU on and strict, but a
+machine whose firmware hides it boots all the same, with every device able
+to reach all of memory.
+
+A listing also names the machine's sound: its HD Audio codecs, and whether
+microphones sit on Intel's DSP or AMD's coprocessor, codecs on SoundWire
+(under HD Audio or behind AMD's coprocessor) or amplifiers in front of the
+speakers, each with what drives it. No level asks for any of it.
+
+Its `shstk` line says whether a program built for shadow stacks runs with
+one there: the kernel turns them on where the processor has them, Intel's
+from Tiger Lake and AMD's from Zen 3. The virtual machines that test each
+release have none, so only such a machine shows how a program built for
+them fares with a library built without. No level asks for it.
+
+Its `gpu` lines give each graphics controller's power state. Nothing here
+drives NVIDIA's graphics, and the kernel lets a device nothing drives sleep
+only once runtime PM is allowed it (`control auto`), so beside Intel's or
+AMD's on a laptop an NVIDIA chip stays powered, in D0. Only such a laptop
+shows what that costs its battery, which the report's `battery` lines give.
+No level asks for it.
+
+## Trying a laptop
+
+A listing's levels speak for installing, booting with Secure Boot, the display
+and the network. Much of what a laptop adds, the virtual machines that test
+each release cannot show ([status](status.md) says which parts wait for
+physical hardware). On a laptop, try these too, on the installed system, and
+let the row's note name what did not work:
+
+| try | what should happen |
+| --- | --- |
+| close the lid, then open it | the screen locks and the machine sleeps; it wakes to the lock asking for the state passphrase, and the zones carry on once it is typed |
+| the power key, and `kryptik suspend` | the same; the listing's `sleep` line says whether that sleep is deep or s2idle, and of a report taken after an s2idle sleep, whether that sleep reached the hardware's sleep state |
+| the touchpad | the pointer moves, a tap clicks, two fingers scroll, and typing stills it for a moment |
+| the brightness keys | the backlight steps up and down and never goes dark; of several, the kind the kernel prefers (firmware, then platform, then raw) |
+| the volume, mute and microphone keys | the volume steps, mutes, and the microphone is taken back, under the lock too |
+| a zone playing sound | the built-in speakers play it where the listing's `audio` line names an HD Audio codec and nothing beyond it |
+| unplug the mains, then plug it in | the menu's Power line follows, with the battery's charge |
+| a charger too weak for the machine, such as a phone's USB-C one | the Power line says on battery though plugged in, and the warnings at 10% and 5% come as they do unplugged |
+| on an AMD laptop whose `sleep` line says s2idle, a sleep of two minutes | it wakes to the lock, not to a fresh boot: the watchdog does not feed AMD's TCO timer there, as it would count through the sleep, and the report's line for it says inactive |
+| an SD card in the laptop's own reader | the window that asks which zone gets a stick opens, as for a USB stick |
+| a USB headset, plugged in while a zone plays, then `c` and a zone's number in the menu | it takes what the zone plays within a second, and records there once granted |
+| an external monitor on HDMI or DisplayPort, plugged in while the desktop runs | the desktop reaches it within seconds, and `kryptik display` lists it with its scale |
+| an external monitor on a laptop with two GPUs, an AMD one beside the built-in | it shows the desktop, whose frames wlroots copies to the second GPU's ports; dark, the row's note names both, as the listing's `display` line does |
+| a laptop with NVIDIA's graphics beside Intel's or AMD's | the desktop shows on the built-in screen; a monitor on a port the NVIDIA chip drives stays dark, as 1.0 drives none, and the listing's `gpu` line says whether that chip stayed powered |
+| a USB-C or Thunderbolt dock: its monitor, its USB ports and its Ethernet | the monitor shows where the laptop drives USB-C itself; a Thunderbolt or USB4 dock's own USB ports and Ethernet stay dark, as 1.0 builds no Thunderbolt driver, and the row's note says which worked |
+| closed on its dock, then the dock unplugged | it sleeps within seconds, as a lid closed undocked does |
+| the state passphrase at boot, typed on the built-in keyboard | it unlocks; a built-in keyboard that types nothing there is one on I2C, and a USB keyboard is the way through |
+| `k` and a zone's number in the menu, then a program there that records video | a USB camera records; one the listing's `camera` line puts behind an IPU does not, as 1.0 drives none |
+| a USB camera given to a zone with `k` and its number, then pulled out | the grant ends at once, and the menu's Camera line says no zone has it; plugged back in, it waits for `k` again |
+| Firefox in `untrusted`: Alt+p, its number and `b` | a window opens; where the listing's `shstk` line says yes, this is the only test of Firefox starting with shadow stacks on, and a failure names SHSTK in what it prints |
+
+A laptop that wakes from the lid and from `kryptik suspend` is the proof that
+the idle sleep, `~/.config/kryptik/lock-sleep`, waits for ([the user
+guide](user-guide.md)).
+
+## Who may vouch
+
+Whoever ran it on a machine in front of them. A row names them and the day,
+and they answer for the report being that machine's and unedited. For
+`certified` they installed from the release's own medium, checked as
+[releases](releases.md) describes, with the release's Secure Boot certificate
+enrolled, and took the report on the installed system.
+
+A row enters the list as a pull request that adds the report and its row. It
+is read by someone other than its author, who runs `tools/check-hardware.sh`
+on the report and compares what it prints with the row.
+
+## The list
+
+`docs/hardware/list.tsv` has one row per report:
+
+```text
+report  level  who  day  note
+```
+
+`report` is the file beside the list, named for the machine in lower case,
+such as `lenovo-thinkpad-x1-carbon-gen-9.txt`. `level` is `reported` or
+`certified`. `who` vouches, `day` is the day the report was taken, and the
+note says what a reader should know that the report cannot: a dock, a
+firmware setting that had to change. A machine that runs a later release gets
+a new report and a new row.
+
+`tools/check-hardware.sh REPORT` prints what a report shows and the level it
+carries, with each reason it falls short of `certified`. One line each says
+what confines a device's DMA, and what the machine's sound, laptop parts,
+sleep, camera and Bluetooth are and what drives them; no level asks for any
+of them yet. `--list` checks the
+whole list: every row's report is there and carries the level the row claims,
+was taken on the row's day and not in a virtual machine, no report holds a
+hardware address, a UUID or a serial number, and no report is without a row.

docs/hardware/list.tsv

@@ -0,0 +1,7 @@
+# Machines Kryptik has been run on (docs/hardware.md). Read by
+# tools/check-hardware.sh --list.
+#
+#   report  level  who  day  note
+#
+# report: the kryptik-hwreport file beside this list, which must carry the
+# level. level: reported or certified. who vouches, and the day it was taken.

docs/status.md

@@ -20,6 +20,7 @@ that ship, under QEMU with OVMF firmware.
 | Stage 05: hardened kernel | **tested**: the stage refuses a config that drops a fragment line, turns on an option a fragment sets off, or that kernel-hardening-checker faults beyond the accepted list; every VM suite boots the kernel (EFI stub, compiled-in command line with `CMDLINE_OVERRIDE`), `make integrity-test` its dm-init verity root, and `make zones-test` Landlock, seccomp, cgroup v2 and nftables' flow count on it. The count, which holds each routed zone to a share of the net zone's flow table, needs `NFT_CONNLIMIT` and so `NETFILTER_ADVANCED`, whose SCTP and UDP-Lite trackers the fragment keeps off |
 | Stage 06: install media and release payloads | **tested**: the firmware, install, integrity and update suites boot its USB image and ISO, whose kernels are signed with the build's Secure Boot key; the stage fails the build on any setuid bit or file capability its allowlists do not justify (`tools/tests/audit-setuid.sh`) and, in a development build given the statement key, checks that the image's trust anchor refuses a statement signed by the release key |
 | Firmware boot of the media | **tested**: `make media-smoke-usb` / `media-smoke-iso`, firmware discovery only (no `-kernel`, `-initrd`, `-append` or host filesystem; acceptance reads the recorded QEMU commands back) |
+| Hardware reports and the hardware list | **tested**: `tools/tests/hwreport.sh` runs `kryptik-hwreport` on made-up machines, the hardware addresses, serial numbers and UUIDs it strikes among its checks: one of each kind of laptop sound (HD Audio alone, microphones on Intel's DSP, SoundWire, AMD's coprocessor, amplifiers) and a laptop's backlights, batteries, sleep states and camera parts, a battery's serial number never read; acceptance's `hardware-report` item boots the USB medium under OVMF, where an unprepared stick stays byte for byte what it was, a prepared one gets a report and then a second, a write-protected one none, and an install from it leaves none on the disk; `tools/check-hardware.sh` holds each report to the listing it carries, `reported` or `certified`, and `docs/hardware/list.tsv` to its reports (`tools/tests/check-hardware.sh`, which CI runs on the tree's own list). Its lines for a laptop's sound, parts, sleep, camera and Bluetooth wait for the tests on physical hardware, as QEMU has none of them |
 | Installation and the state partition | **tested**: `make install-test` (install, boot alone, reboot, cold boot, the firmware's entry for slot a naming the ESP by its PARTUUID, no release named for the empty slot b, refusals including an injected I/O error and a disk with 4096-byte logical sectors), `make state-test` (first-boot setup answered at the console, a cloned disk, ambiguous labels, a corrupt or missing state partition: the system boots degraded and says so; `kryptik state passphrase` refusing a wrong current passphrase and a new one under 8 characters, then changing it), the medium's console suite `tools/image/medium-shell-test.sh` (with a NIC attached, no net zone starts and the NIC stays down in zone 0; typed at the medium's root shell: a dry run that writes nothing, a plan naming what each of the disk's partitions holds, ERASE and the passphrase asked before the first write and a passphrase under 8 characters refused, the refusal of a partition and of a disk with a partition mounted, used as swap or held open by device-mapper, then the user guide's install, state header backup and recovery as it gives them), `make keyboard-test` (the layout a firmware variable names loads before the passphrase is asked; a name this release lacks is said, and the passphrase asked under `us`) |
 | Boot integrity | **tested**: `make media-smoke-secureboot`, `make media-refused-foreign-keys` (Microsoft keys refuse the medium), `make integrity-test` (a foreign-signed boot file refused and put back by `kryptik-recover --commit-slot`, a tampered root refused by dm-verity, recovery from the medium with state intact, also when the disk's ESP no longer mounts, and the state partition's header saved, wiped and put back) |
 | Zones, network and encrypted storage on the installed kernel | **tested**: `make zones-test`, running `zones-check.sh` (the net zone associating over a `mac80211_hwsim` radio; its DHCP client split into an unprivileged user's processes, with no capability in an empty root, and a helper that stays its root; its DNS server as nobody with only `CAP_NET_BIND_SERVICE`, and its clock query and update fetcher with no capability; its CPU limit read back, and each routed zone's share of its flow table measured; a NIC it renamed, readdressed or gave altnames, and a radio it left stations on, reaching the next net zone reset; the installed root's setuid bits and file capabilities against the allowlists, and every sysctl read back) and the compartment suites as root on the Kryptik kernel |