From 5e9f5b616d8c493cb3306a34254b7389dd66dd21 Mon Sep 17 00:00:00 2001 From: PatternCatalyst Date: Fri, 23 Oct 2026 10:31:05 -0400 Subject: [PATCH 1/6] fix: remove machine and owner identifiers from tracked files --- .host-scrub.toml | 34 +++++++++++++++++++ _docs/01-prerequisites.md | 14 ++++---- _docs/02-lab-setup.md | 8 ++--- _docs/04-syscalls-and-the-abi.md | 2 +- _docs/06-concurrency-three-ways.md | 2 +- _docs/07-fds-raii-and-the-vfs.md | 14 ++++---- _docs/08-page-cache-and-durability.md | 2 +- _docs/09-event-loops-epoll-inotify.md | 10 +++--- _docs/10-io-uring.md | 4 +-- _docs/13-pidfd-modern-process-mgmt.md | 8 ++--- _docs/14-identity-and-privilege.md | 4 +-- _docs/15-virtual-memory.md | 2 +- _docs/17-allocators-and-gc-runtimes.md | 2 +- _docs/18-pipes-fifos-splice.md | 2 +- _docs/19-unix-sockets-fd-passing.md | 4 +-- _docs/21-tcp-sockets.md | 2 +- _docs/22-scaling-the-server.md | 2 +- _docs/23-udp-and-peer-discovery.md | 2 +- _docs/24-time-timers-deadlines.md | 2 +- _docs/28-gdb-and-remote-debugging.md | 2 +- _docs/29-valgrind-sanitizers-miri.md | 2 +- _docs/31-per-language-toolbelts.md | 2 +- _docs/33-seccomp-and-landlock.md | 4 +-- _docs/34-our-programs-in-containers.md | 14 ++++---- _docs/35-virtualization-and-kvm.md | 4 +-- _docs/36-proc-sys-and-the-agent.md | 2 +- _docs/38-opentelemetry-to-lgtm.md | 2 +- _docs/39-benchmarking-without-lies.md | 2 +- _docs/41-capstone-fleet.md | 4 +-- _docs/45-linux-analysis-suites.md | 6 ++-- _docs/46-cpp-toolbox.md | 2 +- _docs/47-go-toolbox.md | 2 +- _docs/48-rust-toolbox.md | 16 ++++----- _plans/r15-ch46-plan.md | 2 +- _plans/r17-ch48-plan.md | 2 +- _plans/r18-ch49-plan.md | 4 +-- _plans/r19-ch50-plan.md | 2 +- _plans/r20-ch51-plan.md | 2 +- _plans/r25-ch56-plan.md | 2 +- _plans/r26-full-matrix-gate.md | 2 +- .../diagrams/34-ns-debugging-map.excalidraw | 8 ++--- assets/diagrams/34-ns-debugging-map.svg | 4 +-- examples/01-hello-syscalls/README.md | 4 +-- examples/06-concurrency-three-ways/README.md | 2 +- .../25-shared-state-and-the-futex/README.md | 2 +- examples/26-atomics-and-lock-free/README.md | 2 +- .../34-our-programs-in-containers/README.md | 2 +- examples/35-virtualization-and-kvm/README.md | 2 +- .../39-benchmarking-without-lies/README.md | 2 +- examples/45-linux-analysis-suites/README.md | 2 +- 50 files changed, 132 insertions(+), 98 deletions(-) create mode 100644 .host-scrub.toml diff --git a/.host-scrub.toml b/.host-scrub.toml new file mode 100644 index 0000000..e80b296 --- /dev/null +++ b/.host-scrub.toml @@ -0,0 +1,34 @@ +# Host-scrub configuration. Holds paths and categories only, never values. +# See CLAUDE.md "Publishing rule". + +# The disposable lab guests (systems-target, systems-peer) are Fedora VMs whose own +# values are book content: the guest account's home directory and the guest kernel +# build the book pins. Neither is the development machine's. +[allow] +home-path = [ + "_docs/02-lab-setup.md", + "_docs/14-identity-and-privilege.md", + "_docs/23-udp-and-peer-discovery.md", + "_docs/32-namespaces-and-cgroups.md", + "_docs/35-virtualization-and-kvm.md", + "examples/14-identity-and-privilege/README.md", + "examples/14-identity-and-privilege/verify.lua", + "examples/37-use-method-60s-analysis/verify.lua", + "examples/40-low-latency-fastpath/verify.lua", + "_plans/r09-batch1-golden-capture.md", + "_plans/r09-batch1-stub-completion.md", + "_plans/r26-full-matrix-gate.md", + "scripts/lab/deploy-to-vm.sh", +] +kernel-build = [ + "_docs/02-lab-setup.md", + "_docs/30-ebpf-observation-toolkit.md", + "_docs/32-namespaces-and-cgroups.md", + "_docs/33-seccomp-and-landlock.md", + "_docs/35-virtualization-and-kvm.md", + "_docs/45-linux-analysis-suites.md", + "_plans/r09-batch1-golden-capture.md", +] +kernel-version = [ + "_plans/r09-batch1-golden-capture.md", +] diff --git a/_docs/01-prerequisites.md b/_docs/01-prerequisites.md index fad3851..7992212 100644 --- a/_docs/01-prerequisites.md +++ b/_docs/01-prerequisites.md @@ -35,7 +35,7 @@ The book targets **Fedora 44** deliberately. Systems programming is the one domain where "any recent Linux" is not good enough: chapters later in the book read kernel tracepoints, load eBPF programs, and poke at cgroup files whose layout shifts between kernel versions. Fedora ships close to upstream — the -reference host here runs kernel `7.1.3-200.fc44` — so what you observe matches +reference host here runs kernel `7.1` — so what you observe matches what current kernel documentation describes. It also ships **GCC 16.1.1** as the system compiler, which matters immediately: the C++ examples use C++23's `std::println` and `std::expected`, and those need GCC 14 or newer. On Fedora @@ -318,7 +318,7 @@ run, `cargo` installs the pinned 1.97.1 toolchain if needed — and each binary prints one line of the same shape: ``` -pid 2520094 on Linux 7.1.3-200.fc44.x86_64 (x86_64) +pid 2520094 on Linux 7.1 (x86_64) ``` Three lines, three different PIDs, identical formatting: that is the whole @@ -335,8 +335,8 @@ C++ binary, trimmed to the `uname` call: ```bash [host]$ strace -f -e trace=uname ./cpp/build/release/app -uname({sysname="Linux", nodename="Lemuria", ...}) = 0 -pid 2520274 on Linux 7.1.3-200.fc44.x86_64 (x86_64) +uname({sysname="Linux", nodename="host", ...}) = 0 +pid 2520274 on Linux 7.1 (x86_64) +++ exited with 0 +++ ``` @@ -348,8 +348,8 @@ strace: Process 2520268 attached strace: Process 2520269 attached strace: Process 2520270 attached strace: Process 2520271 attached -[pid 2520267] uname({sysname="Linux", nodename="Lemuria", ...}) = 0 -pid 2520267 on Linux 7.1.3-200.fc44.x86_64 (x86_64) +[pid 2520267] uname({sysname="Linux", nodename="host", ...}) = 0 +pid 2520267 on Linux 7.1 (x86_64) +++ exited with 0 +++ ``` @@ -392,4 +392,4 @@ snapshotted kernel instead of yours. --- -

verified — runner table PASS for cpp, go, and rust on the Fedora 44 host (kernel 7.1.3-200.fc44, GCC 16.1.1, go1.26.5, rustc 1.97.1): each binary printed pid <PID> on Linux 7.1.3-200.fc44.x86_64 (x86_64), and the strace excerpts above are real trimmed output from those binaries. The CLion section remains unverified as noted.

+

verified — runner table PASS for cpp, go, and rust on the Fedora 44 host (kernel 7.1, GCC 16.1.1, go1.26.5, rustc 1.97.1): each binary printed pid <PID> on Linux 7.1 (x86_64), and the strace excerpts above are real trimmed output from those binaries. The CLion section remains unverified as noted.

diff --git a/_docs/02-lab-setup.md b/_docs/02-lab-setup.md index 6e9f202..1800b55 100644 --- a/_docs/02-lab-setup.md +++ b/_docs/02-lab-setup.md @@ -43,7 +43,7 @@ A VM answers all three at once, and adds the property no container gives you: **its own kernel**. Namespaces share the host kernel, so a container can't show you kernel-version drift, can't be probed as an isolated kernel, and can't be snapshot-reverted with its kernel state. The lab guests run their own -`6.19.10-300.fc44` kernel while the host runs `7.1.3-200.fc44` — a visible +`6.19.10-300.fc44` kernel while the host runs `7.1` — a visible difference this chapter turns into its cross-check. That said, the VM is not the default. The book's decision rule, applied at the @@ -298,14 +298,14 @@ than, say, quietly running the local binary. Run it both ways: ```bash [host]$ cd examples/01-hello-syscalls [host]$ ./demo.sh cpp -pid on Linux 7.1.3-200.fc44.x86_64 (x86_64) +pid on Linux 7.1 (x86_64) [host]$ TARGET=systems-target ./demo.sh cpp → copying app to fedora@192.168.124.7:/home/fedora/app → running on systems-target (Ctrl-C to stop): pid on Linux 6.19.10-300.fc44.x86_64 (x86_64) ``` -Same binary, two different kernel strings: `7.1.3-200.fc44` is your host, +Same binary, two different kernel strings: `7.1` is your host, `6.19.10-300.fc44` is the guest. The example's per-language `demo.sh` wires this up — with `TARGET` set, its `run` step calls `scripts/lab/deploy-to-vm.sh "$TARGET" ` instead of executing locally, @@ -339,4 +339,4 @@ stack**, so every later demo has somewhere to send its telemetry. --- -

verified — both guests were provisioned from Fedora-Cloud-Base-Generic-44-1.7 on this host (target 4 GB at 192.168.124.7, peer 2 GB at 192.168.124.95); /var/log/lab-ready read back bpftrace v0.24.2 and kernel 6.19.10-300.fc44 on both; lab-ready snapshots exist on both; and deploy-to-vm.sh ran the host-built C++ and Go binaries on systems-target, printing the guest kernel string 6.19.10-300.fc44.x86_64 versus 7.1.3-200.fc44.x86_64 locally. The “When the guest falls behind the host” section was added later and is verified separately, on the same lab: the host’s libstdc++ reached 16.2.1-2.fc44 (libstdc++.so.6.0.36, max GLIBCXX_3.4.36) while both guests sat at 16.1.1-2.fc44 (libstdc++.so.6.0.35, max GLIBCXX_3.4.35) behind snapshots taken before the update, and every host-built C++ binary then failed on the guest with the quoted version `GLIBCXX_3.4.36' not found. A full-matrix run reproduced the asymmetry the section describes — six VM examples failing in C++ while Go and Rust passed on the same guest in the same run — and the quoted diagnostic commands, the dnf fix, and the re-snapshot were all run here: after revert-vm.sh systems-target lab-ready the guest reported GLIBCXX_3.4.36 and test-all-examples.py --mode vm --lang cpp reported the quoted 8 passed, 0 failed, 0 skipped, including the two-guest 41-capstone-fleet. systems-peer was confirmed to carry the same drift while showing no symptom. Not exercised: unverified — the GLIBC_ form of the symbol check is stated by analogy and was not the failure encountered here, which was GLIBCXX_ only; and building inside the guest with the in-VM toolchains is named as the standing fallback but is not exercised by any example in this book.

+

verified — both guests were provisioned from Fedora-Cloud-Base-Generic-44-1.7 on this host (target 4 GB at 192.168.124.7, peer 2 GB at 192.168.124.95); /var/log/lab-ready read back bpftrace v0.24.2 and kernel 6.19.10-300.fc44 on both; lab-ready snapshots exist on both; and deploy-to-vm.sh ran the host-built C++ and Go binaries on systems-target, printing the guest kernel string 6.19.10-300.fc44.x86_64 versus 7.1 locally. The “When the guest falls behind the host” section was added later and is verified separately, on the same lab: the host’s libstdc++ reached 16.2.1-2.fc44 (libstdc++.so.6.0.36, max GLIBCXX_3.4.36) while both guests sat at 16.1.1-2.fc44 (libstdc++.so.6.0.35, max GLIBCXX_3.4.35) behind snapshots taken before the update, and every host-built C++ binary then failed on the guest with the quoted version `GLIBCXX_3.4.36' not found. A full-matrix run reproduced the asymmetry the section describes — six VM examples failing in C++ while Go and Rust passed on the same guest in the same run — and the quoted diagnostic commands, the dnf fix, and the re-snapshot were all run here: after revert-vm.sh systems-target lab-ready the guest reported GLIBCXX_3.4.36 and test-all-examples.py --mode vm --lang cpp reported the quoted 8 passed, 0 failed, 0 skipped, including the two-guest 41-capstone-fleet. systems-peer was confirmed to carry the same drift while showing no symptom. Not exercised: unverified — the GLIBC_ form of the symbol check is stated by analogy and was not the failure encountered here, which was GLIBCXX_ only; and building inside the guest with the in-VM toolchains is named as the standing fallback but is not exercised by any example in this book.

diff --git a/_docs/04-syscalls-and-the-abi.md b/_docs/04-syscalls-and-the-abi.md index 83bb123..84afae3 100644 --- a/_docs/04-syscalls-and-the-abi.md +++ b/_docs/04-syscalls-and-the-abi.md @@ -388,4 +388,4 @@ Rust — that every later example in the book obeys. --- -

verified — all numbers in this chapter are from this session's runs on the Fedora 44 reference host (kernel 7.1.3-200.fc44, glibc 2.43, strace 7.1): the harness reported PASS for cpp/go/rust and each binary printed the five-line block ending sysprobe: 4 steps ok; strace -c totaled 70 (cpp), 283 (go, -cf), and 73 (rust); the vdso-probe run showed 0 clock_gettime and 2 getrandom syscalls for 1000 calls each, including getrandom("…", 32, 0) = 32; the quoted sequence traces (O_TMPFILE openat, 25-byte write, clock_nanosleep vs raw nanosleep, Go's 20 µs-doubling monitor sleeps) are trimmed real output; objdump counted 0/511/32 syscall instructions; and /proc/self/maps showed the quoted [vdso]/[vvar_vclock] mappings. Not run here: the bpftrace kernel-side count (lab-VM callout above).

+

verified — all numbers in this chapter are from this session's runs on the Fedora 44 reference host (kernel 7.1, glibc 2.43, strace 7.1): the harness reported PASS for cpp/go/rust and each binary printed the five-line block ending sysprobe: 4 steps ok; strace -c totaled 70 (cpp), 283 (go, -cf), and 73 (rust); the vdso-probe run showed 0 clock_gettime and 2 getrandom syscalls for 1000 calls each, including getrandom("…", 32, 0) = 32; the quoted sequence traces (O_TMPFILE openat, 25-byte write, clock_nanosleep vs raw nanosleep, Go's 20 µs-doubling monitor sleeps) are trimmed real output; objdump counted 0/511/32 syscall instructions; and /proc/self/maps showed the quoted [vdso]/[vvar_vclock] mappings. Not run here: the bpftrace kernel-side count (lab-VM callout above).

