From aec2b275c1cda42c2f15e302070909e597e12747 Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Sat, 22 Aug 2026 23:46:20 +0200 Subject: [PATCH] boot-repair: refuse shadow-file cleanup on BIOS systems with no ESP clean_shadow_files() assumed UEFI with an ESP mounted at /boot. On a BIOS/GRUB system with no ESP, /boot is a plain directory on the root filesystem holding the only kernel the machine has -- and neither existing guard catches it: findmnt /boot is empty (GUARD 1 passes) and there is no EFI/ or loader/ (GUARD 2 passes). boot-repair therefore read the real vmlinuz-linux and initramfs-linux.img as "orphaned kernel file(s) shadowing the ESP" and deleted them, leaving the machine unbootable. Measured 2026-08-22 in a vmbox BIOS/GRUB sandbox, not theorised: after sudo boot-repair the guest never booted again. GUARD 3: if /sys/firmware/efi does not exist the system booted via BIOS, so there is no ESP and nothing in /boot can be a shadow. warn + return 1, matching the existing guards' tone and exit convention. Overridable with the existing --esp DEVICE -- naming the ESP by hand asserts the firmware assumption the guard otherwise checks -- rather than adding a new flag. The check goes through rpath(), so a --root fixture declares its own firmware type and the case is testable without a VM. On the live UEFI machine it resolves to the real /sys path, so behaviour there is unchanged. Audit of the other BIOS-unsafe paths (none destructive, left alone): * mount_esp(): resolve_esp_device fails with no /boot fstab entry, so it reports and does not mount. Non-destructive. * sync_kernel_image()/rebuild_initramfs(): gated behind boot_is_mounted, which is false on BIOS, so they never write. * check_fstab_options(): reports "no /boot entry" -- noise on BIOS, but it writes nothing. * run_preflight(): aborts every kernel upgrade on a BIOS box. Fail-closed and non-destructive, so out of scope here. Tests: three cases in tests/lib/boot_repair_bios_cases.sh (new file; the existing case lib is at the 250-line cap) -- the guard refuses and explains, --esp overrides it, and a UEFI fixture still cleans shadows as before. Verified failing without the guard (38/4) and passing with it (42/0). Sandbox: BIOS guest keeps both kernel files, says why, and still boots afterwards (uname -r 7.1.9-arch1-2 after a clean poweroff). shellcheck clean. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3 --- .../boot-repair-bios-guard-2026-08-22.json | 67 ++++++++++++ .../scripts/boot_recovery/boot-repair | 28 ++++- .../tests/lib/boot_repair_bios_cases.sh | 103 ++++++++++++++++++ .../tests/lib/boot_repair_cases.sh | 7 ++ .../boot_recovery/tests/test_boot_repair.sh | 6 +- 5 files changed, 207 insertions(+), 4 deletions(-) create mode 100644 docs/superpowers/evidence/boot-repair-bios-guard-2026-08-22.json create mode 100755 linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_bios_cases.sh diff --git a/docs/superpowers/evidence/boot-repair-bios-guard-2026-08-22.json b/docs/superpowers/evidence/boot-repair-bios-guard-2026-08-22.json new file mode 100644 index 00000000..fd9cf54f --- /dev/null +++ b/docs/superpowers/evidence/boot-repair-bios-guard-2026-08-22.json @@ -0,0 +1,67 @@ +{ + "intent": "Stop boot-repair from deleting the only kernel on a BIOS/GRUB system that has no EFI System Partition, without changing its behaviour on kuhy's UEFI machine.", + "scope": [ + "linux_configuration/scripts/boot_recovery/boot-repair (clean_shadow_files, new system_is_uefi helper, header invariants, --esp help text)", + "linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_bios_cases.sh (new)", + "linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_cases.sh (make_root firmware parameter)", + "linux_configuration/scripts/boot_recovery/tests/test_boot_repair.sh (source + register the new cases)", + "Non-goal: fixing the other BIOS-unsafe-but-non-destructive paths (mount_esp, check_fstab_options, run_preflight) -- audited and left alone deliberately" + ], + "changes": [ + "Added GUARD 3 to clean_shadow_files(): when rpath(/sys/firmware/efi) is absent the system booted via BIOS, has no ESP, and /boot holds the real kernel -- warn and return 1 instead of deleting.", + "Added system_is_uefi(), expressed through rpath() so --root fixtures declare their own firmware type and the guard is testable without a VM; on ROOT=/ it resolves to the real /sys path.", + "Made the guard overridable via the existing --esp DEVICE rather than adding a new flag: naming the ESP by hand asserts the firmware assumption the guard checks.", + "Gave make_root() a third 'firmware' parameter defaulting to uefi (creates sys/firmware/efi), so the pre-existing UEFI-shaped fixtures keep their meaning.", + "Added three cases: BIOS guard refuses and explains, --esp overrides it, and a UEFI fixture still cleans shadows (regression guard for the no-behaviour-change requirement)." + ], + "verification": [ + { + "command": "linux_configuration/scripts/boot_recovery/tests/test_boot_repair.sh", + "result": "pass", + "evidence": "=== 42 passed, 0 failed === (was 33 before; +9 assertions across 3 new cases)" + }, + { + "command": "test_boot_repair.sh with GUARD 3 neutered (system_is_uefi() { return 0; }) in a scratch copy", + "result": "fail-as-expected", + "evidence": "=== 38 passed, 4 failed === -- fails 'explains why it refused', 'names the override', 'does not claim shadows', 'real initramfs preserved'. Proves the new case actually catches the bug rather than passing vacuously." + }, + { + "command": "vm new bg && vm run bg 'sudo /usr/local/sbin/boot-repair' (BIOS/GRUB sandbox)", + "result": "pass", + "evidence": "Guest confirmed BIOS-shaped first: no /sys/firmware/efi, no /boot fstab entry, findmnt /boot empty (GUARD 1 passes), no EFI//loader/ (GUARD 2 passes). boot-repair printed '[WARN] no /sys/firmware/efi -- this system booted via BIOS and has no ESP' and left /boot/vmlinuz-linux (17101312 b) and /boot/initramfs-linux.img (14957933 b) untouched. Exit 1 from the pre-existing 'no /boot entry in /etc/fstab' finding, which is BIOS noise, not a regression." + }, + { + "command": "vm run bg 'sudo systemctl poweroff' then vm run bg 'uname -r'", + "result": "pass", + "evidence": "Host-side VERDICT: clean poweroff (reached 'reboot: Power down'), then the guest booted again into 7.1.9-arch1-2 with both kernel files present. This is the exact scenario that previously left the guest permanently unbootable." + }, + { + "command": "vm run bg '~/tam/.../tests/test_boot_repair.sh'", + "result": "pass", + "evidence": "=== 42 passed, 0 failed === inside the BIOS guest as well as on the UEFI host." + }, + { + "command": "./boot-repair --dry-run (on the real UEFI host)", + "result": "pass", + "evidence": "No BIOS warning; '[ OK ] /boot mounted (/dev/nvme0n1p1)', ESP kernel and initramfs both OK. Confirms the required no-behaviour-change on kuhy's actual machine." + }, + { + "command": "shellcheck boot-repair tests/test_boot_repair.sh tests/lib/*.sh", + "result": "pass", + "evidence": "no findings" + }, + { + "command": "pre-commit run --files ", + "result": "pass", + "evidence": "all hooks pass, including the 250-line cap and shellcheck" + } + ], + "risks": [ + "A UEFI machine booted with efivars unavailable (e.g. an ISO rescue booted in legacy mode to repair a UEFI install) now refuses shadow cleanup. Mitigated by the --esp DEVICE override, which is named in the warning text itself.", + "The guard only covers the destructive path. A BIOS box still gets noisy FAIL lines from check_fstab_options and mount_esp, and run_preflight would abort kernel upgrades there. All are fail-closed and non-destructive; noted in the commit message rather than fixed, to keep this change narrow." + ], + "rollback": [ + "git revert the commit; boot-repair is self-contained and installed by copy, so re-run linux_configuration/scripts/boot_recovery/install.sh to push the reverted script to /usr/local/sbin.", + "After rollback, confirm ./boot-repair --dry-run on the UEFI host still reports '/boot mounted' and do NOT run it on any BIOS system -- the deletion bug is live again." + ] +} diff --git a/linux_configuration/scripts/boot_recovery/boot-repair b/linux_configuration/scripts/boot_recovery/boot-repair index ad555599..22478c0b 100755 --- a/linux_configuration/scripts/boot_recovery/boot-repair +++ b/linux_configuration/scripts/boot_recovery/boot-repair @@ -25,7 +25,8 @@ # # Safety invariants: # * Files under /boot are ONLY deleted while /boot is not a mountpoint AND -# contains no EFI/ or loader/ directory. Deleting them after mounting +# contains no EFI/ or loader/ directory AND the system booted via UEFI. +# Deleting them after mounting, or on a BIOS box that has no ESP at all, # would destroy the real kernel and leave the machine unbootable. # * EFI/ and loader/ on the ESP are never written or removed. # * The running kernel's module tree is never deleted. @@ -96,7 +97,10 @@ Options: only when it acts or fails. --root DIR Operate on an alternate root (testing, or an Arch ISO chroot). Live-only steps are skipped. - --esp DEVICE Use DEVICE as the ESP instead of auto-detecting it. + --esp DEVICE Use DEVICE as the ESP instead of auto-detecting it. Also + overrides the BIOS guard: on a system with no + /sys/firmware/efi, shadow-file cleanup is refused unless + the ESP device is named explicitly here. -h, --help Show this help. Exit status: @@ -243,6 +247,13 @@ boot_is_mounted() { findmnt -n "$ESP_MOUNTPOINT" > /dev/null 2>&1 } +# True when the system booted via UEFI, i.e. an ESP can exist at all. The +# kernel only creates /sys/firmware/efi when it was loaded by EFI firmware. +# +# Expressed via rpath so a fixture tree can declare its own firmware type; +# on the live machine this resolves to the real /sys path and is exact. +system_is_uefi() { [[ -d "$(rpath /sys/firmware/efi)" ]]; } + # ---------------------------------------------------------------------------- # Repair steps # ---------------------------------------------------------------------------- @@ -373,7 +384,7 @@ check_fstab_options() { # while the ESP was unmounted. They shadow the real ESP and waste ~250 MB. # # This is the single most dangerous step in the script: doing it after mounting -# would delete the real kernel. Hence the two hard guards below. +# would delete the real kernel. Hence the three hard guards below. clean_shadow_files() { local bootdir bootdir="$(rpath $ESP_MOUNTPOINT)" @@ -389,6 +400,17 @@ clean_shadow_files() { warn "unmounted $ESP_MOUNTPOINT contains EFI/ or loader/ — refusing to delete anything" return 1 fi + # GUARD 3: on a BIOS/GRUB system there is no ESP at all, so an unmounted + # /boot is not a shadow — it is the only kernel the machine has. Deleting it + # leaves the machine unbootable (measured 2026-08-22: a BIOS guest never + # booted again). --esp is the deliberate override: naming the device by hand + # asserts the firmware assumption that /sys/firmware/efi otherwise proves. + if ! system_is_uefi && [[ -z $ESP_DEV_OVERRIDE ]]; then + warn "no /sys/firmware/efi — this system booted via BIOS and has no ESP;" + warn " $ESP_MOUNTPOINT holds the real kernel. Refusing to delete anything." + warn " If that is wrong, name the ESP explicitly: $SCRIPT_NAME --esp DEVICE" + return 1 + fi local -a shadows=() local f diff --git a/linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_bios_cases.sh b/linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_bios_cases.sh new file mode 100755 index 00000000..f1eb74c9 --- /dev/null +++ b/linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_bios_cases.sh @@ -0,0 +1,103 @@ +#!/bin/bash + +# ============================================================================ +# boot-repair fixture cases: BIOS/GRUB firmware guard (GUARD 3). +# +# Split out of boot_repair_cases.sh, which is at the 250-line cap. Sourced by +# test_boot_repair.sh and relies on the helpers defined there (make_root, +# run_repair, assert_*). +# +# The bug these cover was measured on 2026-08-22 in a vmbox sandbox: on a +# BIOS/GRUB guest with no ESP, boot-repair read the real /boot/vmlinuz-linux +# and /boot/initramfs-linux.img as "orphaned kernel file(s) shadowing the ESP" +# and deleted them. The guest never booted again. +# ============================================================================ + +# A BIOS box, shaped exactly like the guest that lost its kernel: no +# sys/firmware/efi, and a /boot that holds the real kernel with no EFI/ or +# loader/ to trip GUARD 2. +make_bios_root() { + local name="$1" + local r + r="$(make_root "$name" 7.1.5-arch1-2 bios)" + + # GRUB keeps its kernel in a plain /boot directory on the root filesystem. + rm -rf "${r:?}/boot" + mkdir -p "$r/boot/grub" + printf 'Linux version 7.1.5-arch1-2 (linux@archlinux) fake image\n' \ + >"$r/boot/vmlinuz-linux" + printf 'usr/lib/modules/7.1.5-arch1-2/kernel/fs/fat/vfat.ko.zst\n' \ + >"$r/boot/initramfs-linux.img" + + # A BIOS system has no /boot entry in fstab; /boot is just part of /. + printf 'UUID=DEAD-BEEF\t/\text4\tdefaults\t0 1\n' >"$r/etc/fstab" + + printf '%s' "$r" +} + +test_bios_guard_refuses_to_delete_real_kernel() { + echo "TEST: SAFETY — BIOS/GRUB system without an ESP keeps its real kernel" + local r out + r="$(make_bios_root bios)" + + out="$(run_repair "$r")" + + assert_contains "explains why it refused" "$out" "this system booted via BIOS" + assert_contains "names the override" "$out" "--esp DEVICE" + assert_not_contains "does not claim shadows" "$out" "removed 2 shadow file" + + if [[ -f $r/boot/vmlinuz-linux ]]; then + pass "real kernel image preserved" + else + fail "real kernel image preserved" "boot-repair deleted the only kernel!" + fi + if [[ -f $r/boot/initramfs-linux.img ]]; then + pass "real initramfs preserved" + else + fail "real initramfs preserved" "boot-repair deleted the only initramfs!" + fi +} + +test_bios_guard_overridden_by_explicit_esp() { + echo "TEST: --esp DEVICE overrides the BIOS guard" + local r out + r="$(make_bios_root biosesp)" + + # Naming the ESP by hand asserts the firmware assumption the guard checks, + # so cleanup proceeds exactly as it would on a UEFI box. + out="$(run_repair "$r" --esp /dev/fake1)" + + assert_not_contains "guard is silent" "$out" "this system booted via BIOS" + assert_contains "treats the files as shadows" "$out" "orphaned kernel file" + + # initramfs-linux.img is not regenerated by a --root run, so its absence + # proves the deletion happened. (vmlinuz-linux legitimately reappears: + # sync_kernel_image reinstalls the target kernel straight afterwards.) + if [[ ! -f $r/boot/initramfs-linux.img ]]; then + pass "shadow initramfs deleted under --esp" + else + fail "shadow initramfs deleted under --esp" "guard did not yield to --esp" + fi +} + +# A UEFI fixture must keep behaving exactly as before — the guard must not +# change anything on kuhy's actual (UEFI) machine. +test_uefi_shadow_cleanup_still_works() { + echo "TEST: REGRESSION — UEFI system still cleans shadow files" + local r out + r="$(make_root uefishadow)" + rm -rf "${r:?}/boot" + mkdir -p "$r/boot" + printf 'Linux version 7.1.5-arch1-2 (linux@archlinux) fake\n' >"$r/boot/vmlinuz-linux" + printf 'stale\n' >"$r/boot/initramfs-linux-fallback.img" + + out="$(run_repair "$r")" + + assert_not_contains "guard stays out of the way" "$out" "this system booted via BIOS" + assert_contains "still detects shadows" "$out" "orphaned kernel file" + if [[ ! -f $r/boot/initramfs-linux-fallback.img ]]; then + pass "UEFI shadow deletion unchanged" + else + fail "UEFI shadow deletion unchanged" "guard blocked a legitimate cleanup" + fi +} diff --git a/linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_cases.sh b/linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_cases.sh index c7021994..f8c610cd 100755 --- a/linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_cases.sh +++ b/linux_configuration/scripts/boot_recovery/tests/lib/boot_repair_cases.sh @@ -13,13 +13,20 @@ # # Builds a consistent system: one complete kernel tree, an ESP whose kernel # and initramfs match it, a gating fstab and serial downloads. +# make_root [kver] [firmware] +# firmware: "uefi" (default) creates sys/firmware/efi, so boot-repair sees an +# ESP-capable system; "bios" omits it, which is what a GRUB/BIOS box looks like. make_root() { local name="$1" local r="$WORKROOT/$name" local kver="${2:-7.1.5-arch1-2}" + local firmware="${3:-uefi}" mkdir -p "$r/usr/lib/modules/$kver/kernel/fs/fat" mkdir -p "$r/boot" "$r/etc" "$r/var/cache/pacman/pkg" + if [[ $firmware == "uefi" ]]; then + mkdir -p "$r/sys/firmware/efi" + fi # Fake kernel image carrying the version banner boot-repair greps for. printf 'Linux version %s (linux@archlinux) fake image\n' "$kver" \ diff --git a/linux_configuration/scripts/boot_recovery/tests/test_boot_repair.sh b/linux_configuration/scripts/boot_recovery/tests/test_boot_repair.sh index 442da5dc..0bff341c 100755 --- a/linux_configuration/scripts/boot_recovery/tests/test_boot_repair.sh +++ b/linux_configuration/scripts/boot_recovery/tests/test_boot_repair.sh @@ -64,7 +64,8 @@ assert_eq() { # shellcheck source=lib/boot_repair_cases.sh source "$SCRIPT_DIR/lib/boot_repair_cases.sh" - +# shellcheck source=lib/boot_repair_bios_cases.sh +source "$SCRIPT_DIR/lib/boot_repair_bios_cases.sh" # ---------------------------------------------------------------------------- # Runner @@ -91,6 +92,9 @@ main() { test_fstab_nofail_fixed test_shadow_files_removed test_shadow_guard_refuses_real_esp + test_bios_guard_refuses_to_delete_real_kernel + test_bios_guard_overridden_by_explicit_esp + test_uefi_shadow_cleanup_still_works test_parallel_downloads_fixed test_missing_modules_dep test_no_kernel_at_all