Shorten the build's runner messages and comments; report every missing firmware pattern

build/config/artifact-accepted.txt

@@ -1,8 +1,5 @@
-# Findings of tools/check-artifact-hardening.sh that the image keeps, each with
-# its reason: `FINDING PATH # why`, or `RPATH PATH RPATH # why`, since an RPATH
-# entry accepts one rpath. PATH and RPATH are globs on the object's path in the
-# image and on its rpath. A finding not listed here fails --strict, and so does
-# an entry that no longer matches anything.
+# Findings of tools/check-artifact-hardening.sh the image keeps, as globs: `FINDING PATH # why`
+# or `RPATH PATH RPATH # why`. --strict fails on an unlisted finding and on a stale entry.
 
 NO-CET  usr/bin/kryptikd                        # stable rustc marks nothing for CET, nor does the std it links
 NO-CET  usr/bin/kryptik-wlproxy                 # the same

build/config/capability-allowlist.txt

@@ -1,4 +1,2 @@
-# Files allowed to carry file capabilities (security.capability) in a Kryptik
-# image; stage 06 removes them from every other file in its root
-# (tools/audit-setuid.sh --strip). Nothing in the image needs one yet.
+# Files allowed file capabilities; stage 06 strips the rest (tools/audit-setuid.sh --strip).
 #   /absolute/path   # justification

build/config/firmware.list

@@ -1,17 +1,10 @@
 # The only firmware shipped under /lib/firmware on the verified root (ADR-012).
-# One `find -path` pattern per line, matched in the tree linux-firmware's
-# copy-firmware.sh lays out; a selected link brings its target.
-# `newest N PATTERN` keeps the N highest trailing -NUMBERs per device, since a
-# driver falls back only a few firmware API versions. A pattern that matches
-# nothing fails the build.
+#   PATTERN            a `find -path` pattern in copy-firmware.sh's layout; a link brings its target
+#   newest N PATTERN   only the N highest trailing -NUMBERs (API versions) per device
+# A pattern that matches nothing fails the build.
 
-# Intel Wi-Fi: the newest three API versions per device, and every PNVM.
-# Not the version MODULE_FIRMWARE names, on purpose: the driver loads the
-# highest one inside its MAC's range intersected with its RF's (iwl-drv.c), so
-# AX210 with a gf radio declares -100 and loads -89, and the newest parts try
-# cNN names, which newest-N keeps whole, before NN ones. Picking exactly takes
-# that logic and a real card to test on. The glob also keeps the DVM parts'
-# firmware, about 2 MB this kernel cannot load, rather than a way to exclude it.
+# Intel Wi-Fi: three API versions per device, as which one loads depends on MAC and RF (iwl-drv.c).
+# The glob also keeps about 2 MB of DVM firmware this kernel cannot load.
 newest 3 iwlwifi-*.ucode
 iwlwifi-*.pnvm
 
@@ -42,8 +35,7 @@ rtlwifi/rtl8188eufw.bin
 # Broadcom over PCIe (Dell and Apple machines); the SDIO parts are not.
 brcm/brcmfmac*-pcie*
 