diff --git a/_docs/06-concurrency-three-ways.md b/_docs/06-concurrency-three-ways.md index 113d39a..8797c93 100644 --- a/_docs/06-concurrency-three-ways.md +++ b/_docs/06-concurrency-three-ways.md @@ -407,7 +407,7 @@ of `fwatch`, where the question stops being "who runs the code" and becomes ---

verified — every number above -comes from runs on the Fedora 44 reference host (kernel 7.1.3-200.fc44) this +comes from runs on the Fedora 44 reference host (kernel 7.1) this session: the runner reported 06-concurrency-three-ways PASS PASS PASS (3 passed, 0 failed, Go built with -race); the fixture outputs of the three binaries were cmp-identical, diff --git a/_docs/07-fds-raii-and-the-vfs.md b/_docs/07-fds-raii-and-the-vfs.md index 4d51357..2c039f7 100644 --- a/_docs/07-fds-raii-and-the-vfs.md +++ b/_docs/07-fds-raii-and-the-vfs.md @@ -432,9 +432,9 @@ inodes agree, field for field: ```bash [host]$ ls -li tree -68626 -rw-r--r-- 1 rsedor rsedor 5 Sep 8 2001 a.txt -68627 -rw-r--r-- 1 rsedor rsedor 3 Sep 8 2001 gone.txt -68624 drwxr-xr-x 3 rsedor rsedor 80 Jul 18 23:02 sub +68626 -rw-r--r-- 1 user user 5 Sep 8 2001 a.txt +68627 -rw-r--r-- 1 user user 3 Sep 8 2001 gone.txt +68624 drwxr-xr-x 3 user user 80 Jul 18 23:02 sub [host]$ stat --format='%i %s %Y %n' tree/a.txt tree/sub/b.txt 68626 5 1000000000 tree/a.txt 68628 9 1000000100 tree/sub/b.txt @@ -480,10 +480,10 @@ files, delaying each stat by 20 ms leaves minutes to inspect: [host]$ strace -o /dev/null -e trace=newfstatat -e inject=newfstatat:delay_enter=20000 \ ./cpp/build/release/app snapshot big > /dev/null & [host]$ ls -l /proc//fd -lr-x------ 1 rsedor rsedor 64 Jul 18 23:03 3 -> …/fixture/big -lr-x------ 1 rsedor rsedor 64 Jul 18 23:03 4 -> …/fixture/big/l1 -lr-x------ 1 rsedor rsedor 64 Jul 18 23:03 5 -> …/fixture/big/l1/l2 -lr-x------ 1 rsedor rsedor 64 Jul 18 23:03 6 -> …/fixture/big/l1/l2/l3 +lr-x------ 1 user user 64 Jul 18 23:03 3 -> …/fixture/big +lr-x------ 1 user user 64 Jul 18 23:03 4 -> …/fixture/big/l1 +lr-x------ 1 user user 64 Jul 18 23:03 5 -> …/fixture/big/l1/l2 +lr-x------ 1 user user 64 Jul 18 23:03 6 -> …/fixture/big/l1/l2/l3 [host]$ cat /proc//fdinfo/6 pos: 1980 flags: 02700000 diff --git a/_docs/08-page-cache-and-durability.md b/_docs/08-page-cache-and-durability.md index 903e3f8..3086907 100644 --- a/_docs/08-page-cache-and-durability.md +++ b/_docs/08-page-cache-and-durability.md @@ -464,7 +464,7 @@ Next, **event loops**: `epoll` and `inotify`, where the question stops being

verified — all numbers above are from runs performed on the reference host (btrfs on NVMe, Fedora 44, -kernel 7.1.3-200.fc44) while writing this chapter: the mode reports +kernel 7.1) while writing this chapter: the mode reports (ms=21 / fsync_ms=17, ms=138, ms=81 at 64 MiB; Go/Rust buffered parity), the strace -c table (16 fdatasync, 65 write), the Dirty: diff --git a/_docs/09-event-loops-epoll-inotify.md b/_docs/09-event-loops-epoll-inotify.md index 0d4c948..9365b2a 100644 --- a/_docs/09-event-loops-epoll-inotify.md +++ b/_docs/09-event-loops-epoll-inotify.md @@ -480,10 +480,10 @@ list is inspectable. With a watcher running (PID via `$!`): ```bash [host]$ ls -l /proc/$PID/fd | tail -4 -lr-x------ 1 rsedor rsedor 64 Jul 18 23:06 3 -> anon_inode:inotify -lrwx------ 1 rsedor rsedor 64 Jul 18 23:06 4 -> anon_inode:[timerfd] -lrwx------ 1 rsedor rsedor 64 Jul 18 23:06 5 -> anon_inode:[signalfd] -lrwx------ 1 rsedor rsedor 64 Jul 18 23:06 6 -> anon_inode:[eventpoll] +lr-x------ 1 user user 64 Jul 18 23:06 3 -> anon_inode:inotify +lrwx------ 1 user user 64 Jul 18 23:06 4 -> anon_inode:[timerfd] +lrwx------ 1 user user 64 Jul 18 23:06 5 -> anon_inode:[signalfd] +lrwx------ 1 user user 64 Jul 18 23:06 6 -> anon_inode:[eventpoll] [host]$ cat /proc/$PID/fdinfo/6 tfd: 3 events: 19 data: 0 pos:0 ino:426 sdev:11 tfd: 4 events: 19 data: 1 pos:0 ino:426 sdev:11 @@ -564,7 +564,7 @@ tells you it is *done*.

verified — all evidence in this chapter was produced on the Fedora 44 reference host (kernel -7.1.3-200.fc44, strace 7.1) this session: the runner reported +7.1, strace 7.1) this session: the runner reported PASS for cpp, go, and rust (3 passed, 0 failed, 0 skipped); the create/append/delete session printed exactly event: created a.txt, event: deleted a.txt, fwatch: exiting diff --git a/_docs/10-io-uring.md b/_docs/10-io-uring.md index 74f1397..1811e04 100644 --- a/_docs/10-io-uring.md +++ b/_docs/10-io-uring.md @@ -110,7 +110,7 @@ languages, three answers to the same question: *who owns the event loop?* > **Research note — io_uring on this kernel, from primary sources.** Claims > about io_uring age fast, so this chapter cites only what this host shows. -> Kernel `7.1.3-200.fc44` reported 18 `IORING_FEAT_*` flags in the +> Kernel `7.1` reported 18 `IORING_FEAT_*` flags in the > `io_uring_setup` params during our traced run — from `SINGLE_MMAP` and > `NODROP` through `RECVSEND_BUNDLE`, `MIN_TIMEOUT`, `RW_ATTR`, and > `NO_IOWAIT` — and the shipped `io_uring(7)`, `io_uring_setup(2)`, and @@ -520,4 +520,4 @@ us to the capstone. --- -

verified — all numbers above are from this session's runs on the Fedora 44 host (kernel 7.1.3-200.fc44): the runner table passed 3/3 (cpp, go, rust); the 403-file/19,507,360-byte tree synced with engine=rw in 11–12 ms (C++) and 12–13 ms (Rust) versus 129–137 ms and 105–107 ms with engine=uring; strace -c counted 850 read + 444 write (rw) against 407 io_uring_enter + 1 io_uring_setup (uring, loader-only read/write 4/1); the fixture uring sync used 5 enters and printed synced 5 files 1348634 bytes engine=uring ms=3; the io_uring_setup/mmap trace, the diff -r/cmp byte-equality, the Go refusal (engine=uring: unsupported in Go (see chapter 10), exit 64), and the empty grep -c io_uring against podman's seccomp profile were all reproduced as quoted. Unverified: the bpftrace probe in the lab-VM callout, as marked.

+

verified — all numbers above are from this session's runs on the Fedora 44 host (kernel 7.1): the runner table passed 3/3 (cpp, go, rust); the 403-file/19,507,360-byte tree synced with engine=rw in 11–12 ms (C++) and 12–13 ms (Rust) versus 129–137 ms and 105–107 ms with engine=uring; strace -c counted 850 read + 444 write (rw) against 407 io_uring_enter + 1 io_uring_setup (uring, loader-only read/write 4/1); the fixture uring sync used 5 enters and printed synced 5 files 1348634 bytes engine=uring ms=3; the io_uring_setup/mmap trace, the diff -r/cmp byte-equality, the Go refusal (engine=uring: unsupported in Go (see chapter 10), exit 64), and the empty grep -c io_uring against podman's seccomp profile were all reproduced as quoted. Unverified: the bpftrace probe in the lab-VM callout, as marked.

diff --git a/_docs/13-pidfd-modern-process-mgmt.md b/_docs/13-pidfd-modern-process-mgmt.md index 2543143..53b5fde 100644 --- a/_docs/13-pidfd-modern-process-mgmt.md +++ b/_docs/13-pidfd-modern-process-mgmt.md @@ -65,7 +65,7 @@ monitoring agent) has the race with no mitigation at all. ## Four syscalls that make a process a file The fix arrived in a burst across Linux 5.1–5.4, and this host's manpages -(kernel `7.1.3-200.fc44`) document each piece. `pidfd_open(2)` — HISTORY: +(kernel `7.1`) document each piece. `pidfd_open(2)` — HISTORY: "Linux 5.3" — "creates a file descriptor that refers to the process whose PID is specified in pid"; the close-on-exec flag is set automatically, so the Chapter 7 discipline costs nothing here. The fd's superpower is stated @@ -434,8 +434,8 @@ read the fd table the way Chapter 7 taught: ```bash [host]$ ls -l /proc/2624388/fd | tail -2 -lrwx------ 1 rsedor rsedor 64 Jul 18 23:59 3 -> anon_inode:[signalfd] -lrwx------ 1 rsedor rsedor 64 Jul 18 23:59 4 -> anon_inode:[pidfd] +lrwx------ 1 user user 64 Jul 18 23:59 3 -> anon_inode:[signalfd] +lrwx------ 1 user user 64 Jul 18 23:59 4 -> anon_inode:[pidfd] [host]$ cat /proc/2624388/fdinfo/4 pos: 0 flags: 02000002 @@ -487,7 +487,7 @@ ability to do its job.

verified — every number and output excerpt above was produced on the Fedora 44 reference host -(kernel 7.1.3-200.fc44) this session: the runner printed +(kernel 7.1) this session: the runner printed 13-pidfd-modern-process-mgmt PASS PASS PASS (3 passed, 0 failed, 0 skipped) and a direct verify.lua run showed PASS 37 / FAIL 0; the crash-loop and timeout transcripts are diff --git a/_docs/14-identity-and-privilege.md b/_docs/14-identity-and-privilege.md index f691277..a794f64 100644 --- a/_docs/14-identity-and-privilege.md +++ b/_docs/14-identity-and-privilege.md @@ -88,9 +88,9 @@ create: the umask. A `creat`/`open(O_CREAT)` mode is filtered as [host]$ umask 022 [host]$ touch umask-demo.txt && ls -l umask-demo.txt --rw-r--r-- 1 rsedor rsedor 0 Jul 18 23:56 umask-demo.txt +-rw-r--r-- 1 user user 0 Jul 18 23:56 umask-demo.txt [host]$ (umask 077 && touch umask-demo-077.txt && ls -l umask-demo-077.txt) --rw------- 1 rsedor rsedor 0 Jul 18 23:56 umask-demo-077.txt +-rw------- 1 user user 0 Jul 18 23:56 umask-demo-077.txt ``` Same `touch`, same requested 0666: umask 022 clears group/other write diff --git a/_docs/15-virtual-memory.md b/_docs/15-virtual-memory.md index d338be4..15dc2c6 100644 --- a/_docs/15-virtual-memory.md +++ b/_docs/15-virtual-memory.md @@ -509,7 +509,7 @@ seeing one page — the machinery `shmkv` v0 is built from.

verified — every number and excerpt above was produced on the Fedora 44 reference host (kernel -7.1.3-200.fc44, THP=madvise) this session: the runner printed +7.1, THP=madvise) this session: the runner printed 15-virtual-memory PASS PASS PASS (3 passed, 0 failed, 0 skipped; 58 verify.lua checks per language); the heap runs reported minor=16385/16598/16384 (C++/Go/Rust) with the anonymous diff --git a/_docs/17-allocators-and-gc-runtimes.md b/_docs/17-allocators-and-gc-runtimes.md index 9ebb241..b539247 100644 --- a/_docs/17-allocators-and-gc-runtimes.md +++ b/_docs/17-allocators-and-gc-runtimes.md @@ -462,7 +462,7 @@ userspace at all. ---

verified — every number above -was produced on the Fedora 44 reference host (kernel 7.1.3-200.fc44) this +was produced on the Fedora 44 reference host (kernel 7.1) this session: the runner printed 17-allocators-and-gc-runtimes PASS PASS PASS (3 passed, 0 failed, 0 skipped); the six variant lines, the four GOGC/GOMEMLIMIT runs (gc_cycles 9/32/47/0), the mallinfo2 probe output, the diff --git a/_docs/18-pipes-fifos-splice.md b/_docs/18-pipes-fifos-splice.md index 782f594..105fccc 100644 --- a/_docs/18-pipes-fifos-splice.md +++ b/_docs/18-pipes-fifos-splice.md @@ -508,7 +508,7 @@ file descriptors sent across process boundaries.

verified — every number and output excerpt above was reproduced on the Fedora 44 reference host (kernel -7.1.3-200.fc44) this session: the runner printed +7.1) this session: the runner printed 18-pipes-fifos-splice  PASS  PASS  PASS (3 passed, 0 failed, 0 skipped); the F_GETPIPE_SZ probe printed capacity 65536, PIPE_BUF 4096, and the 1→4096 rounding live; the supervise run diff --git a/_docs/19-unix-sockets-fd-passing.md b/_docs/19-unix-sockets-fd-passing.md index 7f7f58b..3504cd5 100644 --- a/_docs/19-unix-sockets-fd-passing.md +++ b/_docs/19-unix-sockets-fd-passing.md @@ -420,8 +420,8 @@ supervisor pid 2622904 and `pmctl` pid 2623753: ```console [host]$ ls -l /proc/2622904/fd | grep pmon.log; ls -l /proc/2623753/fd | grep pmon.log -lrwx------ 1 rsedor rsedor 64 Jul 18 23:57 3 -> /tmp/p19.t9j0/pmon.log -lrwx------ 1 rsedor rsedor 64 Jul 18 23:58 4 -> /tmp/p19.t9j0/pmon.log +lrwx------ 1 user user 64 Jul 18 23:57 3 -> /tmp/p19.t9j0/pmon.log +lrwx------ 1 user user 64 Jul 18 23:58 4 -> /tmp/p19.t9j0/pmon.log [host]$ cat /proc/2622904/fdinfo/3 /proc/2623753/fdinfo/4 pos: 47 flags: 02102002 diff --git a/_docs/21-tcp-sockets.md b/_docs/21-tcp-sockets.md index a6e23ca..c9185ed 100644 --- a/_docs/21-tcp-sockets.md +++ b/_docs/21-tcp-sockets.md @@ -462,7 +462,7 @@ thousand idle clients cost fds instead of stacks.

