api: fail a fact read that does not fit under the sysroot

kasld_resolve composes "<KASLD_SYSROOT><path>" into a KASLD_PATH_MAX
buffer and returned the bare path where the two did not fit, so a long
enough sysroot sent fact reads to the machine running the analysis while
the output still presented them as a captured tree. A 4091-byte sysroot
naming nothing read 124 facts; a short one naming nothing read 3.

The comment argued that a miss against the live tree beat a truncated
path, which weighs two options and omits the third. Nothing was
salvageable in any case: the buffer is KASLD_PATH_MAX at all five call
sites, so a prefixed path that does not fit is already longer than one
the kernel will open, and the fallback could only ever substitute a live
read for a read that had to fail.

Return NULL and fail with ENAMETOOLONG, which is what happened. The five
wrappers check it; kasld_read_file_line already propagates a null FILE,
and nothing outside the header calls kasld_resolve, so those five are all
of them. Short fact paths still resolve under an over-long root while
long ones fail, which is a decline and widens the window rather than
narrowing it.

check-sysroot-containment compares two sysroots that both name nothing,
one sized past the buffer, and requires them to read the same facts. A
live run supplies the control: a host exposing no more than the empty
sysroot does leaves nothing to detect, so the guard skips rather than
passing on an absence.

Author: bcoles

Makefile

@@ -821,6 +821,7 @@ lint :
 	    $(TEST_DIR)/check-render-parity \
 	    $(TEST_DIR)/check-render-color \
 	    $(TEST_DIR)/check-wire-text \
+	    $(TEST_DIR)/check-sysroot-containment \
 	    $(TEST_DIR)/hardening-fixtures \
 	    $(TEST_DIR)/cli-flags
 

SECURITY.md

@@ -14,13 +14,21 @@ with a pointer to where it belongs rather than an advisory.
 
 KASLD runs each component as a separate program and parses its output in the
 orchestrator, which is usually the more privileged process in a run. That
-asymmetry is where the interesting surface is:
+asymmetry, and the untrusted input a run consumes, are where the interesting
+surface is:
 
 - **Orchestrator parsing.** `src/orchestrator.c` consumes component stdout, ELF
   section payloads and `dmesg` — input an unprivileged process can influence —
   inside the privileged process. Memory-safety, over-read or unbounded-loop
   bugs there are a genuine exposure surface; `tests/fuzz` covers these parsers,
   so a crashing input is directly actionable.
+- **Captured trees.** `KASLD_SYSROOT` redirects every kernel-fact path a run
+  reads to a copy of another system's `/proc`, `/sys` and `/boot`, and
+  `extra/collect` produces such trees to be analysed elsewhere. A tree is
+  untrusted input — it comes from the machine under investigation, and its
+  directory names and extraction path are as much a part of it as its file
+  contents. Analysing one must not execute code from it, read outside it, or
+  fall back to the analysing host's own state.
 - **The `extra/` helpers.** Several are documented as being run under `sudo`,
   so anything in one of them that mishandles untrusted input does so as root.
 - **Unintended execution or privilege change.** `KASLD_COMPONENT_DIR` and

docs/testing.md

@@ -209,6 +209,7 @@ stays plain, and setting `KASLD_COLOR` non-empty or empty forces either.
 | `check-render-parity` | the text readout, the markdown report and JSON name the same set of resolved quantities for a given run † |
 | `check-render-color` | coloured output is byte-identical to plain output once the escape sequences are removed, and markdown, JSON and oneline carry no escapes at all † |
 | `check-wire-text` | a component cannot put an escape sequence on the terminal: a record whose `name`, or a disposition whose `gate` or `msg`, leaves printable ASCII is rejected, and the verbose echo of component output strips control bytes † |
+| `check-sysroot-containment` | a `KASLD_SYSROOT` too long to build a fact path with fails the read instead of falling back to the analysing host's own `/proc` and `/sys` † |
 | `check-guard-docs` | this table lists exactly the guards `make lint` runs — the same parity check `check-manpages` applies to flags, applied to the guard list itself |
 | `check-matrix-summary` | the summary table in `docs/reproducibility.md` restates the full per-scenario matrix it precedes: same cells, same KASLR state, same `default` and `perf-open` results in both directions |
 | `check-readout-docs` | documented sample output uses the renderer's current vocabulary and fits 100 columns (live output is measured separately by `check-render-width`) † |
@@ -510,6 +511,35 @@ differential against a colourless run passes while proving nothing. Determinism
 comes from an empty sysroot plus stub components, which also supply the pinned
 base the coloured branches need.
 
+**`check-wire-text`** — A component's free text is data, and the fields
+carrying it — a result's `name`, a disposition's `gate` and `msg` — are
+rendered into the report an operator forwards. An erase-line sequence among
+them redraws a line already printed, so a finding can be made to read as its
+opposite by the report meant to expose it. `check-render-color` proves KASLD's
+own escapes strip back to the plain rendering, which says nothing about escapes
+arriving in data.
+
+The admissible set stops at 0x7E rather than merely above 0x1F, because
+0x80..0x9F is the C1 control range and a terminal in an 8-bit locale acts on it
+with no ESC byte involved. Both halves are exercised. The guard also reads its
+own output with `grep -a`: without it a high byte makes grep report a binary
+match instead of lines, leaving the check searching nothing and passing against
+the very build it targets.
+
+**`check-sysroot-containment`** — `kasld_resolve()` composes
+`<KASLD_SYSROOT><path>` into a `KASLD_PATH_MAX` buffer, and returning the bare
+path where the two do not fit sends the read to the analysing machine's own
+`/proc` and `/sys` while the output still presents a captured tree. It is not a
+truncation trade-off: a prefixed path overflowing 4096 bytes is already longer
+than one the kernel will open, so the fallback never salvaged a read that would
+otherwise have worked. Before the fix, a 4091-byte sysroot naming nothing read
+124 facts where a short one naming nothing read 3.
+
+Both roots name nothing, so a difference between them can only be a read that
+escaped. A live run supplies the control: a host exposing no more facts than
+the empty sysroot does leaves nothing to detect, and the guard skips rather
+than passing on an absence.
+
 **`check-doc-structure`** — Three failures markdown accepts silently and a
 reader meets as a broken page: an unclosed fence swallows the rest of the
 document, a heading added without its TOC line is unreachable from the contents

src/include/kasld/sysroot.h

@@ -27,6 +27,7 @@
 #define KASLD_SYSROOT_H
 
 #include <dirent.h>