-# Graphics: all of Intel's and AMD's. Not NVIDIA: nouveau's GSP firmware is tens
-# of MB per generation, and the firmware framebuffer still gives a display.
+# Graphics: Intel and AMD, not NVIDIA (GSP firmware is tens of MB; the framebuffer still works).
 i915/*
 xe/*
 amdgpu/*

build/config/hardening-exceptions.txt

@@ -1,6 +1,4 @@
-# Packages exempted from part of the hardening flag set:
-#   <package>  <flag-to-drop>  # justification
-# An entry without a justification fails the build. Say what breaks and what
-# you tried; exceptions are meant to be removed, not accumulated.
+# Packages exempted from a hardening flag; an entry without a justification fails the build.
+#   <package>  <flag-to-drop>  # what breaks, and what was tried
 
-glibc  -D_FORTIFY_SOURCE=3  # glibc DEFINES the fortify machinery; fortifying it against itself fails to build
+glibc  -D_FORTIFY_SOURCE=3  # glibc provides the fortify machinery; fortifying it against itself fails to build

build/config/hardening.env

@@ -1,10 +1,6 @@
-# Hardening flags for the target packages; docs/hardening.md has the reasons.
-# Loaded by stage 04 only: stages 01 and 02 build the compiler that implements
-# these flags, and set no flags at all.
+# Hardening flags for the target packages, loaded by stage 04; docs/hardening.md has the reasons.
 
-# No -fPIE or -pie: GCC is built with --enable-default-pie, so executables are
-# PIE anyway, and -pie links Scrt1.o into shared libraries, which then fail on
-# an undefined main.
+# No -fPIE or -pie: GCC defaults to PIE, and -pie breaks shared libraries (Scrt1.o, undefined main).
 
 # _FORTIFY_SOURCE needs -O1 or more; -O2 is the tested level.
 KRYPTIK_OPT="-O2"
@@ -29,6 +25,5 @@ export CFLAGS="${KRYPTIK_OPT} ${KRYPTIK_CFLAGS_HARDENING}"
 export CXXFLAGS="${KRYPTIK_OPT} ${KRYPTIK_CFLAGS_HARDENING}"
 export LDFLAGS="${KRYPTIK_LDFLAGS_HARDENING}"
 
-# Packages exempted from some flags. Each needs a justification, which
-# validate_hardening_exceptions in build/lib/common.sh enforces.
+# Per-package flag exemptions, each with the justification validate_hardening_exceptions enforces.
 KRYPTIK_HARDENING_EXCEPTIONS="build/config/hardening-exceptions.txt"

build/config/kernel/checker-accepted.txt

@@ -1,13 +1,8 @@
-# kernel-hardening-checker failures on the resolved config and the shipped
-# command line that Kryptik accepts, each with its reason:
+# kernel-hardening-checker failures Kryptik accepts, read by tools/check-kernel-hardening.sh:
 #   <kconfig|cmdline|sysctl>  <option>   # <why it stays>
-# tools/check-kernel-hardening.sh fails on an unlisted failure or an entry
-# without a reason, and reports an entry that now passes so it can go.
-# The checker's decision column names who recommends a setting: kspp (Kernel
-# Self-Protection Project), clipos, grsec, maintainer, a13xp0p0v (its author).
 
 # --- the toolchain is GCC (ADR-001) --------------------------------------------
-kconfig  CONFIG_CFI_CLANG         # kernel control-flow integrity needs Clang; hardening.fragment records why that split is not adopted yet
+kconfig  CONFIG_CFI_CLANG         # kernel control-flow integrity needs Clang; hardening.fragment says why the kernel is built with GCC
 kconfig  CONFIG_CFI_PERMISSIVE    # follows CFI_CLANG
 kconfig  CONFIG_CFI_AUTO_DEFAULT  # follows CFI_CLANG
 cmdline  cfi                      # cfi=kcfi selects the Clang CFI mode; no kernel CFI is built
@@ -18,7 +13,7 @@ kconfig  CONFIG_MODULES           # drivers that need firmware load after the ve
 
 # --- the desktop and the console need them ------------------------------------------
 kconfig  CONFIG_VT                # the framebuffer console and the tty1 login (boot.fragment)
-kconfig  CONFIG_KCMP              # DRM selects it (drivers/gpu/drm/Kconfig) and the compositor needs DRM; the "is not set" line for it was ignored, so it is a decision here rather than a dead line there
+kconfig  CONFIG_KCMP              # DRM selects it (drivers/gpu/drm/Kconfig), and the compositor needs DRM
 
 # --- ADR-007: Landlock and seccomp, no SELinux ------------------------------------
 kconfig  CONFIG_SECURITY_SELINUX  # the checker's author prefers SELinux; Kryptik compiles no MAC framework it loads no policy into (ADR-007)
@@ -29,4 +24,4 @@ kconfig  CONFIG_LSM_MMAP_MIN_ADDR # exists only with SELinux; CONFIG_DEFAULT_MMA
 kconfig  CONFIG_KALLSYMS          # a stack trace without symbols cannot be acted on; kernel.kptr_restrict=2 and kernel.dmesg_restrict=1 (build/config/sysctl.d) keep them from users, and KALLSYMS_ALL is off
 
 # --- the IOMMU is already on and strict by default -------------------------------
-cmdline  iommu                    # iommu=force is clipos's belt over the same braces: INTEL_IOMMU_DEFAULT_ON, AMD_IOMMU and IOMMU_DEFAULT_DMA_STRICT turn it on, strict, wherever there is one
+cmdline  iommu                    # INTEL_IOMMU_DEFAULT_ON, AMD_IOMMU and IOMMU_DEFAULT_DMA_STRICT already turn it on, strict, wherever there is one

build/config/licence-exceptions.txt

@@ -1,7 +1,5 @@
-# Sources the image carries no licence file for, each with its reason:
+# Sources the image carries no licence file for; tools/check-image-licences.sh fails on any other.
 #   name   # why
-# Stage 04 installs every other source's (s_licences), and acceptance fails
-# on a source without them (tools/check-image-licences.sh).
 glibc-fhs-patch   # a patch to glibc, whose licence files cover it
 linux-hardened    # a patch to linux, whose COPYING and LICENSES/ cover it
 cmake-bin         # the build's own cmake, which stage 06 leaves out of the root

build/config/setuid-allowlist.txt

@@ -1,8 +1,5 @@
-# Binaries allowed to be setuid or setgid in a Kryptik image; stage 06 takes
-# the bit off every other file in its root (tools/audit-setuid.sh --strip).
+# Binaries allowed setuid or setgid; stage 06 strips the rest (tools/audit-setuid.sh --strip).
 #   /absolute/path   # why it stays, and what would remove it
-# Privilege transitions go through kryptikd, where they are auditable. A file
-# capability is no way round this list: it needs an entry in
-# capability-allowlist.txt, and nothing has one.
+# A file capability is no way round this list: it needs an entry in capability-allowlist.txt.
 /usr/bin/su       # the one way from a login to root, for an administrator and for the test drivers (vm-drive.py su:); goes when kryptikd brokers a root session
-/usr/bin/passwd   # a user changes their own password; goes when a kryptikd verb does that, which weighs a new root-side parser of /etc/shadow against this one binary
+/usr/bin/passwd   # a user changes their own password; goes when a kryptikd verb does that, at the cost of a root-side /etc/shadow parser

build/config/sysctl.d/99-kryptik-hardening.conf

@@ -5,19 +5,17 @@ kernel.kptr_restrict = 2
 kernel.dmesg_restrict = 1
 kernel.printk = 3 3 3 3
 kernel.perf_event_paranoid = 3
-# (No kernel.kexec_load_disabled: CONFIG_KEXEC is off, so the key does not exist.)
+# No kernel.kexec_load_disabled: CONFIG_KEXEC is off, so the key does not exist.
 
 # --- ptrace: disabled entirely after boot ---
 kernel.yama.ptrace_scope = 3
 
-# --- eBPF ---
-# Nothing: CONFIG_BPF_SYSCALL is off (kernel/hardening.fragment), so
-# kernel.unprivileged_bpf_disabled and net.core.bpf_jit_harden do not exist.
+# --- eBPF: not built (CONFIG_BPF_SYSCALL is off), so its sysctls do not exist ---
 
 # --- ASLR: maximum entropy on x86-64 ---
 kernel.randomize_va_space = 2
 vm.mmap_rnd_bits = 32
-# (No vm.mmap_rnd_compat_bits: no 32-bit programs, CONFIG_IA32_EMULATION is off.)
+# No vm.mmap_rnd_compat_bits: no 32-bit programs, CONFIG_IA32_EMULATION is off.
 
 # --- userfaultfd, a heap-grooming primitive, is not built; its sysctl does not exist ---
 
@@ -42,5 +40,4 @@ net.ipv4.icmp_echo_ignore_broadcasts = 1
 net.ipv6.conf.all.accept_redirects = 0
 net.ipv6.conf.all.accept_source_route = 0
 
-# --- core dumps, which could hold zone secrets, are not built (CONFIG_COREDUMP is off):
-# no kernel.core_pattern exists; fs.suid_dumpable above is the belt to that brace ---
+# --- core dumps could hold zone secrets: CONFIG_COREDUMP is off; suid_dumpable is a backstop ---

build/guest-tests/icmp-echo.py

@@ -3,9 +3,7 @@
 
     icmp-echo.py HOST [TIMEOUT]
 """
-# The ICMP datagram socket needs no privilege (net.ipv4.ping_group_range, set
-# by kryptikd in the zone). ping uses it too; the reachability checks use this
-# instead, so a broken ping fails only the ping checks.
+# Not ping itself, so a broken ping fails only the ping checks.
 import socket
 import struct
 import sys
@@ -31,7 +29,7 @@
         s.recvfrom(1500)
         print("PONG", host)
         sys.exit(0)
-    except Exception as e:  # noqa: BLE001 - the reason is the point
+    except Exception as e:  # noqa: BLE001 - its text is the reason printed
         last = str(e)
     finally:
         try: