orchestrator: reject wire text that would reach the terminal as an escape

A component chooses the text in three wire fields — a result's name, and a
disposition's gate and msg — and all three are rendered, gate and msg into
the hardening report an operator forwards. api.h said the parser at ingest
was the gatekeeper for them; no such gatekeeper existed, so a control byte
travelled from a component line to the terminal, where erase-line and
cursor movement redraw what was already printed and a finding can be made
to read as its opposite.

Validate at ingest and reject the record whole, joining the existing parse
discard rather than truncating or scrubbing: losing a record only widens a
window, and a name that survives with its bytes replaced would silently
change the identity merge_results groups on.

The admissible set is per field. name and gate are identifiers whose every
source is ASCII by its own specification — C identifiers, dtc-checked
device-tree node names, ACPI signatures, a PCI BDF — so printable ASCII
without the space, which the wire could never carry anyway. msg is quoted
prose and admits the space. Both refuse 0x80 and above: nothing that fills
these fields produces one, and the range cannot be split byte-wise, since
0x80..0x9F is both the C1 controls a terminal in an 8-bit locale acts on
and the UTF-8 continuation range.

--verbose echoes each component line before any parser sees it, so that
echo strips control bytes independently, showing them as `?` rather than
dropping them. Its range stops short of 0x80 on purpose: a diagnostic
quotes arbitrary kernel text where a high byte can be legitimate.

check-wire-text covers both paths with stub components, asserting that no
control byte reaches any mode, that a rejected record never renders, and
that a clean record still does — the last so a parser that rejected
everything could not pass. check-render-color proves KASLD's own escapes
strip to plain; it says nothing about escapes arriving in data.

Author: bcoles

Makefile

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

docs/testing.md

@@ -208,6 +208,7 @@ stays plain, and setting `KASLD_COLOR` non-empty or empty forces either.
 | `check-baseline` | the no-component baseline (`-s '*'`) renders in every output mode and exits with the no-results status, and a run that gathers evidence resolves a window *inside* it † |
 | `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-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`) † |

src/include/kasld/api.h

@@ -2075,8 +2075,16 @@ kasld_scalar_fact_from_wire(const char *s) {
  * Rejection happens for: CONF_UNKNOWN, invalid type, invalid region,
  * helper-specific preconditions (e.g. _sized overflow).
  * `name = NULL` or `""` means no specific instance (the wire form omits
- * the `:name` suffix). Names with leading/trailing whitespace or unsupported
- * chars are NOT validated here — the parser at ingest is the gatekeeper.
+ * the `:name` suffix).
+ *
+ * The character set is not checked here; the parser at ingest enforces it, and
+ * what it enforces is this: a name is made only of printable ASCII excluding
+ * space, 0x21..0x7E, and a record carrying anything else is rejected whole
+ * rather than truncated or scrubbed. The same rule governs a disposition's
+ * `gate`, while its quoted `msg` additionally admits the space. Every source
+ * these fields draw on is ASCII by its own specification, so a byte outside
+ * the set is an artefact; and since all three reach a terminal, a control byte
+ * among them is an escape sequence rather than a cosmetic flaw.
  * ========================================================================= */
 
 static inline int kasld__emit_check(enum kasld_addr_type t, enum kasld_region r,

src/orchestrator.c

@@ -780,6 +780,40 @@ struct parsed_tail {
   unsigned long lo, hi, sz, sample, base_align;
 };
 
+/* Is a free-text wire field made only of characters the protocol admits?
+ *
+ * `name`, `gate` and `msg` are the three fields a component fills with text of
+ * its own choosing, and all three reach the operator's terminal — `gate` and
+ * `msg` through the hardening report. A control byte among them is an escape
+ * sequence: cursor movement and erase-line can redraw a finding as its
+ * opposite in the very report meant to expose it.
+ *
+ * The admissible set is per field rather than global. `name` and `gate` are
+ * identifiers, and every source that fills them is ASCII by its own
+ * specification — kernel symbols are C identifiers, device-tree node names are
+ * checked against a fixed set by dtc, ACPI signatures and OEM ids are ASCII by
+ * the ACPI spec, a PCI BDF is hex with `:` and `.`. `msg` is quoted prose and
+ * so admits the space as well.
+ *
+ * Bytes at or above 0x80 are excluded with the controls. Nothing that fills
+ * these fields produces one, and admitting them would admit both the C1
+ * controls — which a terminal in an 8-bit locale acts on, no ESC byte needed —
+ * and confusable characters, neither of which a line-oriented ASCII protocol
+ * has a reason to carry. Note the range cannot be split byte-wise: 0x80..0x9F
+ * is also the UTF-8 continuation range, so banning C1 alone would corrupt any
+ * multi-byte sequence, and permitting it would leave the controls intact. */
+static int wire_text_ok(const char *s, int allow_space) {
+  for (; *s; s++) {
+    unsigned char c = (unsigned char)*s;
+    if (c >= 0x21 && c <= 0x7e)
+      continue;
+    if (allow_space && c == 0x20)
+      continue;
+    return 0;
+  }
+  return 1;
+}
+
 /* Split a "region[:name]" wire token into a resolved region + name_buf (sized
  * NAME_LEN). The split is on the FIRST `:` only — names may contain subsequent
  * colons (e.g. PCI BDF "0000:00:14.0"); region wire names are short
@@ -805,6 +839,10 @@ static enum kasld_region parse_region_field(const char *region_field,
       return REGION_UNKNOWN;
     memcpy(name_buf, name_src, nlen);
     name_buf[nlen] = '\0';
+    if (!wire_text_ok(name_buf, 0)) { /* control bytes reach the terminal */
+      name_buf[0] = '\0';
+      return REGION_UNKNOWN;
+    }
   } else {
     size_t rlen = strlen(region_field);
     if (rlen >= sizeof(region_str))
@@ -1618,6 +1656,8 @@ static int parse_disposition(const char *s, struct component_disposition *d) {
       tmp.gate[n] = '\0';
       if (n == 0)
         return 0; /* gate= naming nothing */
+      if (!wire_text_ok(tmp.gate, 0))
+        return 0; /* control bytes reach the hardening report */
     } else if (klen == 3 && memcmp(key, "msg", 3) == 0) {
       size_t n = 0;
       if (seen_msg)
@@ -1635,6 +1675,8 @@ static int parse_disposition(const char *s, struct component_disposition *d) {
         return 0; /* unterminated */
       s++;
       tmp.message[n] = '\0';
+      if (!wire_text_ok(tmp.message, 1))
+        return 0; /* quoted prose, but still no control bytes */
     } else {
       return 0; /* unknown key (spec: no forward-compat silence) */
     }
@@ -1661,8 +1703,27 @@ static int handle_component_line(struct component_log *clog,
   memcpy(line, content, len);
   line[len] = '\0';
 
-  if (verbose && plain_output())
-    printf("%s\n", line);
+  /* Echoed verbatim except for control bytes: DEL and everything below 0x20,
+   * including a stray CR that would redraw the line just printed. What a filter
+   * removes here is an escape sequence on a line that never reaches a parser
+   * and so is never rejected by one — the same terminal the readout protects,
+   * reached through the debugging channel instead.
+   *
+   * The range is narrower than the one wire_text_ok() applies to the wire's
+   * free-text fields, which also refuse everything at or above 0x80. That is
+   * deliberate rather than an omission: those fields are identifiers whose
+   * sources are ASCII by their own specifications, while a diagnostic line
+   * quotes arbitrary kernel text — a dmesg line, a /proc string — where a high
+   * byte can be legitimate UTF-8 that the operator asked to see. The residue is
+   * that a raw C1 byte survives here, which a terminal in an 8-bit locale would
+   * act on; mangling quoted kernel text on every run is the worse trade. */
+  if (verbose && plain_output()) {
+    for (const char *p = line; *p; p++) {
+      unsigned char c = (unsigned char)*p;
+      putchar((c < 0x20 || c == 0x7f) ? '?' : c);
+    }
+    putchar('\n');
+  }
 
   /* Capture line for verbose / JSON-with-output. Allocated on first use and
    * grown geometrically — no fixed cap, so noisy components do not silently

tests/check-wire-text

@@ -0,0 +1,166 @@
+#!/bin/sh
+# This file is part of KASLD - https://github.com/bcoles/kasld
+#
+# check-wire-text — a component cannot put an escape sequence on the operator's
+# terminal.
+#
+# Three wire fields carry text a component chooses: a result's `name`, and a
+# disposition's `gate` and `msg`. All three are rendered, `gate` and `msg` into
+# the hardening report, which is the output an operator forwards. A control byte
+# among them is not a cosmetic flaw: cursor-movement and erase-line sequences
+# redraw what was already printed, so a finding can be made to read as its
+# opposite by the report meant to expose it.
+#
+# Two paths carry such a byte and both are covered here. The parser rejects a
+# record whose free-text field leaves printable ASCII, so nothing reaches the
+# rendered readout. `--verbose` additionally echoes each component line before
+# any parser sees it, so that echo strips control bytes rather than relying on
+# the rejection.
+#
+# check-render-color proves KASLD's OWN escapes strip back to the plain
+# rendering. It says nothing about escapes arriving in data, which is the gap
+# this guard covers.
+#
+# The stubs are shell scripts: the orchestrator execs whatever is executable in
+# the component directory, so no compiler is needed and the guard runs anywhere
+# the host binary does.
+# ---
+# <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
+
+# Literal control bytes, built once. The textual form "\033" is not a portable
+# pattern -- some greps read it as an escape and some as four characters, so a
+# guard written that way matches nothing and reports success on every run.
+ESC=$(printf '\033')
+CR=$(printf '\r')
+
+HOST_TRIPLE=$(cc -dumpmachine 2>/dev/null || echo unknown)
+BIN="$ROOT/build/$HOST_TRIPLE/kasld"
+if [ ! -x "$BIN" ]; then
+  printf '%swire-text guard: SKIP%s (no host binary at %s; run make first)\n' \
+    "$YELLOW" "$RESET" "$BIN"
+  exit 0
+fi
+
+WORK=$(mktemp -d "${TMPDIR:-/tmp}/kasld-wiretext.XXXXXX") || exit 1
+trap 'rm -rf "$WORK"' EXIT INT TERM
+EMPTY="$WORK/sysroot"
+STUBS="$WORK/components"
+mkdir -p "$EMPTY" "$STUBS" || exit 1
+
+# An empty sysroot keeps the run hermetic: no host fact is read, so the output
+# is the stubs' contribution and the architectural defaults.
+
+# A clean record, so a run that rejects everything cannot pass by accident.
+cat >"$STUBS/stub_clean" <<'STUB'
+#!/bin/sh
+echo "V kernel_text:cleanname pos=base conf=parsed lo=0xffffffff8b600000"
+STUB
+
+# One stub per hostile field. Each carries an erase-line and a colour sequence,
+# the pair that rewrites a rendered line in place.
+cat >"$STUBS/stub_name" <<'STUB'
+#!/bin/sh
+printf 'V module:ev\033[2K\rHOSTILENAME pos=base conf=parsed lo=0xffffffffc0abc000\n'
+STUB
+
+cat >"$STUBS/stub_gate" <<'STUB'
+#!/bin/sh
+printf 'R cat=mitigation gate=kpti\033[2K\rHOSTILEGATE msg="blocked"\n'
+exit 69
+STUB
+
+cat >"$STUBS/stub_msg" <<'STUB'
+#!/bin/sh
+printf 'R cat=mitigation gate=kpti msg="blocked \033[7mHOSTILEMSG\033[0m here"\n'
+exit 69
+STUB
+
+# A high byte, covering the other half of the rule. The admissible set stops at
+# 0x7E, not merely below 0x20: 0x80..0x9F is the C1 control range, which a
+# terminal in an 8-bit locale acts on with no ESC byte involved, and it cannot
+# be excluded byte-wise without also excluding UTF-8 continuation bytes. A guard
+# that only emitted ESC would keep passing if that half were dropped.
+cat >"$STUBS/stub_highbyte" <<'STUB'
+#!/bin/sh
+printf 'V module:hi\233HOSTILEHIGH pos=base conf=parsed lo=0xffffffffc0def000\n'
+STUB
+
+chmod +x "$STUBS"/stub_* || exit 1
+
+fail=0
+checked=0
+
+# Every mode that renders component-supplied text: the default readout, the
+# verbose readout (which also echoes raw component lines), and the hardening
+# report (where a disposition's gate and msg are shown).
+for mode in "-q" "-q -v" "-q -H"; do
+  # shellcheck disable=SC2086  # $mode is a deliberate word-split option list
+  out=$(KASLD_SYSROOT="$EMPTY" KASLD_COMPONENT_DIR="$STUBS" \
+        "$BIN" $mode 2>&1) || true
+  checked=$((checked + 1))
+
+  case $out in
+  *"$ESC"*)
+    printf '%s  escape byte reached the terminal%s: kasld %s\n' \
+      "$RED" "$RESET" "$mode"
+    fail=1 ;;
+  esac
+  case $out in
+  *"$CR"*)
+    printf '%s  carriage return reached the terminal%s: kasld %s\n' \
+      "$RED" "$RESET" "$mode"
+    fail=1 ;;
+  esac
+
+  # A record whose free-text field left printable ASCII must not RENDER,
+  # whichever byte took it out of the set. Under --verbose the raw component
+  # line is echoed on purpose, so the marker legitimately appears there with its
+  # control bytes already neutralised; the rendered readout is every other line.
+  # Dropping the echoed lines -- those that still carry a wire tag -- separates
+  # the two without needing to know the readout's layout.
+  # -a: the output can carry a high byte, and grep would otherwise report
+  # "binary file matches" instead of the lines, leaving the check below with
+  # nothing to search and passing vacuously.
+  rendered=$(printf '%s\n' "$out" | LC_ALL=C grep -av '^[VPSR] ' || true)
+  for marker in HOSTILENAME HOSTILEGATE HOSTILEMSG HOSTILEHIGH; do
+    case $rendered in
+    *"$marker"*)
+      printf '%s  a rejected record rendered anyway%s: %s in kasld %s\n' \
+        "$RED" "$RESET" "$marker" "$mode"
+      fail=1 ;;
+    esac
+  done
+
+  # The clean record must still render: a guard that passes because nothing at
+  # all was accepted would report success on a parser that rejects everything.
+  # Checked under --verbose, the mode that lists a record's name at all; the
+  # default readout reports resolved quantities rather than per-record labels.
+  case $mode in
+  "-q -v")
+    case $out in
+    *cleanname*) ;;
+    *)
+      printf '%s  the clean record did not render%s: kasld %s\n' \
+        "$RED" "$RESET" "$mode"
+      fail=1 ;;
+    esac ;;
+  esac
+done
+
+if [ "$fail" -eq 0 ]; then
+  printf '%swire-text guard: OK%s (%d modes, 4 hostile records, none rendered)\n' \
+    "$GREEN" "$RESET" "$checked"
+else
+  printf '%swire-text guard: FAIL%s\n' "$RED" "$RESET"
+fi
+exit "$fail"