verified — every number and output excerpt above was produced on the Fedora 44 reference host (kernel -7.1.3-200.fc44, strace 7.1) this session. The runner printed +7.1, strace 7.1) this session. The runner printed 21-tcp-sockets PASS PASS PASS (3 passed, 0 failed, 0 skipped; verify.lua 19/19 per language). The hand-driven two-client session produced the exact transcripts shown — bob received diff --git a/_docs/22-scaling-the-server.md b/_docs/22-scaling-the-server.md index fe856c5..ea104ec 100644 --- a/_docs/22-scaling-the-server.md +++ b/_docs/22-scaling-the-server.md @@ -418,7 +418,7 @@ between two VMs on one L2 segment.

verified — every number and output excerpt above was produced on the Fedora 44 reference host (kernel -7.1.3-200.fc44, GCC 16.1.1, strace 7.1, 16 CPUs) this session: the runner printed +7.1, GCC 16.1.1, strace 7.1, 16 CPUs) this session: the runner printed 22-scaling-the-server PASS PASS PASS (3 passed, 0 failed, 0 skipped; verify.lua 24 checks per language, 72 total); the hand-driven epoll session produced the exact alice: hello, chatterd echo to both diff --git a/_docs/23-udp-and-peer-discovery.md b/_docs/23-udp-and-peer-discovery.md index c6604bf..aa61afd 100644 --- a/_docs/23-udp-and-peer-discovery.md +++ b/_docs/23-udp-and-peer-discovery.md @@ -370,7 +370,7 @@ accurate about *when* it fires. ---

verified — evidence produced -this session on the Fedora 44 reference host (kernel 7.1.3-200.fc44) and the +this session on the Fedora 44 reference host (kernel 7.1) and the two lab guests systems-target (192.168.124.7) / systems-peer (192.168.124.95): the runner printed 23-udp-and-peer-discovery  PASS  PASS  PASS diff --git a/_docs/24-time-timers-deadlines.md b/_docs/24-time-timers-deadlines.md index 4922866..3202a6f 100644 --- a/_docs/24-time-timers-deadlines.md +++ b/_docs/24-time-timers-deadlines.md @@ -440,7 +440,7 @@ a lock is a userspace atomic that only touches the kernel when it must block.