+#include <errno.h>
 #include <fcntl.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -90,8 +91,13 @@ __attribute__((unused)) static void kasld_hermetic_record(const char *abs) {
 
 /* Resolve an absolute fact path against the sysroot. With no sysroot set (or
  * a non-absolute path), returns `abs` unchanged. Otherwise writes
- * "<root><abs>" into buf and returns it; if that would not fit, falls back to
- * `abs` (a miss against the live tree is safer than a truncated path). */
+ * "<root><abs>" into buf and returns it.
+ *
+ * Returns NULL if the prefixed path does not fit. buf is KASLD_PATH_MAX at
+ * every call site, so a path that does not fit is already longer than one the
+ * kernel will open: there is no reading it either way. Callers must check, and
+ * fail the read with ENAMETOOLONG. Returning `abs` instead would read the
+ * analysing machine's own file while a sysroot named another tree. */
 __attribute__((unused)) static const char *
 kasld_resolve(const char *abs, char *buf, size_t bufsz) {
   const char *root = kasld_sysroot();
@@ -105,7 +111,7 @@ kasld_resolve(const char *abs, char *buf, size_t bufsz) {
   rl = strlen(root);
   al = strlen(abs);
   if (rl + al + 1 > bufsz)
-    return abs;
+    return NULL;
   memcpy(buf, root, rl);
   memcpy(buf + rl, abs, al + 1);
   return buf;
@@ -114,33 +120,58 @@ kasld_resolve(const char *abs, char *buf, size_t bufsz) {
 __attribute__((unused)) static FILE *kasld_fopen(const char *path,
                                                  const char *mode) {
   char buf[KASLD_PATH_MAX];
-  return fopen(kasld_resolve(path, buf, sizeof(buf)), mode);
+  const char *p = kasld_resolve(path, buf, sizeof(buf));
+  if (!p) {
+    errno = ENAMETOOLONG;
+    return NULL;
+  }
+  return fopen(p, mode);
 }
 
 /* Read-only open() only — kasld never creates files, so no mode arg (and
  * thus no variadic wrapper) is needed. */
 __attribute__((unused)) static int kasld_open(const char *path, int flags) {
   char buf[KASLD_PATH_MAX];
-  return open(kasld_resolve(path, buf, sizeof(buf)), flags);
+  const char *p = kasld_resolve(path, buf, sizeof(buf));
+  if (!p) {
+    errno = ENAMETOOLONG;
+    return -1;
+  }
+  return open(p, flags);
 }
 
 __attribute__((unused)) static int kasld_stat(const char *path,
                                               struct stat *st) {
   char buf[KASLD_PATH_MAX];
-  return stat(kasld_resolve(path, buf, sizeof(buf)), st);
+  const char *p = kasld_resolve(path, buf, sizeof(buf));
+  if (!p) {
+    errno = ENAMETOOLONG;
+    return -1;
+  }
+  return stat(p, st);
 }
 
 __attribute__((unused)) static int kasld_access(const char *path, int mode) {
   char buf[KASLD_PATH_MAX];
-  return access(kasld_resolve(path, buf, sizeof(buf)), mode);
+  const char *p = kasld_resolve(path, buf, sizeof(buf));
+  if (!p) {
+    errno = ENAMETOOLONG;
+    return -1;
+  }
+  return access(p, mode);
 }
 
 /* opendir() through the sysroot. Entry names are returned as-is (relative to
  * the dir), so callers rebuild child paths with the original (un-rewritten)
  * directory prefix and re-resolve via the other wrappers. */
 __attribute__((unused)) static DIR *kasld_opendir(const char *path) {
   char buf[KASLD_PATH_MAX];
-  return opendir(kasld_resolve(path, buf, sizeof(buf)));
+  const char *p = kasld_resolve(path, buf, sizeof(buf));
+  if (!p) {
+    errno = ENAMETOOLONG;
+    return NULL;
+  }
+  return opendir(p);
 }
 
 /* Read the first line of a fact file into buf: NUL-terminated, trailing

tests/check-sysroot-containment

@@ -0,0 +1,75 @@
+#!/bin/sh
+# This file is part of KASLD - https://github.com/bcoles/kasld
+#
+# check-sysroot-containment — a sysroot too long to build a path with must not
+# send the read back to the analysing machine.
+#
+# kasld_resolve() writes "<KASLD_SYSROOT><path>" into a KASLD_PATH_MAX buffer.
+# Where the two do not fit, returning the bare path reads the analysing host's
+# own /proc and /sys while the output presents the result as a captured tree.
+# Nothing is salvageable at that point — the prefixed path is already longer
+# than one the kernel will open — so the read fails with ENAMETOOLONG.
+#
+# Two sysroots that name nothing are compared: one short, one long enough to
+# overflow. Both must yield the same facts. Whether the run reads anything is
+# not assumed: a live run supplies the control, and a host exposing no more
+# than the empty sysroot does leaves nothing to detect, so the guard skips
+# rather than passing on an absence.
+# ---
+# <bcoles@gmail.com>
+
+set -u
+ROOT=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)
+
+if [ -t 1 ] || [ -n "${KASLD_COLOR:-}" ]; then
+  RED=$(printf '\033[31m'); GREEN=$(printf '\033[32m'); YELLOW=$(printf '\033[33m')
+  RESET=$(printf '\033[0m')
+else
+  RED=; GREEN=; YELLOW=; RESET=
+fi
+
+HOST_TRIPLE=$(cc -dumpmachine 2>/dev/null || echo unknown)
+BIN="$ROOT/build/$HOST_TRIPLE/kasld"
+if [ ! -x "$BIN" ]; then
+  printf '%ssysroot-containment guard: SKIP%s (no host binary at %s; run make first)\n' \
+    "$YELLOW" "$RESET" "$BIN"
+  exit 0
+fi
+
+# Neither root exists, so neither can supply a fact. The long one is sized past
+# KASLD_PATH_MAX (4096) once any fact path is appended; awk builds it because a
+# 4091-character literal is not something to keep in a source file.
+SHORT=/nonexistent-sysroot
+LONG=$(awk 'BEGIN { s = "/"; while (length(s) < 4091) s = s "aaaaaaaaaa";
+                    print substr(s, 1, 4091) }')
+
+# Facts a run actually read: --verbose echoes each component's wire lines, and
+# every fact a component emits is one of them.
+facts() { # $1 = KASLD_SYSROOT value, empty for a live run
+  if [ -z "$1" ]; then
+    "$BIN" -q -v 2>&1 | grep -c '^[VPSR] '
+  else
+    KASLD_SYSROOT="$1" "$BIN" -q -v 2>&1 | grep -c '^[VPSR] '
+  fi
+}
+
+live=$(facts '')
+short=$(facts "$SHORT")
+long=$(facts "$LONG")
+
+if [ "$((live - short))" -lt 10 ]; then
+  printf '%ssysroot-containment guard: SKIP%s (host exposes %d facts, empty sysroot %d; too few to detect a fallback)\n' \
+    "$YELLOW" "$RESET" "$live" "$short"
+  exit 0
+fi
+
+if [ "$long" -ne "$short" ]; then
+  printf '%ssysroot-containment guard: FAIL%s\n' "$RED" "$RESET"
+  printf '  an over-long KASLD_SYSROOT read %d facts; a short one reads %d\n' \
+    "$long" "$short"
+  printf '  (the live host reads %d) — a read escaped the sysroot\n' "$live"
+  exit 1
+fi
+
+printf '%ssysroot-containment guard: OK%s (over-long and short sysroots both read %d facts; live host %d)\n' \
+  "$GREEN" "$RESET" "$short" "$live"