verified — every number and output excerpt above was produced on the Fedora 44 reference host (kernel -7.1.3-200.fc44, strace 7.1) this session: the runner printed +7.1, strace 7.1) this session: the runner printed 24-time-timers-deadlines PASS PASS PASS (3 passed, 0 failed, 0 skipped), and the orchestrator was re-run to confirm the timing scenario is not flaky. clockprobe printed res=1ns with diff --git a/_docs/28-gdb-and-remote-debugging.md b/_docs/28-gdb-and-remote-debugging.md index 28cc1b9..a979fb0 100644 --- a/_docs/28-gdb-and-remote-debugging.md +++ b/_docs/28-gdb-and-remote-debugging.md @@ -528,7 +528,7 @@ above except the two spans marked unverified (the `systems-target` gdbserver/target remote session, the CLion remote-debug configuration, and delve's `goroutines`/`goroutine bt`) was produced on the Fedora 44 reference host -(kernel 7.1.3-200.fc44, gdb 17.2, gcc 16.1.1, go1.26.5, rustc 1.97.1, readelf/ +(kernel 7.1, gdb 17.2, gcc 16.1.1, go1.26.5, rustc 1.97.1, readelf/ objdump 2.46.1) this session: app crash under ulimit -c unlimited exited 139 and coredumpctl recorded and extracted a real core; a scripted diff --git a/_docs/29-valgrind-sanitizers-miri.md b/_docs/29-valgrind-sanitizers-miri.md index b1d70f2..6d8db0a 100644 --- a/_docs/29-valgrind-sanitizers-miri.md +++ b/_docs/29-valgrind-sanitizers-miri.md @@ -410,7 +410,7 @@ no rebuild, on the lab VM this chapter's tools never needed.

verified — every transcript, number, and diagnostic above was produced on the Fedora 44 reference host -(kernel 7.1.3-200.fc44, valgrind-3.27.1, gcc 16.1.1, go1.26.5, rustc/cargo +(kernel 7.1, valgrind-3.27.1, gcc 16.1.1, go1.26.5, rustc/cargo 1.97.1, miri 0.1.0 nightly-2026-07-18) this session. Confirmed live: valgrind memcheck reported definitely lost for leak and uninitialised value(s) for uninit, and also diff --git a/_docs/31-per-language-toolbelts.md b/_docs/31-per-language-toolbelts.md index 4ac6b16..7f971d8 100644 --- a/_docs/31-per-language-toolbelts.md +++ b/_docs/31-per-language-toolbelts.md @@ -521,7 +521,7 @@ tracing tools this book has deferred until now.

verified — every command, number, and transcript above was run this session on the Fedora 44 reference -host (kernel 7.1.3-200.fc44, GCC 16.1.1, clang 22.1.8, go1.26.5, rustc +host (kernel 7.1, GCC 16.1.1, clang 22.1.8, go1.26.5, rustc 1.97.1, perf 7.1.3, gdb 17.2) against the binaries in examples/31-per-language-toolbelts/. The plain hand runs printed result=216816 (hot) and result=5000 (alloc) diff --git a/_docs/33-seccomp-and-landlock.md b/_docs/33-seccomp-and-landlock.md index e73a7d9..98a05e9 100644 --- a/_docs/33-seccomp-and-landlock.md +++ b/_docs/33-seccomp-and-landlock.md @@ -171,7 +171,7 @@ fwatch: probe outside /etc/hostname: EACCES (Permission denied) ``` Same distribution, same syscall numbers, and yet the host (kernel -`7.1.3-200.fc44.x86_64`) reports ABI 9 while `systems-target` (kernel +`7.1`) reports ABI 9 while `systems-target` (kernel `6.19.10-300.fc44.x86_64`) reports ABI 7 -- two real Fedora 44 kernels a few point releases apart, disagreeing about what Landlock supports, while agreeing completely on the observable behavior the ruleset enforces. Every @@ -486,7 +486,7 @@ start being something a container runtime installs *for* it.

verified — every transcript and number above was produced this session, reproduced on both the plain -host (kernel 7.1.3-200.fc44.x86_64, libseccomp 2.6.0, GCC +host (kernel 7.1, libseccomp 2.6.0, GCC 16.1.1, Go 1.26.5, Rust/Cargo 1.97.1) and the systems-target guest (kernel 6.19.10-300.fc44.x86_64): the runner printed 33-seccomp-and-landlock PASS PASS PASS (3 passed, 0 failed, diff --git a/_docs/34-our-programs-in-containers.md b/_docs/34-our-programs-in-containers.md index 5df77cd..de52198 100644 --- a/_docs/34-our-programs-in-containers.md +++ b/_docs/34-our-programs-in-containers.md @@ -98,11 +98,11 @@ per-user block of otherwise-unused host uids, declared in `/etc/subuid` and ```bash [host]$ grep "^$(whoami):" /etc/subuid /etc/subgid -/etc/subuid:rsedor:524288:65536 -/etc/subgid:rsedor:524288:65536 +/etc/subuid:user:524288:65536 +/etc/subgid:user:524288:65536 ``` -That line grants `rsedor` a private range of 65,536 host uids starting at +That line grants `user` a private range of 65,536 host uids starting at 524288 -- ids no other account owns. `podman unshare cat /proc/self/uid_map`, run in podman's own user namespace, shows exactly how the two ranges combine: @@ -113,7 +113,7 @@ combine: 1 524288 65536 ``` -Container uid 0 (root, inside) maps to host uid 1000 (`rsedor`, outside) -- +Container uid 0 (root, inside) maps to host uid 1000 (`user`, outside) -- one id. Container uids 1 through 65536 map to the private subuid block. The consequence worth sitting with: a process that is root *inside* the container has, outside it, only the privileges of the ordinary host user @@ -336,7 +336,7 @@ the container's pid and mount namespaces on top: {% include excalidraw.html file="34-ns-debugging-map" - alt="A host band above a podman-user-namespace band. podman exec reaches the container PID 1 directly from inside the container runtime. podman unshare nsenter first joins podman's own user namespace, then nsenter --target --pid --mount reaches the same PID 1 from there -- both confirming Name: app and /proc/1/exe resolving to /usr/local/bin/app. A dashed, failing arrow shows plain nsenter without podman unshare returning EPERM: reassociate to namespaces failed. Below, real evidence boxes show the subuid mapping rsedor:524288:65536 and a live zombie scan of /proc/[0-9]*/stat reporting zero." + alt="A host band above a podman-user-namespace band. podman exec reaches the container PID 1 directly from inside the container runtime. podman unshare nsenter first joins podman's own user namespace, then nsenter --target --pid --mount reaches the same PID 1 from there -- both confirming Name: app and /proc/1/exe resolving to /usr/local/bin/app. A dashed, failing arrow shows plain nsenter without podman unshare returning EPERM: reassociate to namespaces failed. Below, real evidence boxes show the subuid mapping user:524288:65536 and a live zombie scan of /proc/[0-9]*/stat reporting zero." caption="Figure 34.3 -- podman exec and podman unshare nsenter reach the same container PID 1 from two different starting namespaces; plain nsenter cannot" %} A live `gdb` attach is the surprise worth reporting plainly: because @@ -406,7 +406,7 @@ ladder -- container versus full KVM guest versus bare host. ``` Against podman 5.8.4 rootless on this host (Fedora Linux 44, kernel -`7.1.3-200.fc44.x86_64`, 16 cpus), a fresh build/run/teardown of all three +`7.1`, 16 cpus), a fresh build/run/teardown of all three languages: ``` @@ -503,7 +503,7 @@ containers, and a real `systems-target` guest.

verified -- every transcript and number above was produced this session on this host -(Fedora Linux 44, kernel 7.1.3-200.fc44.x86_64, 16 cpus, +(Fedora Linux 44, kernel 7.1, 16 cpus, podman 5.8.4 rootless): python3 scripts/test-all-examples.py --only 34-our-programs-in-containers --mode local printed 34-our-programs-in-containers PASS PASS PASS (3 passed, 0 diff --git a/_docs/35-virtualization-and-kvm.md b/_docs/35-virtualization-and-kvm.md index 4d3080f..8e1630f 100644 --- a/_docs/35-virtualization-and-kvm.md +++ b/_docs/35-virtualization-and-kvm.md @@ -324,7 +324,7 @@ or the state and the code that thinks it owns the state quietly drift apart. ## Build, run, observe Three environments, one binary. First, the bare host (Fedora 44, kernel -7.1.3-200.fc44, Intel i7-11800H, `Virtualization: VT-x` from `lscpu`): +7.1, Intel 8-core/16-thread laptop CPU, `Virtualization: VT-x` from `lscpu`): ```bash [host]$ cd examples/35-virtualization-and-kvm @@ -464,7 +464,7 @@ hand, one `overheadbench` run at a time.

verified — every transcript and number above was produced this session. Host: Fedora 44, kernel -7.1.3-200.fc44.x86_64, Intel i7-11800H, lscpu reporting +7.1, Intel 8-core/16-thread laptop CPU, lscpu reporting Virtualization: VT-x, lsmod showing kvm_intel/kvm/irqbypass loaded; python3 scripts/test-all-examples.py --only 35-virtualization-and-kvm diff --git a/_docs/36-proc-sys-and-the-agent.md b/_docs/36-proc-sys-and-the-agent.md index e44f702..46c94e7 100644 --- a/_docs/36-proc-sys-and-the-agent.md +++ b/_docs/36-proc-sys-and-the-agent.md @@ -631,7 +631,7 @@ same USE method, two structurally opposite ways of answering it. ---

verified — on the Fedora 44 -reference host (kernel 7.1.3-200.fc44, 16 CPUs, ~62 GiB RAM) this session: +reference host (kernel 7.1, 16 CPUs, ~62 GiB RAM) this session: python3 scripts/test-all-examples.py --only 36-proc-sys-and-the-agent --mode local printed PASS PASS PASS (3 passed, 0 failed; verify.lua reported PASS 32 / FAIL 0 for each of diff --git a/_docs/38-opentelemetry-to-lgtm.md b/_docs/38-opentelemetry-to-lgtm.md index 5d4ac63..aceb089 100644 --- a/_docs/38-opentelemetry-to-lgtm.md +++ b/_docs/38-opentelemetry-to-lgtm.md @@ -433,7 +433,7 @@ make most microbenchmarks quietly measure the wrong thing. ---

verified — on the Fedora 44 -reference host (kernel 7.1.3-200.fc44) this session, with the lsp-lgtm +reference host (kernel 7.1) this session, with the lsp-lgtm LGTM stack running (OTLP on :4318, Grafana on :3000): python3 scripts/test-all-examples.py --only 38-opentelemetry-to-lgtm --mode local printed PASS PASS PASS (3 passed, 0 failed; diff --git a/_docs/39-benchmarking-without-lies.md b/_docs/39-benchmarking-without-lies.md index b984051..6a5cd67 100644 --- a/_docs/39-benchmarking-without-lies.md +++ b/_docs/39-benchmarking-without-lies.md @@ -515,7 +515,7 @@ corrected p99 small in the first place. ---

verified — on the Fedora 44 -reference host (kernel 7.1.3-200.fc44, 11th-gen Intel i7-11800H, 16 CPUs, +reference host (kernel 7.1, 11th-gen Intel 8-core/16-thread laptop CPU, 16 CPUs, intel_pstate/powersave governor, turbo active) this session: python3 scripts/test-all-examples.py --only 39-benchmarking-without-lies printed PASS PASS PASS (3 diff --git a/_docs/41-capstone-fleet.md b/_docs/41-capstone-fleet.md index dd21b78..885ba49 100644 --- a/_docs/41-capstone-fleet.md +++ b/_docs/41-capstone-fleet.md @@ -731,7 +731,7 @@ The first is Landlock's enforced ABI. `fwatch --sandbox` never hardcodes a version — it asks the running kernel with `landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION)`, the exact probe Chapter 33 established, and prints whatever comes back. On the -Fedora 44 reference host (kernel `7.1.3-200.fc44`), where this chapter's +Fedora 44 reference host (kernel `7.1`), where this chapter's loopback `verify.lua` runs, that probe returns **ABI 9**. On the `systems-target` lab guest (kernel `6.19.10-300.fc44`) this session, the identical code, the identical syscall, returned **ABI 7**. That is not a @@ -799,7 +799,7 @@ those chapters lean on was proven here, running for real. ---

verified — on the Fedora 44 -reference host (kernel 7.1.3-200.fc44) and the two lab guests +reference host (kernel 7.1) and the two lab guests systems-target (192.168.124.7) / systems-peer (192.168.124.95, kernel 6.19.10-300.fc44) this session: python3 scripts/test-all-examples.py --only 41-capstone-fleet --mode diff --git a/_docs/45-linux-analysis-suites.md b/_docs/45-linux-analysis-suites.md index 50a84b7..2113f7f 100644 --- a/_docs/45-linux-analysis-suites.md +++ b/_docs/45-linux-analysis-suites.md @@ -306,12 +306,12 @@ run() { ``` This session's real transcript, on the Fedora 44 host (kernel -`7.1.4-204.fc44`, podman 5.8.4 rootless): +`7.1`, podman 5.8.4 rootless): ```console --- pcp: suite summary (openmetrics/podman should both be listed) --- Performance Co-Pilot configuration on 9fb541ff035b: - platform: Linux 9fb541ff035b 7.1.4-204.fc44.x86_64 ... + platform: Linux 9fb541ff035b 7.1 ... pmcd: Version 7.1.5-3, 11 agents pmda: root pmcd proc pmproxy xfs podman linux mmv kvm jbd2 openmetrics --- pminfo -f: a real scraped openmetrics value (file:// source, no network) --- @@ -479,7 +479,7 @@ without ever giving it a chapter of its own. above except the span marked unverified (Cockpit's Overview/Podman/Logs web-UI panels, described but not browser-automated) was produced this -session. On the Fedora 44 host (kernel 7.1.4-204.fc44, podman +session. On the Fedora 44 host (kernel 7.1, podman 5.8.4 rootless): ./demo.sh cpp run produced the exact transcript quoted above, including pmcd: Version 7.1.5-3, 11 agents, openmetrics.lsp45.lsp45_answer value 42, and diff --git a/_docs/46-cpp-toolbox.md b/_docs/46-cpp-toolbox.md index ec453ba..81b8eca 100644 --- a/_docs/46-cpp-toolbox.md +++ b/_docs/46-cpp-toolbox.md @@ -780,7 +780,7 @@ reference-depth treatment this chapter gave C++. ---

verified — on the Fedora 44 -reference host this session (kernel 7.1.4-204.fc44, GCC 16.1.1, clang +reference host this session (kernel 7.1, GCC 16.1.1, clang 22.1.8, CMake 4.3.0, Ninja, gdb 17.2, Conan 2.30.0): LSP_LANG=cpp REPO_ROOT=$(cd ../.. && pwd) lua verify.lua reported PASS 20 / FAIL 0, and diff --git a/_docs/47-go-toolbox.md b/_docs/47-go-toolbox.md index f721d70..eb22d8f 100644 --- a/_docs/47-go-toolbox.md +++ b/_docs/47-go-toolbox.md @@ -945,7 +945,7 @@ treatment this chapter and Chapter 46 gave C++ and Go. ---

verified — on the Fedora 44 -reference host this session (kernel 7.1.4-204.fc44, go1.26.5, offline, no +reference host this session (kernel 7.1, go1.26.5, offline, no network access used): LSP_LANG=go REPO_ROOT=$(cd ../.. && pwd) lua verify.lua reported PASS 16 / FAIL 0, and diff --git a/_docs/48-rust-toolbox.md b/_docs/48-rust-toolbox.md index 78995ef..6155766 100644 --- a/_docs/48-rust-toolbox.md +++ b/_docs/48-rust-toolbox.md @@ -80,7 +80,7 @@ host whose global default is `stable` and which also has `nightly` and ```console $ rustup show Default host: x86_64-unknown-linux-gnu -rustup home: /home/rsedor/.rustup +rustup home: ~/.rustup installed toolchains -------------------- @@ -92,7 +92,7 @@ nightly-x86_64-unknown-linux-gnu active toolchain ---------------- name: 1.97.1-x86_64-unknown-linux-gnu -active because: overridden by '/home/rsedor/Dev/linux-systems-programming/examples/48-rust-toolbox/rust/rust-toolchain.toml' +active because: overridden by '/examples/48-rust-toolbox/rust/rust-toolchain.toml' installed targets: x86_64-unknown-linux-gnu ``` @@ -183,7 +183,7 @@ There is no `[dependencies]`. The crate is zero-dependency on purpose, and ```console $ cargo tree --offline -toolbox v0.1.0 (/home/rsedor/Dev/linux-systems-programming/examples/48-rust-toolbox/rust) +toolbox v0.1.0 (/examples/48-rust-toolbox/rust) ``` One node. `Cargo.lock` holds exactly one package — itself. That is not @@ -315,7 +315,7 @@ No output, exit 0. The loud half, run on the same host in the same session: ```console $ rustfmt --edition 2024 --check fixtures/misformatted.rs -Diff in /home/rsedor/Dev/linux-systems-programming/examples/48-rust-toolbox/rust/fixtures/misformatted.rs:10: +Diff in /examples/48-rust-toolbox/rust/fixtures/misformatted.rs:10: // Do not "fix" the formatting below. The wrong spacing, the 4-into-2 indent, // the missing trailing comma, and the crammed `if` are the assertion. @@ -391,7 +391,7 @@ Clean first: ```console $ cargo clippy --offline --all-targets -- -D warnings - Checking toolbox v0.1.0 (/home/rsedor/Dev/linux-systems-programming/examples/48-rust-toolbox/rust) + Checking toolbox v0.1.0 (/examples/48-rust-toolbox/rust) Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.05s ``` @@ -405,7 +405,7 @@ Now the same command with the feature on: ```console $ cargo clippy --offline --features lintbait --all-targets -- -D warnings - Checking toolbox v0.1.0 (/home/rsedor/Dev/linux-systems-programming/examples/48-rust-toolbox/rust) + Checking toolbox v0.1.0 (/examples/48-rust-toolbox/rust) error: unneeded `return` statement --> src/lintbait.rs:13:5 | @@ -481,7 +481,7 @@ made `pub` for testing's sake. ```console $ cargo test --offline - Compiling toolbox v0.1.0 (/home/rsedor/Dev/linux-systems-programming/examples/48-rust-toolbox/rust) + Compiling toolbox v0.1.0 (/examples/48-rust-toolbox/rust) Finished `test` profile [unoptimized + debuginfo] target(s) in 0.10s Running unittests src/main.rs (target/debug/deps/toolbox-6b13b413a4fa8296) @@ -999,7 +999,7 @@ that network half: show it, name the durable identifier, never gate it. ---

verified — on the Fedora 44 -reference host this session (kernel 7.1.5-201.fc44, rustc/cargo 1.97.1 via +reference host this session (kernel 7.1, rustc/cargo 1.97.1 via rustup, clippy 0.1.97, rustfmt 1.9.0-stable, offline, no network access used): LSP_LANG=rust REPO_ROOT=$(cd ../.. && pwd) lua verify.lua reported PASS 20 / FAIL 0, and diff --git a/_plans/r15-ch46-plan.md b/_plans/r15-ch46-plan.md index 76a2b01..a4b4726 100644 --- a/_plans/r15-ch46-plan.md +++ b/_plans/r15-ch46-plan.md @@ -93,6 +93,6 @@ asides — never gated. Should merge on standard host-gate + CI-green, no mixed ## Gate (host run, 2026-08-01/02) - `verify.lua` PASS 20/0 · `validate.py` → validate: OK · `test-all-examples --only 46-cpp-toolbox` PASS - Verification CLEAN (local, no VM). Only ccache/mold shown-not-gated (absent on host); GCC-vs-clang diagnostic asides framed as illustrative live-session, not gated. -- Reference toolchain: GCC 16.1.1, clang 22.1.8, CMake 4.3.0, gdb 17.2, Conan 2.30.0, kernel 7.1.4-204.fc44. +- Reference toolchain: GCC 16.1.1, clang 22.1.8, CMake 4.3.0, gdb 17.2, Conan 2.30.0, kernel 7.1. ## Merge: AUTONOMOUS (user authorized for r15). diff --git a/_plans/r17-ch48-plan.md b/_plans/r17-ch48-plan.md index e370669..dbf1b58 100644 --- a/_plans/r17-ch48-plan.md +++ b/_plans/r17-ch48-plan.md @@ -120,7 +120,7 @@ Merge-safe either way; verify.lua identical; footer states which optional tools - Concurrency lens = tooling concurrency: cargo build-graph `-j` + release codegen-units, libtest's thread-per-test model (`--test-threads=1`, captured), and nextest's process-per-test isolation. -## Gate matrix (host run, 2026-08-04 → 08-07, Fedora 44, kernel 7.1.5-201.fc44, offline) +## Gate matrix (host run, 2026-08-04 → 08-07, Fedora 44, kernel 7.1, offline) | gate | result | | --- | --- | | `lua verify.lua` (LSP_LANG=rust) | **PASS 20 / FAIL 0**, 4 informational SKIP (E-H) | diff --git a/_plans/r18-ch49-plan.md b/_plans/r18-ch49-plan.md index dd77cff..50ddca2 100644 --- a/_plans/r18-ch49-plan.md +++ b/_plans/r18-ch49-plan.md @@ -13,9 +13,9 @@ parallelism is *execution* (a machine doing many things at once). The whole comp is set here; ch50–56 (pthreads → std threading → Boost.Thread → C++20 coroutines → Boost.Fiber → Boost.Asio → capstone comparison) all lean on it. See "ch55 scope" at the end of this file. -## Host audit (run 2026-08-07, Fedora 44, kernel 7.1.5-201.fc44) +## Host audit (run 2026-08-07, Fedora 44, kernel 7.1) - GCC **16.1.1**, clang **22.1.8**, CMake **4.3.0**, Ninja 1.13.0, Conan **2.30.0**. -- CPU: 16 logical / 8 physical cores, 2 threads-per-core, **1 NUMA node** (i7-11800H). +- CPU: 16 logical / 8 physical cores, 2 threads-per-core, **1 NUMA node**. - Boost **1.90** system-installed (`boost-devel`), incl. `libboost_{context,fiber,thread}.so` → ch52/ch54 have their libraries already; **no Conan fetch needed for Boost on this host**. - `libtbb.so.12` runtime present but **`tbb-devel` ABSENT** → `std::execution::par` (C++17 parallel diff --git a/_plans/r19-ch50-plan.md b/_plans/r19-ch50-plan.md index edc0aa3..4a12add 100644 --- a/_plans/r19-ch50-plan.md +++ b/_plans/r19-ch50-plan.md @@ -27,7 +27,7 @@ starts being a task with a tid, a name, a stack, an affinity mask, and a policy. grounded in measured facts, with `native_handle()` as the sanctioned bridge. - **D4 — Autonomous through PR; the user merges.** -## Host audit (run 2026-08-16, Fedora 44, kernel 7.1.5-201.fc44) +## Host audit (run 2026-08-16, Fedora 44, kernel 7.1) All measured with real probe programs, not inferred: diff --git a/_plans/r20-ch51-plan.md b/_plans/r20-ch51-plan.md index f29ec58..33d0f36 100644 --- a/_plans/r20-ch51-plan.md +++ b/_plans/r20-ch51-plan.md @@ -24,7 +24,7 @@ at all* when it does not, and both halves are measurable with a syscall counter. `timeout` (exit 124) with every thread showing `wchan=futex_do_wait` in procfs. - **D3 — Autonomous through PR; the user merges.** -## Host audit (run 2026-08-17, Fedora 44, kernel 7.1.5-201.fc44, glibc 2.43) +## Host audit (run 2026-08-17, Fedora 44, kernel 7.1, glibc 2.43) Measured with `strace -f -c -e trace=futex`, not inferred: diff --git a/_plans/r25-ch56-plan.md b/_plans/r25-ch56-plan.md index caeb177..c3bcf0d 100644 --- a/_plans/r25-ch56-plan.md +++ b/_plans/r25-ch56-plan.md @@ -31,7 +31,7 @@ two numbers in the compendium are strictly comparable. ch56 runs **one workload* **all six** and measures them with **the same two instruments**, which is the only way the comparison is a comparison rather than a table of quotations. -## Host audit (2026-08-22, Fedora 44, kernel 7.1.8-200.fc44) +## Host audit (2026-08-22, Fedora 44, kernel 7.1) GCC 16.1.1, clang 22.1.8, CMake 4.3.0, Ninja 1.13.0, Conan 2.30.0, Lua 5.4.8, Boost 1.90.0 (`boost-devel-1.90.0-7.fc44`), 16 logical / 8 physical CPUs. diff --git a/_plans/r26-full-matrix-gate.md b/_plans/r26-full-matrix-gate.md index afeb3e7..6bab009 100644 --- a/_plans/r26-full-matrix-gate.md +++ b/_plans/r26-full-matrix-gate.md @@ -33,7 +33,7 @@ ran for real. JUnit at `build-logs/r26-full-matrix.xml`. | | | | --- | --- | -| host kernel | 7.1.8-200.fc44 | +| host kernel | 7.1 | | host glibc / libstdc++ | 2.43 / **16.2.1-2.fc44** (`libstdc++.so.6.0.36`) | | host toolchain | g++ 16.1.1, clang 22.1.8, CMake 4.3.0, Ninja 1.13.0 (at `~/.local/bin/ninja`), Conan 2.30.0, Lua 5.4.8 | | guest kernel | 6.19.10-300.fc44 | diff --git a/assets/diagrams/34-ns-debugging-map.excalidraw b/assets/diagrams/34-ns-debugging-map.excalidraw index a35e708..c3469e5 100644 --- a/assets/diagrams/34-ns-debugging-map.excalidraw +++ b/assets/diagrams/34-ns-debugging-map.excalidraw @@ -56,13 +56,13 @@ "updated": 1, "link": null, "locked": false, - "text": "host (rootless user rsedor, uid 1000)", + "text": "host (rootless user user, uid 1000)", "fontSize": 12, "fontFamily": 1, "textAlign": "left", "verticalAlign": "top", "containerId": null, - "originalText": "host (rootless user rsedor, uid 1000)", + "originalText": "host (rootless user user, uid 1000)", "lineHeight": 1.25, "baseline": 12 }, @@ -637,13 +637,13 @@ "updated": 1, "link": null, "locked": false, - "text": "subuid rsedor:524288:65536", + "text": "subuid user:524288:65536", "fontSize": 14, "fontFamily": 1, "textAlign": "left", "verticalAlign": "top", "containerId": null, - "originalText": "subuid rsedor:524288:65536", + "originalText": "subuid user:524288:65536", "lineHeight": 1.25, "baseline": 14 }, diff --git a/assets/diagrams/34-ns-debugging-map.svg b/assets/diagrams/34-ns-debugging-map.svg index f364e4e..2034641 100644 --- a/assets/diagrams/34-ns-debugging-map.svg +++ b/assets/diagrams/34-ns-debugging-map.svg @@ -1,7 +1,7 @@ -host (rootless user rsedor, uid 1000) +host (rootless user user, uid 1000) podman's user namespace (uid 0 in container == uid 1000 on host) @@ -19,7 +19,7 @@ Name: app State: S (sleeping) readlink /proc/1/exe -> /usr/local/bin/app -subuid rsedor:524288:65536 +subuid user:524288:65536 uid_map: 0->1000 (1), 1->524288 (65536) zombie scan (podman exec): diff --git a/examples/01-hello-syscalls/README.md b/examples/01-hello-syscalls/README.md index 4e9786f..6c0f67f 100644 --- a/examples/01-hello-syscalls/README.md +++ b/examples/01-hello-syscalls/README.md @@ -49,8 +49,8 @@ a time. It uses `scripts/lib/checks.lua` to run `./demo.sh $LSP_LANG run` and asserts the output matches `pid %d+ on Linux`. Exit 0 = pass, 1 = fail, 77 = skip. -Verified on the Fedora 44 reference host (kernel 7.1.3-200.fc44): all three -languages PASS and print `pid on Linux 7.1.3-200.fc44.x86_64 (x86_64)`. +Verified on the Fedora 44 reference host (kernel 7.1): all three +languages PASS and print `pid on Linux 7.1 (x86_64)`. ## Mapping to a chapter diff --git a/examples/06-concurrency-three-ways/README.md b/examples/06-concurrency-three-ways/README.md index d9e9b9e..d46bdd5 100644 --- a/examples/06-concurrency-three-ways/README.md +++ b/examples/06-concurrency-three-ways/README.md @@ -86,5 +86,5 @@ a time and asserts, per language: `kill -INT` after 100 ms yields only well-formed partial hash lines on stdout, no summary line, `parhash: interrupted` on stderr, and exit 130. -Verified on the Fedora 44 reference host (kernel 7.1.3-200.fc44): all three +Verified on the Fedora 44 reference host (kernel 7.1): all three languages PASS all 8 checks, Go under the race detector. diff --git a/examples/25-shared-state-and-the-futex/README.md b/examples/25-shared-state-and-the-futex/README.md index a369b67..5eb607d 100644 --- a/examples/25-shared-state-and-the-futex/README.md +++ b/examples/25-shared-state-and-the-futex/README.md @@ -148,5 +148,5 @@ time and asserts, per language (25 checks each): The `--buggy` race is a sanitizer/`-race` chapter demo and is deliberately outside the passing verify. -Verified on the Fedora 44 reference host (kernel 7.1.3-200.fc44, GCC 16.1.1, +Verified on the Fedora 44 reference host (kernel 7.1, GCC 16.1.1, go1.26.5, rustc 1.97.1): all three languages PASS 25/25, Go under `-race`. diff --git a/examples/26-atomics-and-lock-free/README.md b/examples/26-atomics-and-lock-free/README.md index 3519132..0d3ce37 100644 --- a/examples/26-atomics-and-lock-free/README.md +++ b/examples/26-atomics-and-lock-free/README.md @@ -134,5 +134,5 @@ time and asserts, per language: 5. no arguments prints `usage: spscring --capacity K --items N [--pad on|off]` on stderr and exits 2. -Verified on the Fedora 44 reference host (kernel 7.1.3-200.fc44): all three +Verified on the Fedora 44 reference host (kernel 7.1): all three languages PASS all 11 checks, Go under the race detector. diff --git a/examples/34-our-programs-in-containers/README.md b/examples/34-our-programs-in-containers/README.md index b35017c..1668207 100644 --- a/examples/34-our-programs-in-containers/README.md +++ b/examples/34-our-programs-in-containers/README.md @@ -195,4 +195,4 @@ containers rather than trusting exit codes: checks passed or not. All three languages pass all 16 checks on the reference host (Fedora 44, -kernel 7.1.3-200.fc44, podman 5.8.4 rootless). +kernel 7.1, podman 5.8.4 rootless). diff --git a/examples/35-virtualization-and-kvm/README.md b/examples/35-virtualization-and-kvm/README.md index b968195..aab84bb 100644 --- a/examples/35-virtualization-and-kvm/README.md +++ b/examples/35-virtualization-and-kvm/README.md @@ -95,7 +95,7 @@ a time. It asserts, per language: - bad usage (unknown `--bench` value, missing flag value, unknown flag, non-numeric or zero `--iters`) exits 2 and prints the usage line. -Real host numbers from this machine (Fedora 44, kernel 7.1.3-200.fc44, +Real host numbers from this machine (Fedora 44, kernel 7.1, `examples/` on an NVMe-backed btrfs filesystem — not `/tmp`): | lang | syscall (ns/call) | mem (GB/s) | io (ops/s) | diff --git a/examples/39-benchmarking-without-lies/README.md b/examples/39-benchmarking-without-lies/README.md index 86d52cb..1df6226 100644 --- a/examples/39-benchmarking-without-lies/README.md +++ b/examples/39-benchmarking-without-lies/README.md @@ -176,6 +176,6 @@ time and asserts, per language: 4. no flags, an unknown `--op`, and `--warmup >= --iters` each exit 2 with a usage line. -Verified on the Fedora 44 reference host (kernel 7.1.3-200.fc44, GCC 16.1.1, +Verified on the Fedora 44 reference host (kernel 7.1, GCC 16.1.1, go1.26.5, rustc 1.97.1): all three languages PASS all 42 checks, repeatably across multiple runs. diff --git a/examples/45-linux-analysis-suites/README.md b/examples/45-linux-analysis-suites/README.md index 8f47c9d..c3683bd 100644 --- a/examples/45-linux-analysis-suites/README.md +++ b/examples/45-linux-analysis-suites/README.md @@ -116,7 +116,7 @@ builds the image and drives a real container: - the container and the built image are removed at the end, whether the checks passed or not. -A real run on the reference host (Fedora 44, kernel 7.1.4-204.fc44, podman +A real run on the reference host (Fedora 44, kernel 7.1, podman 5.8.4 rootless) passes all 10 checks: ``` From 5666b715f4f1476145628c2a3837ca7c1b296deb Mon Sep 17 00:00:00 2001 From: PatternCatalyst Date: Fri, 23 Oct 2026 10:31:05 -0400 Subject: [PATCH 2/6] fix(scripts): scrub run logs of machine identifiers after each runner pass --- scripts/test-all-examples.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/scripts/test-all-examples.py b/scripts/test-all-examples.py index 15ed6ab..ad4f21b 100755 --- a/scripts/test-all-examples.py +++ b/scripts/test-all-examples.py @@ -365,6 +365,19 @@ def write_junit(path: str, selected: list[dict], results: dict) -> None: ET.ElementTree(suite).write(path, encoding="utf-8", xml_declaration=True) +def scrub_logs() -> None: + """Strip machine identifiers (kernel build, paths, account) from the run logs. + + Chapter transcripts are pasted from these logs, so scrub them before anyone + copies a line (see CLAUDE.md, "Publishing rule"). + """ + tool = REPO_ROOT / "scripts" / "host_ids.py" + if tool.is_file() and LOG_DIR.is_dir(): + subprocess.run([sys.executable, str(tool), "scrub", "--repo", + str(REPO_ROOT), str(LOG_DIR)], + stdout=subprocess.DEVNULL, check=False) + + def main(argv: list[str]) -> int: args = parse_args(argv) try: @@ -439,6 +452,8 @@ def main(argv: list[str]) -> int: print(f"\n{passed} passed, {failed} failed, {skipped} skipped" f" (logs in {LOG_DIR.relative_to(REPO_ROOT)}/)") + scrub_logs() + if args.junit: write_junit(args.junit, selected, results) print(f"junit report: {args.junit}") From 1e876792a8565ff6014598d3f2b4b3e604fa880e Mon Sep 17 00:00:00 2001 From: PatternCatalyst Date: Fri, 23 Oct 2026 10:31:05 -0400 Subject: [PATCH 3/6] ci: check tracked files for machine and owner identifiers Adds scripts/host_ids.py, a host-ids job in validate.yml and the publishing rule in CLAUDE.md. --- .github/workflows/validate.yml | 9 + CLAUDE.md | 23 + scripts/host_ids.py | 741 +++++++++++++++++++++++++++++++++ 3 files changed, 773 insertions(+) create mode 100755 scripts/host_ids.py diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index c142d75..f727bef 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -37,6 +37,15 @@ jobs: - name: Run validate.py run: python3 scripts/validate.py + host-ids: + runs-on: ubuntu-latest + steps: + - name: Check out repo + uses: actions/checkout@v5 + + - name: No machine or owner identifiers in tracked files + run: python3 scripts/host_ids.py check + smoke-go: runs-on: ubuntu-latest steps: diff --git a/CLAUDE.md b/CLAUDE.md index 27d745d..d3cc32d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -87,3 +87,26 @@ Ruby), examples in `examples/NN-slug/{cpp,go,rust}/`, chapters in rename it without fixing both links. **Internal working plans and capture dumps must set `published: false` in their front matter** so they stay in git for resumability without shipping to the site. + +## Publishing rule: nothing identifies the machine or its owner + +The repo is public, so no tracked file may name the development machine, its owner +or anything that helps locate or attack it later: + +- No absolute home-directory path (under /home or /Users), no account name, no + hostname. Write `/...` or `~/...`. The lab guests' own `fedora` account and + its home directory are book content, not the host's. +- No laptop model (DMI `product_name` is `"redacted"`), no CPU model or model number. + The CPU is a class ("Intel 8-core/16-thread laptop CPU"); prose names its + properties (SMT, cache sizes, frequency driver), never the part. +- No host kernel build number or build date: give `major.minor` (for example + `7.1`) and the preempt model. The lab guests' pinned kernel (`systems-target`) is + book content and is allowed by path in `.host-scrub.toml`. +- No `/etc/machine-id`, DMI serial or UUID, MAC or IP address, `root=UUID=` or + BOOT_IMAGE. +- Generated output is scrubbed before it is committed: `python3 scripts/host_ids.py + scrub ` on a results directory, `scripts/host_ids.py filter` on a captured + transcript. `scripts/test-all-examples.py` scrubs `build-logs/` after each run. +- `python3 scripts/host_ids.py check` runs in CI (`host-ids` job) and fails the build + on a hit. Allow a legitimate hit by path and category in `.host-scrub.toml`; the + file holds no values. diff --git a/scripts/host_ids.py b/scripts/host_ids.py new file mode 100755 index 0000000..6e27abf --- /dev/null +++ b/scripts/host_ids.py @@ -0,0 +1,741 @@ +#!/usr/bin/env python3 +"""Find and remove details that identify the development machine or its owner. + +A public repository must not name the machine it was built on: home paths, the +account name, the hostname, the laptop and CPU model, the exact kernel build, the +machine-id, MAC addresses, the root filesystem UUID. This tool finds them and +replaces them, without ever writing them down itself: this machine's own values +are read at run time, everything else is matched by generic patterns. + + host_ids.py check [--repo DIR] tracked files; exit 1 on a hit (CI-safe) + host_ids.py scrub [--repo DIR] [PATH...] rewrite files in place (default: tracked) + host_ids.py scrub --dry-run ... change nothing; exit 1 if a file would change + host_ids.py filter scrub stdin to stdout (captured logs) + host_ids.py history [--repo DIR] [--emit-rules FILE] + scan every blob and message in all refs; + optionally write git filter-repo rules + host_ids.py local [--repo DIR] inventory of local copies of old history + host_ids.py self-test planted cases in a throwaway repo + +Hits are reported as `path:line: category`, never with the matched value, so a CI +log does not republish what it found. The rules file written by --emit-rules does +hold the values: it must live outside the repository and be deleted after use. + +Optional per-repo config `.host-scrub.toml` (committed; holds no identifiers): + + skip = ["scripts/validate.py"] # files never checked or scrubbed + cpu_class = "Intel 8-core/16-thread laptop CPU" # override the derived class + [allow] # path globs exempt from a category + kernel-build = ["scripts/lab/*.sh"] + +Extra literals that identify the machine but are not discoverable (an old hostname, +a former account) go in an untracked file, one per line, `value` or +`value==>replacement`: $HOST_SCRUB_EXTRA, else ~/.config/host-scrub/extra.txt. + +Stdlib only; Python 3.11 or newer. +""" + +from __future__ import annotations + +import argparse +import fnmatch +import getpass +import gzip +import os +import platform +import re +import socket +import subprocess +import sys +import tempfile +import tomllib +from dataclasses import dataclass, field +from pathlib import Path + +SELF = Path(__file__).resolve() +CONFIG_NAME = ".host-scrub.toml" +# Names too common to search for as words; a CI runner's account is "runner". +COMMON_NAMES = { + "root", "user", "runner", "fedora", "ubuntu", "debian", "admin", "localhost", + "github", "build", "builder", "docker", "vagrant", "ec2-user", "cloud-user", +} # fmt: skip +# Placeholders that are fine after /home/ or /Users/. +HOME_PLACEHOLDERS = {"user", "you", "username", "me", "name", "runner"} +PLACEHOLDER_ALT = "|".join(sorted(HOME_PLACEHOLDERS)) + + +# ----------------------------------------------------------------- the machine +@dataclass +class Runtime: + """This machine's identifying values, read now and never written to disk.""" + + account: list[str] = field(default_factory=list) + hostname: list[str] = field(default_factory=list) + home: str = "" + repo_path: str = "" + cpu_model: str = "" + cpu_class: str = "CPU" + products: list[str] = field(default_factory=list) + kernel_release: str = "" + kernel_version: str = "" + machine_ids: list[str] = field(default_factory=list) + macs: list[str] = field(default_factory=list) + boot_uuids: list[str] = field(default_factory=list) + extra: list[tuple[str, str]] = field(default_factory=list) + + +def _read(path: str) -> str: + try: + return Path(path).read_text(encoding="utf-8", errors="replace").strip() + except OSError: + return "" + + +def _run(*args: str) -> str: + try: + return subprocess.run( + args, capture_output=True, text=True, check=True + ).stdout.strip() + except (OSError, subprocess.CalledProcessError): + return "" + + +def _cpu_class() -> str: + info = _read("/proc/cpuinfo") + vendor = {"GenuineIntel": "Intel", "AuthenticAMD": "AMD"} + v = next((vendor.get(m) for m in re.findall(r"vendor_id\s*:\s*(\S+)", info)), None) + if not v and platform.system() == "Darwin": + brand = _run("sysctl", "-n", "machdep.cpu.brand_string") + v = "Apple" if brand.startswith("Apple") else "Intel" + cores = { + (p, c) + for p, c in re.findall( + r"physical id\s*:\s*(\d+).*?core id\s*:\s*(\d+)", info, re.DOTALL + ) + } + threads = os.cpu_count() or 0 + chassis = _read("/sys/class/dmi/id/chassis_type") + kind = "laptop " if chassis in {"8", "9", "10", "14", "31", "32"} else "" + shape = f"{len(cores)}-core/{threads}-thread " if cores and threads else "" + return f"{v or 'x86'} {shape}{kind}CPU".replace(" ", " ") + + +def _extra_literals() -> list[tuple[str, str]]: + path = os.environ.get("HOST_SCRUB_EXTRA") or str( + Path.home() / ".config/host-scrub/extra.txt" + ) + out = [] + for line in _read(path).splitlines(): + line = line.strip() + if not line or line.startswith("#"): + continue + value, _, repl = line.partition("==>") + out.append((value, repl or "redacted")) + return out + + +def gather(repo: Path | None) -> Runtime: + rt = Runtime() + home = os.environ.get("HOME", "") + names = set() + try: + names.add(getpass.getuser()) + except (OSError, KeyError): + pass + if m := re.match(r"/(?:home|Users)/([^/]+)", home): + names.add(m.group(1)) + rt.home = m.group(0) + rt.account = sorted(n for n in names if n) + host = socket.gethostname() + rt.hostname = sorted({h for h in (host, host.split(".")[0]) if h}) + if repo is not None: + rt.repo_path = str(repo.resolve()) + for line in _read("/proc/cpuinfo").splitlines(): + if line.startswith("model name"): + rt.cpu_model = line.split(":", 1)[1].strip() + break + if not rt.cpu_model and platform.system() == "Darwin": + rt.cpu_model = _run("sysctl", "-n", "machdep.cpu.brand_string") + rt.cpu_class = _cpu_class() + for f in ("product_name", "product_version", "product_family", "board_name"): + v = _read(f"/sys/class/dmi/id/{f}") + if len(v) >= 4 and not re.fullmatch( + r"(?i)none|default string|to be filled.*|\d+", v + ): + rt.products.append(v) + if platform.system() == "Linux": + rt.kernel_release = _run("uname", "-r") + rt.kernel_version = _run("uname", "-v") + rt.machine_ids = sorted( + {v for v in (_read("/etc/machine-id"), _read("/var/lib/dbus/machine-id")) if v} + ) + for d in Path("/sys/class/net").glob("*"): + mac = _read(str(d / "address")).lower() + if mac and d.name != "lo" and mac != "00:00:00:00:00:00": + rt.macs.append(mac) + rt.macs = sorted(set(rt.macs)) + rt.boot_uuids = re.findall(r"UUID=([0-9a-fA-F-]{36})", _read("/proc/cmdline")) + rt.extra = _extra_literals() + return rt + + +# ----------------------------------------------------------------- the rules +@dataclass(frozen=True) +class Rule: + category: str + pattern: re.Pattern[str] + replacement: str # a re.sub template + literal: str = "" # set for a runtime literal; used for filter-repo rules + + +def _lit( + category: str, value: str, repl: str, word: bool = False, icase: bool = False +) -> Rule: + pat = re.escape(value) + if word: + pat = rf"(? str: + m = re.match(r"(\d+\.\d+)", release) + return m.group(1) if m else "redacted" + + +def _preempt(version: str) -> str: + m = re.search(r"PREEMPT_RT|PREEMPT_DYNAMIC|PREEMPT\b", version) + return m.group(0) if m else "SMP" + + +INTEL_PART = r"i[3579]-\d{4,5}[A-Z]{0,2}" +KERNEL_BUILD = ( + r"(? list[Rule]: + """Patterns that catch identifiers from any machine, not just this one. + + A match becomes this machine's CPU class when the vendor agrees, else the bare vendor. + """ + + def cls(vendor: str) -> str: + c = cpu_class if cpu_class.startswith(vendor) else f"{vendor} CPU" + return c.replace("\\", "\\\\") + + cpu, amd = cls("Intel"), cls("AMD") + return [ + Rule( + "cpu-model", + re.compile( + rf"(?:\d+(?:st|nd|rd|th) Gen )?Intel\(R\) Core\(TM\) (?:{INTEL_PART}|Ultra \d \d{{3}}[A-Z]?)" + r"(?: (?:CPU )?@ [\d.]+GHz)?" + ), + cpu, + ), + Rule( + "cpu-model", + re.compile(rf"(?" + ), + Rule("boot-uuid", re.compile(r"BOOT_IMAGE=\S+"), "BOOT_IMAGE="), + Rule( + "home-path", + re.compile( + rf"/(?:home|Users)/(?!(?:{PLACEHOLDER_ALT})(?:/|\b))[A-Za-z0-9._-]+(?=/|\b)" + ), + "~", + ), + ] + + +def runtime_rules(rt: Runtime) -> list[Rule]: + """Literal rules for this machine's values. Longest and most specific first.""" + rules: list[Rule] = [] + if rt.repo_path and rt.home and rt.repo_path.startswith(rt.home): + rules.append(_lit("home-path", rt.repo_path, "")) + for value, repl in rt.extra: + rules.append(_lit("extra", value, repl)) + if rt.home: + rules.append(_lit("home-path", rt.home, "~")) + if rt.cpu_model: + rules.append(_lit("cpu-model", rt.cpu_model, rt.cpu_class)) + for p in sorted(rt.products, key=len, reverse=True): + rules.append(_lit("product-name", p, "redacted")) + if rt.kernel_version and "PREEMPT_RT" not in rt.kernel_version: + rules.append( + _lit("kernel-version", rt.kernel_version, _preempt(rt.kernel_version)) + ) + if rt.kernel_release: + rules.append( + _lit("kernel-build", rt.kernel_release, _major_minor(rt.kernel_release)) + ) + for mid in rt.machine_ids: + rules.append(_lit("machine-id", mid, "", word=True)) + for mac in rt.macs: + rules.append(_lit("mac", mac, "00:00:00:00:00:00", icase=True)) + for u in rt.boot_uuids: + rules.append(_lit("boot-uuid", u, "", icase=True)) + for h in sorted(rt.hostname, key=len, reverse=True): + if len(h) >= 4 and h.lower() not in COMMON_NAMES: + rules.append(_lit("hostname", h, "host", word=True)) + for a in rt.account: + if len(a) >= 3 and a.lower() not in COMMON_NAMES: + rules.append(_lit("account", a, "user", word=True)) + return rules + + +def all_rules(rt: Runtime) -> list[Rule]: + return runtime_rules(rt) + generic_rules(rt.cpu_class) + + +# ----------------------------------------------------------------- config +@dataclass +class Config: + skip: list[str] = field(default_factory=list) + allow: dict[str, list[str]] = field(default_factory=dict) + cpu_class: str = "" + + def skipped(self, rel: str) -> bool: + return any(fnmatch.fnmatch(rel, g) for g in self.skip) + + def allowed(self, category: str, rel: str) -> bool: + return any(fnmatch.fnmatch(rel, g) for g in self.allow.get(category, [])) + + +def load_config(repo: Path) -> Config: + path = repo / CONFIG_NAME + if path.is_file(): + text = path.read_text(encoding="utf-8") + else: # a bare mirror: read the committed config from HEAD + text = _run("git", "-C", str(repo), "show", f"HEAD:{CONFIG_NAME}") + if not text: + return Config() + data = tomllib.loads(text) + return Config( + skip=list(data.get("skip", [])), + allow={k: list(v) for k, v in data.get("allow", {}).items()}, + cpu_class=str(data.get("cpu_class", "")), + ) + + +# ----------------------------------------------------------------- files +def repo_root(start: Path) -> Path: + """The work tree root, or the repository itself when it is bare (a mirror clone).""" + out = _run("git", "-C", str(start), "rev-parse", "--show-toplevel") + if out: + return Path(out) + if _run("git", "-C", str(start), "rev-parse", "--is-bare-repository") == "true": + return start.resolve() + sys.exit(f"host_ids: {start} is not a git repository") + + +def tracked(repo: Path) -> list[str]: + res = subprocess.run( + ["git", "-C", str(repo), "ls-files", "-z"], capture_output=True, check=True + ) + return [n for n in res.stdout.decode().split("\0") if n] + + +def decode(raw: bytes) -> str | None: + if raw[:2] == b"\x1f\x8b": + try: + raw = gzip.decompress(raw) + except (OSError, EOFError): + return None + try: + return raw.decode("utf-8") + except UnicodeDecodeError: + return None + + +def gzip_n(data: bytes) -> bytes: + """Compress like `gzip -n`: no stored file name, mtime 0.""" + return gzip.compress(data, mtime=0) + + +def scrub_text(text: str, rules: list[Rule], cfg: Config, rel: str) -> str: + for r in rules: + if not cfg.allowed(r.category, rel): + text = r.pattern.sub(r.replacement, text) + return text + + +def hits(text: str, rules: list[Rule], cfg: Config, rel: str) -> list[tuple[int, str]]: + found = [] + for r in rules: + if cfg.allowed(r.category, rel): + continue + for m in r.pattern.finditer(text): + if r.category == "home-path" and m.group(0) in ("~", ""): + continue + found.append((text.count("\n", 0, m.start()) + 1, r.category)) + return sorted(set(found)) + + +def is_self(repo: Path, rel: str) -> bool: + try: + return (repo / rel).resolve() == SELF + except OSError: + return False + + +# ----------------------------------------------------------------- commands +def setup(repo_arg: str | None) -> tuple[Path, Config, list[Rule]]: + repo = repo_root(Path(repo_arg or ".")) + cfg = load_config(repo) + rt = gather(repo) + if cfg.cpu_class: + rt.cpu_class = cfg.cpu_class + return repo, cfg, all_rules(rt) + + +def cmd_check(repo: Path, cfg: Config, rules: list[Rule]) -> int: + n_files = n_hits = 0 + for rel in tracked(repo): + if cfg.skipped(rel) or is_self(repo, rel): + continue + try: + text = decode((repo / rel).read_bytes()) + except OSError: + continue + if text is None: + continue + n_files += 1 + for line, cat in hits(text, rules, cfg, rel): + print(f"{rel}:{line}: {cat}") + n_hits += 1 + print(f"host_ids check: {n_files} text file(s), {n_hits} hit(s)", file=sys.stderr) + return 1 if n_hits else 0 + + +def cmd_scrub( + repo: Path, cfg: Config, rules: list[Rule], paths: list[str], dry_run: bool +) -> int: + if paths: + files = [] + for p in map(Path, paths): + if p.is_dir(): + files += [ + f + for f in sorted(p.rglob("*")) + if f.is_file() and ".git" not in f.parts + ] + elif p.is_file(): + files.append(p) + else: + files = [repo / rel for rel in tracked(repo)] + changed = [] + for f in files: + try: + rel = str(f.resolve().relative_to(repo)) + except ValueError: + rel = str(f) + if cfg.skipped(rel) or f.resolve() == SELF: + continue + try: + raw = f.read_bytes() + except OSError: + continue + text = decode(raw) + if text is None: + continue + new = scrub_text(text, rules, cfg, rel) + is_gz = raw[:2] == b"\x1f\x8b" + clean_header = not is_gz or (raw[3] & 0x08 == 0 and raw[4:8] == b"\0\0\0\0") + if new == text and clean_header: + continue + changed.append(rel) + if not dry_run: + data = new.encode("utf-8") + f.write_bytes(gzip_n(data) if is_gz else data) + verb = "would change" if dry_run else "changed" + print(f"host_ids scrub: {verb} {len(changed)} file(s)", file=sys.stderr) + for rel in changed[:50]: + print(f" {rel}", file=sys.stderr) + return 1 if (dry_run and changed) else 0 + + +def cmd_filter(rules: list[Rule]) -> int: + sys.stdout.write(scrub_text(sys.stdin.read(), rules, Config(), "-")) + return 0 + + +def _replacement_for(rule: Rule, value: str) -> str: + """The text a matched value becomes, computed with the rule's own template.""" + return rule.pattern.sub(rule.replacement, value, count=1) + + +def cmd_history(repo: Path, cfg: Config, rules: list[Rule], emit: str | None) -> int: + if emit and Path(emit).resolve().is_relative_to(repo): + sys.exit( + "host_ids: --emit-rules must be outside the repository (it holds the values)" + ) + objects = subprocess.run( + ["git", "-C", str(repo), "rev-list", "--all", "--objects"], + capture_output=True, text=True, check=True, + ).stdout.splitlines() # fmt: skip + paths: dict[str, str] = {} + for line in objects: + sha, _, path = line.partition(" ") + if path: + paths.setdefault(sha, path) + found: dict[str, set[str]] = {} # category -> paths + values: dict[str, str] = {} # value -> replacement + batch = subprocess.Popen( + ["git", "-C", str(repo), "cat-file", "--batch"], + stdin=subprocess.PIPE, stdout=subprocess.PIPE, + ) # fmt: skip + assert batch.stdin and batch.stdout + + def scan(text: str, rel: str) -> None: + for r in rules: + if cfg.allowed(r.category, rel) or cfg.skipped(rel): + continue + for m in r.pattern.finditer(text): + v = m.group(0) + if r.category == "home-path" and v in ("~", ""): + continue + found.setdefault(r.category, set()).add(rel) + values.setdefault(v, _replacement_for(r, v)) + + for sha, rel in paths.items(): + if Path(rel).name == SELF.name: + continue + batch.stdin.write(f"{sha}\n".encode()) + batch.stdin.flush() + header = batch.stdout.readline().split() + if len(header) < 3: + continue + data = batch.stdout.read(int(header[2])) + batch.stdout.read(1) + if header[1] != b"blob": + continue + text = decode(data) + if text is not None: + scan(text, rel) + batch.stdin.close() + batch.wait() + messages = subprocess.run( + ["git", "-C", str(repo), "log", "--all", "--format=%H%n%B%n%x00"], + capture_output=True, text=True, check=True, + ).stdout # fmt: skip + tags = _run( + "git", "-C", str(repo), "for-each-ref", "refs/tags", "--format=%(contents)" + ) + scan(messages + "\n" + tags, "") + n_commits = _run("git", "-C", str(repo), "rev-list", "--all", "--count") + print(f"host_ids history: {n_commits} commit(s), {len(paths)} path object(s)") + for cat in sorted(found): + sample = sorted(found[cat]) + more = f" (+{len(sample) - 5} more)" if len(sample) > 5 else "" + print(f" {cat}: {len(sample)} path(s): {', '.join(sample[:5])}{more}") + if not found: + print(" clean: nothing identifying in any reachable blob or message") + if emit: + lines = [ + f"{v}==>{r}" + for v, r in sorted(values.items(), key=lambda kv: len(kv[0]), reverse=True) + if v != r + ] + Path(emit).write_text( + "\n".join(lines) + ("\n" if lines else ""), encoding="utf-8" + ) + os.chmod(emit, 0o600) + print( + f" wrote {len(lines)} literal rule(s) to {emit}: review it, then delete it" + ) + return 1 if found else 0 + + +def cmd_local(repo: Path) -> int: + g = ["git", "-C", str(repo)] + print("worktrees:") + print(" " + (_run(*g, "worktree", "list") or "(none)").replace("\n", "\n ")) + remote_tips = set( + _run(*g, "for-each-ref", "--format=%(objectname)", "refs/remotes").split() + ) + print("local branches not contained in any remote-tracking branch:") + stray = 0 + for line in _run( + *g, "for-each-ref", "--format=%(refname:short) %(objectname)", "refs/heads" + ).splitlines(): + name, sha = line.split() + contained = sha in remote_tips or bool( + _run(*g, "for-each-ref", "--contains", sha, "--format=x", "refs/remotes") + ) + if not contained: + stray += 1 + print(f" {name}") + if not stray: + print(" (none)") + stashes = _run(*g, "stash", "list") + print(f"stashes: {len(stashes.splitlines()) if stashes else 0}") + reflog = _run(*g, "reflog", "--all", "--format=%H") + print(f"reflog entries: {len(reflog.splitlines()) if reflog else 0}") + print("objects:", _run(*g, "count-objects", "-v").replace("\n", ", ")) + return 0 + + +# ----------------------------------------------------------------- self-test +def self_test() -> int: + fake = Runtime( + account=["planted-acct"], + hostname=["planted-host.example", "planted-host"], + home="/home/planted-acct", + cpu_model="Intel(R) Core(TM) i9-99999X CPU @ 9.90GHz", + cpu_class="Intel 4-core/8-thread laptop CPU", + products=["Planted Laptop 9000"], + kernel_release="9.9.9-100.fc99.x86_64", + kernel_version="#1 SMP PREEMPT_DYNAMIC Mon Jan 1 00:00:00 UTC 2099", + machine_ids=["0123456789abcdef0123456789abcdef"], + macs=["02:00:5e:10:20:30"], + boot_uuids=["11111111-2222-3333-4444-555555555555"], + ) + cases = { + "a.md": "built in /home/planted-acct/Dev/proj by planted-acct\n", + "b.json": '{"product_name": "Planted Laptop 9000", "model": "i9-99999X"}\n', + "c.txt": "Linux planted-host 9.9.9-100.fc99.x86_64 #1 SMP PREEMPT_DYNAMIC " + "Mon Jan 1 00:00:00 UTC 2099\n", + "d.txt": "id 0123456789abcdef0123456789abcdef mac 02:00:5E:10:20:30 " + "root=UUID=11111111-2222-3333-4444-555555555555\n", + "e.txt": "other machine: /home/someone/x, an AMD Ryzen 7 5800X, 6.8.0-45-generic\n", + "pins.sh": "SRPM=kernel-7.2.11-200.fc44.src.rpm\nGUEST=7.2.11-200.fc44.x86_64\n", + "clean.md": "a ~/x path, /y, /home/user/z, kernel 7.2 PREEMPT_DYNAMIC\n", + } + failures = [] + with tempfile.TemporaryDirectory() as tmp: + repo = Path(tmp) + subprocess.run(["git", "init", "-q", str(repo)], check=True) + for name, body in cases.items(): + (repo / name).write_text(body, encoding="utf-8") + (repo / "g.log.gz").write_bytes( + gzip.compress(b"/home/planted-acct/log\n", mtime=123) + ) + (repo / CONFIG_NAME).write_text( + '[allow]\nkernel-build = ["pins.sh"]\n', encoding="utf-8" + ) + subprocess.run(["git", "-C", str(repo), "add", "-A"], check=True) + fake.repo_path = str(repo) + rules = all_rules(fake) + cfg = load_config(repo) + + def expect(cond: bool, what: str) -> None: + if not cond: + failures.append(what) + + for name in ("a.md", "b.json", "c.txt", "d.txt", "e.txt"): + expect(bool(hits(cases[name], rules, cfg, name)), f"check flags {name}") + expect(not hits(cases["clean.md"], rules, cfg, "clean.md"), "clean.md passes") + expect( + not hits(cases["pins.sh"], rules, cfg, "pins.sh"), + "allowed kernel pin passes", + ) + expect( + bool(hits(cases["pins.sh"], rules, Config(), "pins.sh")), + "pin flagged without allow", + ) + rc = cmd_scrub(repo, cfg, rules, [], dry_run=False) + expect(rc == 0, "scrub exits 0") + for name in cases: + text = (repo / name).read_text(encoding="utf-8") + expect(not hits(text, rules, cfg, name), f"{name} clean after scrub") + out = (repo / "a.md").read_text(encoding="utf-8") + expect(out == "built in ~/Dev/proj by user\n", f"a.md exact: {out!r}") + out = (repo / "c.txt").read_text(encoding="utf-8") + expect(out == "Linux host 9.9 PREEMPT_DYNAMIC\n", f"c.txt exact: {out!r}") + out = (repo / "b.json").read_text(encoding="utf-8") + expect( + '"redacted"' in out and "Intel 4-core/8-thread laptop CPU" in out, "b.json" + ) + out = (repo / "pins.sh").read_text(encoding="utf-8") + expect(out == cases["pins.sh"], "allowed pin untouched by scrub") + gz = (repo / "g.log.gz").read_bytes() + expect( + gz[4:8] == b"\0\0\0\0" and gzip.decompress(gz) == b"~/log\n", + "gz rewritten -n", + ) + expect( + cmd_scrub(repo, cfg, rules, [], dry_run=True) == 0, "scrub is idempotent" + ) + for f in failures: + print(f"FAIL {f}") + print( + f"host_ids self-test: {'FAILED' if failures else 'passed'} ({len(failures)} failure(s))" + ) + return 1 if failures else 0 + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) + sub = ap.add_subparsers(dest="cmd", required=True) + p = sub.add_parser("check", help="tracked files; exit 1 on a hit") + p.add_argument("--repo") + p = sub.add_parser("scrub", help="rewrite files in place") + p.add_argument("--repo") + p.add_argument("--dry-run", action="store_true") + p.add_argument("paths", nargs="*") + sub.add_parser("filter", help="scrub stdin to stdout") + p = sub.add_parser("history", help="scan all reachable blobs and messages") + p.add_argument("--repo") + p.add_argument("--emit-rules", metavar="FILE") + p = sub.add_parser("local", help="inventory of local copies of old history") + p.add_argument("--repo") + sub.add_parser("self-test", help="planted cases in a throwaway repo") + args = ap.parse_args() + if args.cmd == "self-test": + return self_test() + if args.cmd == "filter": + rt = gather(None) + return cmd_filter(all_rules(rt)) + repo, cfg, rules = setup(getattr(args, "repo", None)) + if args.cmd == "check": + return cmd_check(repo, cfg, rules) + if args.cmd == "scrub": + return cmd_scrub(repo, cfg, rules, args.paths, args.dry_run) + if args.cmd == "history": + return cmd_history(repo, cfg, rules, args.emit_rules) + return cmd_local(repo) + + +if __name__ == "__main__": + sys.exit(main()) From c3d5c3d8e429c59a826875bd968db9e5f250414d Mon Sep 17 00:00:00 2001 From: PatternCatalyst Date: Fri, 23 Oct 2026 10:34:29 -0400 Subject: [PATCH 4/6] fix: use allow_match for guest values; scrub archless host kernels Replaces the per-path allows with allow_match regexes for the guest's public values and refreshes scripts/host_ids.py. --- .host-scrub.toml | 39 ++++++----------------------- scripts/host_ids.py | 60 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 65 insertions(+), 34 deletions(-) diff --git a/.host-scrub.toml b/.host-scrub.toml index e80b296..fb17ba5 100644 --- a/.host-scrub.toml +++ b/.host-scrub.toml @@ -1,34 +1,11 @@ -# Host-scrub configuration. Holds paths and categories only, never values. +# Host-scrub configuration. Holds public values and patterns only, never a host value. # See CLAUDE.md "Publishing rule". # The disposable lab guests (systems-target, systems-peer) are Fedora VMs whose own -# values are book content: the guest account's home directory and the guest kernel -# build the book pins. Neither is the development machine's. -[allow] -home-path = [ - "_docs/02-lab-setup.md", - "_docs/14-identity-and-privilege.md", - "_docs/23-udp-and-peer-discovery.md", - "_docs/32-namespaces-and-cgroups.md", - "_docs/35-virtualization-and-kvm.md", - "examples/14-identity-and-privilege/README.md", - "examples/14-identity-and-privilege/verify.lua", - "examples/37-use-method-60s-analysis/verify.lua", - "examples/40-low-latency-fastpath/verify.lua", - "_plans/r09-batch1-golden-capture.md", - "_plans/r09-batch1-stub-completion.md", - "_plans/r26-full-matrix-gate.md", - "scripts/lab/deploy-to-vm.sh", -] -kernel-build = [ - "_docs/02-lab-setup.md", - "_docs/30-ebpf-observation-toolkit.md", - "_docs/32-namespaces-and-cgroups.md", - "_docs/33-seccomp-and-landlock.md", - "_docs/35-virtualization-and-kvm.md", - "_docs/45-linux-analysis-suites.md", - "_plans/r09-batch1-golden-capture.md", -] -kernel-version = [ - "_plans/r09-batch1-golden-capture.md", -] +# values are book content: the cloud image's default account home and the pinned +# guest kernel. Each regex matches that public value wherever it appears, so a host +# value in the same file is still found. +[allow_match] +home-path = ['^/home/fedora$'] +kernel-build = ['6[.]19[.]10-300[.]fc44'] +kernel-version = ['^#1 SMP PREEMPT_DYNAMIC Wed Mar 25 18:23:49 UTC 2026$'] diff --git a/scripts/host_ids.py b/scripts/host_ids.py index 6e27abf..8c4e4b0 100755 --- a/scripts/host_ids.py +++ b/scripts/host_ids.py @@ -27,6 +27,9 @@ cpu_class = "Intel 8-core/16-thread laptop CPU" # override the derived class [allow] # path globs exempt from a category kernel-build = ["scripts/lab/*.sh"] + [allow_match] # regexes for public values, any file + kernel-build = ['^7[.]1[.]3-201[.]fc44'] # e.g. the lab guest's pinned kernel + home-path = ['^/home/fedora$'] # the guest's cloud-init account Extra literals that identify the machine but are not discoverable (an old hostname, a former account) go in an untracked file, one per line, `value` or @@ -216,6 +219,14 @@ def _preempt(version: str) -> str: r"\.(?:x86_64|aarch64)(?!\.rpm)\b" r"|(? list[Rule]: @@ -266,6 +277,7 @@ def cls(vendor: str) -> str: r'\1"redacted"', ), Rule("kernel-build", re.compile(KERNEL_BUILD), r"\1\2"), + Rule("kernel-build", re.compile(KERNEL_BUILD_NOARCH), r"\1\2"), Rule( "kernel-version", re.compile( @@ -333,6 +345,7 @@ def all_rules(rt: Runtime) -> list[Rule]: class Config: skip: list[str] = field(default_factory=list) allow: dict[str, list[str]] = field(default_factory=dict) + allow_match: dict[str, list[re.Pattern[str]]] = field(default_factory=dict) cpu_class: str = "" def skipped(self, rel: str) -> bool: @@ -341,6 +354,10 @@ def skipped(self, rel: str) -> bool: def allowed(self, category: str, rel: str) -> bool: return any(fnmatch.fnmatch(rel, g) for g in self.allow.get(category, [])) + def value_allowed(self, category: str, value: str) -> bool: + """True when a matched value is a known public string, such as a guest's pin.""" + return any(p.search(value) for p in self.allow_match.get(category, [])) + def load_config(repo: Path) -> Config: path = repo / CONFIG_NAME @@ -354,6 +371,10 @@ def load_config(repo: Path) -> Config: return Config( skip=list(data.get("skip", [])), allow={k: list(v) for k, v in data.get("allow", {}).items()}, + allow_match={ + k: [re.compile(x) for x in v] + for k, v in data.get("allow_match", {}).items() + }, cpu_class=str(data.get("cpu_class", "")), ) @@ -395,8 +416,15 @@ def gzip_n(data: bytes) -> bytes: def scrub_text(text: str, rules: list[Rule], cfg: Config, rel: str) -> str: for r in rules: - if not cfg.allowed(r.category, rel): - text = r.pattern.sub(r.replacement, text) + if cfg.allowed(r.category, rel): + continue + + def sub(m: re.Match[str], r: Rule = r) -> str: + if cfg.value_allowed(r.category, m.group(0)): + return m.group(0) + return m.expand(r.replacement) + + text = r.pattern.sub(sub, text) return text @@ -408,6 +436,8 @@ def hits(text: str, rules: list[Rule], cfg: Config, rel: str) -> list[tuple[int, for m in r.pattern.finditer(text): if r.category == "home-path" and m.group(0) in ("~", ""): continue + if cfg.value_allowed(r.category, m.group(0)): + continue found.append((text.count("\n", 0, m.start()) + 1, r.category)) return sorted(set(found)) @@ -535,6 +565,8 @@ def scan(text: str, rel: str) -> None: v = m.group(0) if r.category == "home-path" and v in ("~", ""): continue + if cfg.value_allowed(r.category, v): + continue found.setdefault(r.category, set()).add(rel) values.setdefault(v, _replacement_for(r, v)) @@ -640,6 +672,9 @@ def self_test() -> int: "root=UUID=11111111-2222-3333-4444-555555555555\n", "e.txt": "other machine: /home/someone/x, an AMD Ryzen 7 5800X, 6.8.0-45-generic\n", "pins.sh": "SRPM=kernel-7.2.11-200.fc44.src.rpm\nGUEST=7.2.11-200.fc44.x86_64\n", + "noarch.md": "the host ran kernel 6.9.4-200.fc40 that day\n", + "mixed.md": "guest 7.3.1-100.fc45.x86_64, host 6.9.4-200.fc40.x86_64, /home/fedora/app\n", + "pkgs.md": "pcp 7.1.5-3.fc44 and kernel-devel-7.1.3-201.fc44 are pinned\n", "clean.md": "a ~/x path, /y, /home/user/z, kernel 7.2 PREEMPT_DYNAMIC\n", } failures = [] @@ -652,7 +687,10 @@ def self_test() -> int: gzip.compress(b"/home/planted-acct/log\n", mtime=123) ) (repo / CONFIG_NAME).write_text( - '[allow]\nkernel-build = ["pins.sh"]\n', encoding="utf-8" + '[allow]\nkernel-build = ["pins.sh"]\n' + "[allow_match]\nkernel-build = ['^7[.]3[.]1-100[.]fc45']\n" + "home-path = ['^/home/fedora$']\n", + encoding="utf-8", ) subprocess.run(["git", "-C", str(repo), "add", "-A"], check=True) fake.repo_path = str(repo) @@ -666,6 +704,17 @@ def expect(cond: bool, what: str) -> None: for name in ("a.md", "b.json", "c.txt", "d.txt", "e.txt"): expect(bool(hits(cases[name], rules, cfg, name)), f"check flags {name}") expect(not hits(cases["clean.md"], rules, cfg, "clean.md"), "clean.md passes") + expect( + bool(hits(cases["noarch.md"], rules, cfg, "noarch.md")), "archless flagged" + ) + expect( + not hits(cases["pkgs.md"], rules, cfg, "pkgs.md"), "package versions pass" + ) + expect( + [c for _, c in hits(cases["mixed.md"], rules, cfg, "mixed.md")] + == ["kernel-build"], + "mixed.md: only the host kernel is flagged", + ) expect( not hits(cases["pins.sh"], rules, cfg, "pins.sh"), "allowed kernel pin passes", @@ -687,6 +736,11 @@ def expect(cond: bool, what: str) -> None: expect( '"redacted"' in out and "Intel 4-core/8-thread laptop CPU" in out, "b.json" ) + out = (repo / "mixed.md").read_text(encoding="utf-8") + want = "guest 7.3.1-100.fc45.x86_64, host 6.9, /home/fedora/app\n" + expect(out == want, f"mixed.md exact: {out!r}") + out = (repo / "noarch.md").read_text(encoding="utf-8") + expect(out == "the host ran kernel 6.9 that day\n", f"noarch.md exact: {out!r}") out = (repo / "pins.sh").read_text(encoding="utf-8") expect(out == cases["pins.sh"], "allowed pin untouched by scrub") gz = (repo / "g.log.gz").read_bytes() From 3fe6aa45af3de07f9566b5bf18ee3dbb0714eda6 Mon Sep 17 00:00:00 2001 From: PatternCatalyst Date: Fri, 23 Oct 2026 10:36:27 -0400 Subject: [PATCH 5/6] fix: host_ids.py catches quoted and line-start kernel builds; allow the guest image's kernel-devel build --- .host-scrub.toml | 5 +++-- scripts/host_ids.py | 20 ++++++++++++++++---- 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/.host-scrub.toml b/.host-scrub.toml index fb17ba5..2d71172 100644 --- a/.host-scrub.toml +++ b/.host-scrub.toml @@ -4,8 +4,9 @@ # The disposable lab guests (systems-target, systems-peer) are Fedora VMs whose own # values are book content: the cloud image's default account home and the pinned # guest kernel. Each regex matches that public value wherever it appears, so a host -# value in the same file is still found. +# value in the same file is still found. The second kernel-build value is the Fedora +# kernel-devel package build shipped in the guest image (_docs/30 discusses the mismatch). [allow_match] home-path = ['^/home/fedora$'] -kernel-build = ['6[.]19[.]10-300[.]fc44'] +kernel-build = ['6[.]19[.]10-300[.]fc44', '^7[.]1[.]3-201[.]fc44$'] kernel-version = ['^#1 SMP PREEMPT_DYNAMIC Wed Mar 25 18:23:49 UTC 2026$'] diff --git a/scripts/host_ids.py b/scripts/host_ids.py index 8c4e4b0..cd4e0e6 100755 --- a/scripts/host_ids.py +++ b/scripts/host_ids.py @@ -221,11 +221,14 @@ def _preempt(version: str) -> str: ) # The same release written without its architecture ("kernel 7.1.3-201.fc44"). A bare # name-version-release would also match every Fedora package version, so this form is -# matched only after a word that says it is a kernel. +# matched after a word that says it is a kernel (allowing quotes, markup or a line break +# in between), or by the shape of a Fedora kernel release: a three-digit release number +# in the 100s to 300s, which ordinary packages do not use. KERNEL_BUILD_NOARCH = ( - r"\b((?:[Kk]ernel|Linux|vmlinuz-|uname -r\W{0,4})\s*)" + r"\b((?:[Kk]ernel|Linux|vmlinuz-|uname -r)\W{0,8}?(?:)?)" r"(\d+\.\d+)\.\d+-\d+(?:\.\w+)*?\.(?:fc|el)\d+(?:_\d+)?\b" r"(?!\.(?:x86_64|aarch64|src|rpm))" + r"|(? str: r'\1"redacted"', ), Rule("kernel-build", re.compile(KERNEL_BUILD), r"\1\2"), - Rule("kernel-build", re.compile(KERNEL_BUILD_NOARCH), r"\1\2"), + Rule("kernel-build", re.compile(KERNEL_BUILD_NOARCH), r"\1\2\3\4"), Rule( "kernel-version", re.compile( @@ -438,7 +441,7 @@ def hits(text: str, rules: list[Rule], cfg: Config, rel: str) -> list[tuple[int, continue if cfg.value_allowed(r.category, m.group(0)): continue - found.append((text.count("\n", 0, m.start()) + 1, r.category)) + found.append((text.count("\n", 0, m.end() - 1) + 1, r.category)) return sorted(set(found)) @@ -673,6 +676,8 @@ def self_test() -> int: "e.txt": "other machine: /home/someone/x, an AMD Ryzen 7 5800X, 6.8.0-45-generic\n", "pins.sh": "SRPM=kernel-7.2.11-200.fc44.src.rpm\nGUEST=7.2.11-200.fc44.x86_64\n", "noarch.md": "the host ran kernel 6.9.4-200.fc40 that day\n", + "noarch2.md": "kernel `6.9.4-200.fc40`, kernel\n6.8.1-100.fc40\n" + "| 6.7.2-300.fc39 | host |\n", "mixed.md": "guest 7.3.1-100.fc45.x86_64, host 6.9.4-200.fc40.x86_64, /home/fedora/app\n", "pkgs.md": "pcp 7.1.5-3.fc44 and kernel-devel-7.1.3-201.fc44 are pinned\n", "clean.md": "a ~/x path, /y, /home/user/z, kernel 7.2 PREEMPT_DYNAMIC\n", @@ -710,6 +715,10 @@ def expect(cond: bool, what: str) -> None: expect( not hits(cases["pkgs.md"], rules, cfg, "pkgs.md"), "package versions pass" ) + expect( + len(hits(cases["noarch2.md"], rules, cfg, "noarch2.md")) == 3, + "quoted, next-line and table-cell kernels flagged", + ) expect( [c for _, c in hits(cases["mixed.md"], rules, cfg, "mixed.md")] == ["kernel-build"], @@ -741,6 +750,9 @@ def expect(cond: bool, what: str) -> None: expect(out == want, f"mixed.md exact: {out!r}") out = (repo / "noarch.md").read_text(encoding="utf-8") expect(out == "the host ran kernel 6.9 that day\n", f"noarch.md exact: {out!r}") + out = (repo / "noarch2.md").read_text(encoding="utf-8") + want = "kernel `6.9`, kernel\n6.8\n| 6.7 | host |\n" + expect(out == want, f"noarch2.md exact: {out!r}") out = (repo / "pins.sh").read_text(encoding="utf-8") expect(out == cases["pins.sh"], "allowed pin untouched by scrub") gz = (repo / "g.log.gz").read_bytes() From 5fe4384abbe3557f8b48d4a6863ff8a05c905c91 Mon Sep 17 00:00:00 2001 From: PatternCatalyst Date: Fri, 23 Oct 2026 10:47:28 -0400 Subject: [PATCH 6/6] fix: validation fixes (fake fixture values, CLAUDE.md wording, diagram 34, scrub on exit) --- CLAUDE.md | 11 ++++---- _docs/39-benchmarking-without-lies.md | 2 +- .../diagrams/34-ns-debugging-map.excalidraw | 4 +-- assets/diagrams/34-ns-debugging-map.svg | 2 +- scripts/host_ids.py | 28 ++++++++++++++----- scripts/test-all-examples.py | 11 ++++++-- 6 files changed, 39 insertions(+), 19 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d3cc32d..1a7b8e7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -101,12 +101,13 @@ or anything that helps locate or attack it later: properties (SMT, cache sizes, frequency driver), never the part. - No host kernel build number or build date: give `major.minor` (for example `7.1`) and the preempt model. The lab guests' pinned kernel (`systems-target`) is - book content and is allowed by path in `.host-scrub.toml`. -- No `/etc/machine-id`, DMI serial or UUID, MAC or IP address, `root=UUID=` or - BOOT_IMAGE. + book content and is allowed by value (`allow_match`) in `.host-scrub.toml`. +- No `/etc/machine-id`, DMI serial or UUID, host MAC or IP address (the lab guests' private libvirt + addresses are book content), `root=UUID=` or BOOT_IMAGE. - Generated output is scrubbed before it is committed: `python3 scripts/host_ids.py scrub

` on a results directory, `scripts/host_ids.py filter` on a captured transcript. `scripts/test-all-examples.py` scrubs `build-logs/` after each run. - `python3 scripts/host_ids.py check` runs in CI (`host-ids` job) and fails the build - on a hit. Allow a legitimate hit by path and category in `.host-scrub.toml`; the - file holds no values. + on a hit. Allow a legitimate hit by path and category (or by public value with + `allow_match`) in `.host-scrub.toml`; the file holds no host values (only public + guest values). diff --git a/_docs/39-benchmarking-without-lies.md b/_docs/39-benchmarking-without-lies.md index 6a5cd67..96c5b1f 100644 --- a/_docs/39-benchmarking-without-lies.md +++ b/_docs/39-benchmarking-without-lies.md @@ -515,7 +515,7 @@ corrected p99 small in the first place. ---

verified — on the Fedora 44 -reference host (kernel 7.1, 11th-gen Intel 8-core/16-thread laptop CPU, 16 CPUs, +reference host (kernel 7.1, Intel 8-core/16-thread laptop CPU, 16 CPUs, intel_pstate/powersave governor, turbo active) this session: python3 scripts/test-all-examples.py --only 39-benchmarking-without-lies printed PASS PASS PASS (3 diff --git a/assets/diagrams/34-ns-debugging-map.excalidraw b/assets/diagrams/34-ns-debugging-map.excalidraw index c3469e5..7314c43 100644 --- a/assets/diagrams/34-ns-debugging-map.excalidraw +++ b/assets/diagrams/34-ns-debugging-map.excalidraw @@ -56,13 +56,13 @@ "updated": 1, "link": null, "locked": false, - "text": "host (rootless user user, uid 1000)", + "text": "host (rootless account `user`, uid 1000)", "fontSize": 12, "fontFamily": 1, "textAlign": "left", "verticalAlign": "top", "containerId": null, - "originalText": "host (rootless user user, uid 1000)", + "originalText": "host (rootless account `user`, uid 1000)", "lineHeight": 1.25, "baseline": 12 }, diff --git a/assets/diagrams/34-ns-debugging-map.svg b/assets/diagrams/34-ns-debugging-map.svg index 2034641..69ed163 100644 --- a/assets/diagrams/34-ns-debugging-map.svg +++ b/assets/diagrams/34-ns-debugging-map.svg @@ -1,7 +1,7 @@ -host (rootless user user, uid 1000) +host (rootless account `user`, uid 1000) podman's user namespace (uid 0 in container == uid 1000 on host) diff --git a/scripts/host_ids.py b/scripts/host_ids.py index cd4e0e6..1e5fcea 100755 --- a/scripts/host_ids.py +++ b/scripts/host_ids.py @@ -28,7 +28,7 @@ [allow] # path globs exempt from a category kernel-build = ["scripts/lab/*.sh"] [allow_match] # regexes for public values, any file - kernel-build = ['^7[.]1[.]3-201[.]fc44'] # e.g. the lab guest's pinned kernel + kernel-build = ['^8[.]4[.]2-200[.]fc98'] # e.g. the lab guest's pinned kernel home-path = ['^/home/fedora$'] # the guest's cloud-init account Extra literals that identify the machine but are not discoverable (an old hostname, @@ -219,7 +219,7 @@ def _preempt(version: str) -> str: r"\.(?:x86_64|aarch64)(?!\.rpm)\b" r"|(? str: ), Rule( "cpu-model", - re.compile(rf"(? list[tuple[int, def is_self(repo: Path, rel: str) -> bool: + """The tool itself, or the config that lists allowed patterns.""" + if rel == CONFIG_NAME: + return True try: return (repo / rel).resolve() == SELF except OSError: @@ -503,7 +508,7 @@ def cmd_scrub( rel = str(f.resolve().relative_to(repo)) except ValueError: rel = str(f) - if cfg.skipped(rel) or f.resolve() == SELF: + if cfg.skipped(rel) or rel == CONFIG_NAME or f.resolve() == SELF: continue try: raw = f.read_bytes() @@ -574,7 +579,7 @@ def scan(text: str, rel: str) -> None: values.setdefault(v, _replacement_for(r, v)) for sha, rel in paths.items(): - if Path(rel).name == SELF.name: + if Path(rel).name in (SELF.name, CONFIG_NAME): continue batch.stdin.write(f"{sha}\n".encode()) batch.stdin.flush() @@ -674,12 +679,13 @@ def self_test() -> int: "d.txt": "id 0123456789abcdef0123456789abcdef mac 02:00:5E:10:20:30 " "root=UUID=11111111-2222-3333-4444-555555555555\n", "e.txt": "other machine: /home/someone/x, an AMD Ryzen 7 5800X, 6.8.0-45-generic\n", - "pins.sh": "SRPM=kernel-7.2.11-200.fc44.src.rpm\nGUEST=7.2.11-200.fc44.x86_64\n", + "f.md": "an 11th-gen Intel i7-99999X laptop, an Intel Core i5-99999U\n", + "pins.sh": "SRPM=kernel-8.4.2-200.fc98.src.rpm\nGUEST=8.4.2-200.fc98.x86_64\n", "noarch.md": "the host ran kernel 6.9.4-200.fc40 that day\n", "noarch2.md": "kernel `6.9.4-200.fc40`, kernel\n6.8.1-100.fc40\n" "| 6.7.2-300.fc39 | host |\n", "mixed.md": "guest 7.3.1-100.fc45.x86_64, host 6.9.4-200.fc40.x86_64, /home/fedora/app\n", - "pkgs.md": "pcp 7.1.5-3.fc44 and kernel-devel-7.1.3-201.fc44 are pinned\n", + "pkgs.md": "pcp 8.1.5-3.fc98 and kernel-devel-8.4.2-200.fc98 are pinned\n", "clean.md": "a ~/x path, /y, /home/user/z, kernel 7.2 PREEMPT_DYNAMIC\n", } failures = [] @@ -750,6 +756,9 @@ def expect(cond: bool, what: str) -> None: expect(out == want, f"mixed.md exact: {out!r}") out = (repo / "noarch.md").read_text(encoding="utf-8") expect(out == "the host ran kernel 6.9 that day\n", f"noarch.md exact: {out!r}") + out = (repo / "f.md").read_text(encoding="utf-8") + cls = "Intel 4-core/8-thread laptop CPU" + expect(out == f"an {cls} laptop, an {cls}\n", f"f.md exact: {out!r}") out = (repo / "noarch2.md").read_text(encoding="utf-8") want = "kernel `6.9`, kernel\n6.8\n| 6.7 | host |\n" expect(out == want, f"noarch2.md exact: {out!r}") @@ -763,6 +772,11 @@ def expect(cond: bool, what: str) -> None: expect( cmd_scrub(repo, cfg, rules, [], dry_run=True) == 0, "scrub is idempotent" ) + # The tool must never carry this machine's own values, not even in a test fixture. + own = SELF.read_text(encoding="utf-8") + for r in runtime_rules(gather(None)): + if r.pattern.search(own): + failures.append(f"host_ids.py itself holds this machine's {r.category}") for f in failures: print(f"FAIL {f}") print( diff --git a/scripts/test-all-examples.py b/scripts/test-all-examples.py index ad4f21b..cde43f8 100755 --- a/scripts/test-all-examples.py +++ b/scripts/test-all-examples.py @@ -378,7 +378,7 @@ def scrub_logs() -> None: stdout=subprocess.DEVNULL, check=False) -def main(argv: list[str]) -> int: +def run(argv: list[str]) -> int: args = parse_args(argv) try: examples = load_manifest() @@ -452,13 +452,18 @@ def main(argv: list[str]) -> int: print(f"\n{passed} passed, {failed} failed, {skipped} skipped" f" (logs in {LOG_DIR.relative_to(REPO_ROOT)}/)") - scrub_logs() - if args.junit: write_junit(args.junit, selected, results) print(f"junit report: {args.junit}") return 1 if failed else 0 +def main(argv: list[str]) -> int: + try: + return run(argv) + finally: + scrub_logs() # also on an exception or Ctrl-C + + if __name__ == "__main__": sys.exit(main(sys.argv[1:]))