tests: assert no arithmetic-input validator accepts a metacharacter

check-results and ksymoff both feed parsed fields into shell arithmetic,
where $(( x )) evaluates embedded command substitutions and array
subscripts -- and check-results is documented as running under sudo, so a
value like a[$(cmd)] reaching it is root command execution. Four functions
guard that across the two scripts: numeric() and hex16() in one, is_hex()
and is_dec() in the other.

They are duplicated because neither script can source a library: ksymoff
installs to $PREFIX/bin as a standalone program, and check-results is
copied to a target and run there. So a correction to one does not reach
the others, and the failure mode of getting it wrong is root exec.

The guard asserts REJECTION, not sameness. The four accept different sets
deliberately -- is_hex refuses an 0x prefix because its callers strip one
first, is_dec is decimal-only for --page-shift's range check -- so diffing
them would fail on correct code. Every one must refuse a shared corpus of
command substitutions, backticks, array subscripts and arithmetic
operators.

Two assertions beyond that. Each validator must ACCEPT a known-good value,
so one that rejected everything could not pass the corpus vacuously while
breaking the tool it guards. And the @arith-validator marker count must
match the number exercised, so a validator added later cannot quietly
escape the corpus -- the marker sits at the definition, making
registration the same act as writing it.

Definitions are extracted rather than sourced, both scripts running
top-level code. Extraction also fails if a validator stops being
self-contained, which is when a shared helper has crept in.

Each definition now names the other three and records why they cannot be
unified.

Author: bcoles

Makefile

@@ -686,6 +686,7 @@ lint :
 	@$(TEST_DIR)/check-version
 	@$(TEST_DIR)/check-posture-diff
 	@$(TEST_DIR)/check-posture-summary
+	@$(TEST_DIR)/check-validators
 	@$(TEST_DIR)/check-shellcheck
 	@$(TEST_DIR)/check-baseline
 	@$(TEST_DIR)/check-render-parity

docs/testing.md

@@ -142,6 +142,7 @@ and `make` halts on the first.
 | `check-shellcheck` | shellcheck over the `extra/` helper scripts |
 | `check-confidence-floor` | no engine rule pins the *guaranteed* window from a guess — a sub-floor signal may shape `likely` only, outside the reviewed allowlist |
 | `check-unattributed-leak-floor` | a component that cannot establish *which* region its leaked value belongs to stays below the sound floor. Some leaks hand over a kernel address with no evidence of what it points at: the value is real, the region is a guess, and a region guess admitted to the guaranteed window is a soundness bug rather than an imprecision — an interior-text sample implies `image_base <= sample`, so a value that is not text but sits below the real `_text` carves the truth out of the window that promises to contain it. `/proc/<pid>/syscall` (CVE-2020-28588) is the registered case: it leaks whatever the reading task's call chain left on `proc_pid_syscall()`'s kernel stack frame, which is a return address into text on x86_32, arm and riscv32, and a direct-map pointer on powerpc and mips, where the image is randomized above them so the leaked word sits *below* `_text`. Nothing in the component can tell the two apart, because the text band is the unknown being solved for. The rule is per file rather than per call — a listed component has no region-establishing evidence at all, so no emission it makes can earn the sound band — which also keeps the matcher line-oriented, since a confidence argument routinely wraps onto its own line. A component that gains real corroboration is removed from the list, never raised in place |
+| `check-validators` | no arithmetic-input validator accepts anything dangerous. `extra/check-results` and `extra/ksymoff` both feed parsed fields into shell arithmetic, where `$(( x ))` evaluates embedded command substitutions — and `check-results` is documented as running under `sudo`, so a value like `a[$(cmd)]` reaching it would be root command execution. The validator is duplicated four ways because neither script can source a library (`ksymoff` installs to `$PREFIX/bin`; `check-results` is copied to a target), so a correction to one does not reach the others. What is asserted is *rejection*, not sameness: the four accept different sets on purpose. Also asserts each one accepts a known-good value, so a validator that rejected everything could not pass vacuously, and that the `@arith-validator` marker count matches the number exercised, so a new one cannot escape the corpus |
 | `check-arch-macros` | every macro an architecture header defines is read by something. A name nothing reads is a misspelling, a retired spelling one header kept, or dead weight — and the first two are silent: the architecture falls back to the contract's default for the macro it *meant* to set, which costs precision with nothing to show for it. No test catches that, because the tests read the same declaration the code does and assert whatever it says. Complements the retired-spelling `#error`s in `api.h`, which fail the build for one known-old name; this catches the names no such check lists |
 | `check-lattice-seam` | the quantities held to the estimate accessors (`Q_PAGE_OFFSET`, `Q_VA_BITS`) are read through `quantity_pinned/window/admits/narrowed`, never through `.lo` / `.hi`. `struct estimate` means different things per lattice — on a finite set `lo` is a live-candidate bitmask and `hi` is unused — and which lattice a quantity uses is declared once in the quantity table, so a direct read hard-codes an answer the reader never asked for. Nothing would fail loudly: a bitmask read as an address is a small integer, so the result is a plausible wrong answer rather than a crash. The pointer alias is discovered from its binding rather than assumed to be named `po`, so renaming it cannot slip a read past |
 | `check-page-offset-substitution` | no engine rule or leak component substitutes the compile-time `PAGE_OFFSET` for the target's linear-map base. That constant describes the analysing build, not the kernel under examination, and on the VMSPLIT arches the two differ routinely — code that reaches for it is asserting the split it was compiled with. The failure is invisible: it compiles everywhere, passes on the whole default-split corpus, and is off by exactly the gap between two build configurations, which is zero on every machine anyone tests. In a rule, an equality must read the resolved `Q_PAGE_OFFSET` via `quantity_pinned()`, and a bound may instead use `PAGE_OFFSET_MAX` (upper) or `PAGE_OFFSET_MIN` (lower), which hold against every target and need no resolution. A component runs before inference and can never see an estimate, so it measures the boundary instead — `kasld_kernel_pointer_floor()` for the user/kernel split, `kasld_page_offset_floor()` for a region-tagged bound. Comments and string literals are stripped first, and `#if` / `#elif` lines are exempt by construction (a constant expression cannot call an accessor, which is why the band assertions keep `PAGE_OFFSET` a plain scalar), so only C code counts |

extra/check-results

@@ -72,6 +72,14 @@ skip() { update_counts skip; printf "  ${YELLOW}SKIP${RESET}  %s\n" "$1"; }
 # -------------------------------------------------------------------------
 
 # Normalize a hex string (with or without 0x prefix) to 16-char lowercase
+#
+# @arith-validator — one of four guarding the same property across two scripts:
+# numeric() and hex16() here, is_hex() and is_dec() in extra/ksymoff. They are
+# duplicated because neither script can source a library (ksymoff installs to
+# $PREFIX/bin; this one is copied to a target), so a correction to one does NOT
+# reach the others -- review all four together. They accept different sets on
+# purpose; what none of them may do is accept a shell metacharacter, which
+# tests/check-validators asserts against a shared adversarial corpus.
 hex16() {
   # SECURITY: reject non-hex input up front so the reformatted value can never
   # carry shell/arithmetic metacharacters into a later `$(( 0x... ))` — the same
@@ -115,6 +123,8 @@ get_field() {
 # run `cmd` as root. So EVERY value that reaches `$(( ))` must pass through
 # numeric() first; anything with a non-[0-9a-fx] character is rejected to empty
 # (treated as an absent field by the callers' existing `[ -n ]` checks).
+# @arith-validator — see the note on hex16() above; all four are reviewed
+# together.
 numeric() {
   printf '%s' "$1" | grep -qiE '^(0x)?[0-9a-f]+$' && printf '%s' "$1"
   return 0 # never fail the substitution (a rejected value is just empty output)

extra/ksymoff

@@ -143,8 +143,17 @@ hex_ult() {  # a b (hex, no 0x) -> true if a < b unsigned
 # bash arithmetic evaluates embedded command substitutions and array subscripts,
 # so a value like `a[$(cmd)]` from an untrusted symbol source would execute as a
 # command. Every arithmetic input is validated by one of these first. (The same
-# guard is duplicated in extra/check-results — deliberately no shared library.)
+# guard is duplicated in extra/check-results — deliberately no shared library:
+# ksymoff installs to $PREFIX/bin and check-results is copied to a target, so
+# neither can source one. A correction here does NOT reach numeric()/hex16()
+# there -- review all four together. The accept sets differ on purpose (is_hex
+# refuses an 0x prefix, its callers having stripped one; is_dec is decimal-only
+# for --page-shift); what none may do is accept a shell metacharacter, which
+# tests/check-validators asserts against a shared adversarial corpus.
+#
+# @arith-validator
 is_hex() { case "$1" in ''|*[!0-9A-Fa-f]*) return 1 ;; *) return 0 ;; esac; }
+# @arith-validator
 is_dec() { case "$1" in ''|*[!0-9]*)       return 1 ;; *) return 0 ;; esac; }
 
 # -- Argument parsing -----------------------------------------------------

tests/check-validators

@@ -0,0 +1,179 @@
+#!/bin/sh
+# This file is part of KASLD - https://github.com/bcoles/kasld
+#
+# check-validators — no arithmetic-input validator accepts anything dangerous.
+#
+# extra/check-results and extra/ksymoff both feed parsed fields into shell
+# arithmetic, and `$(( x ))` evaluates embedded command substitutions and array
+# subscripts. A value like `a[$(cmd)]` reaching it runs cmd -- as ROOT in
+# check-results, whose documented use is `sudo check-results results.txt` and
+# `<component> | sudo check-results -`. Each script therefore validates every
+# arithmetic input first.
+#
+# The guard exists because that validator is DUPLICATED. Neither script can
+# source a shared library: ksymoff is installed to $PREFIX/bin as a standalone
+# program, and check-results is meant to be copied to a target and run there. So
+# there are four implementations of one security property, and a correction to
+# one does not reach the others.
+#
+# What is asserted is REJECTION, not sameness. The four legitimately differ in
+# what they accept -- is_hex refuses an 0x prefix because its callers strip one
+# first, and is_dec is decimal-only because --page-shift feeds a decimal range
+# check. Diffing them would fail on correct code. The invariant that actually
+# matters is that none of them lets a shell metacharacter through.
+#
+# Also asserted:
+#   - each validator ACCEPTS a known-good value, so one that rejected
+#     everything could not pass the corpus vacuously while breaking the tool;
+#   - the number of @arith-validator markers in the two scripts equals the
+#     number exercised here, so a validator added later cannot quietly escape
+#     the corpus.
+#
+# The definitions are extracted rather than sourced: both scripts run top-level
+# code and cannot be sourced. Extraction also fails loudly if a validator stops
+# being self-contained -- which is exactly when a shared helper has crept in.
+# ---
+# <bcoles@gmail.com>
+
+set -u
+ROOT=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)
+
+if [ -t 1 ]; then
+  RED=$(printf '\033[31m')
+  GREEN=$(printf '\033[32m')
+  RESET=$(printf '\033[0m')
+else
+  RED=
+  GREEN=
+  RESET=
+fi
+
+fail=0
+note() {
+  printf '%scheck-validators: FAIL%s — %s\n' "$RED" "$RESET" "$1" >&2
+  fail=1
+}
+
+# Pull one shell function definition out of a script, by brace depth so a
+# one-liner and a multi-line body both come out whole.
+extract() {
+  awk -v fn="$2" '
+    index($0, fn "()") == 1 { inb = 1 }
+    inb {
+      print
+      t = $0; o = gsub(/\{/, "{", t)
+      t = $0; c = gsub(/\}/, "}", t)
+      depth += o - c
+      if (o > 0) seen = 1
+      if (seen && depth <= 0) exit
+    }
+  ' "$1"
+}
+
+# Inputs no validator may ever accept. Anything here reaching `$(( ))` is
+# command execution, or arithmetic the caller never intended.
+corpus=$(
+  cat <<'ADVERSARIAL'
+a[$(touch /tmp/kasld-pwn)]
+$(id)
+`id`
+$((1))
+${IFS}
+0x1$(id)
+x[0]
+1+1
+1-1
+1;id
+1 2
+-1
++1
+0xg
+zz
+1.0
+0x
+*
+?
+../etc/passwd
+ADVERSARIAL
+)
+
+# validator | script | convention | a value it MUST accept
+#   echo — accepted when it echoes something back (rejection is empty output)
+#   exit — accepted when it returns 0
+checks="
+numeric|extra/check-results|echo|deadbeef
+hex16|extra/check-results|echo|deadbeef
+is_hex|extra/ksymoff|exit|deadbeef
+is_dec|extra/ksymoff|exit|1234
+"
+
+n_checked=0
+tmp=$(mktemp) || exit 1
+trap 'rm -f "$tmp"' EXIT INT TERM
+
+# Read into positional args so the counters below survive (a `while read` on the
+# far side of a pipe runs in a subshell).
+oldifs=$IFS
+IFS='
+'
+# shellcheck disable=SC2086  # deliberate split: one row per newline
+set -- $checks
+IFS=$oldifs
+
+for row in "$@"; do
+  [ -n "$row" ] || continue
+  fn=$(printf '%s' "$row" | cut -d'|' -f1)
+  script=$(printf '%s' "$row" | cut -d'|' -f2)
+  conv=$(printf '%s' "$row" | cut -d'|' -f3)
+  good=$(printf '%s' "$row" | cut -d'|' -f4)
+  src="$ROOT/$script"
+
+  if [ ! -f "$src" ]; then
+    note "$script is missing"
+    continue
+  fi
+  def=$(extract "$src" "$fn")
+  if [ -z "$def" ]; then
+    note "$script: cannot extract $fn() -- is it still a self-contained function?"
+    continue
+  fi
+  n_checked=$((n_checked + 1))
+
+  # Non-vacuity first: a validator that rejects everything would sail through
+  # the corpus below while breaking the tool it guards.
+  if [ "$conv" = echo ]; then
+    got=$(printf '%s\n' "$def" "out=\$($fn '$good'); [ -n \"\$out\" ]" | sh 2>/dev/null && echo yes)
+  else
+    got=$(printf '%s\n' "$def" "$fn '$good'" | sh 2>/dev/null && echo yes)
+  fi
+  [ "${got:-}" = yes ] ||
+    note "$script: $fn() rejects '$good', which it must accept"
+
+  # Every adversarial input must be refused.
+  printf '%s\n' "$corpus" | while IFS= read -r bad; do
+    if [ "$conv" = echo ]; then
+      out=$(printf '%s\n' "$def" "$fn \"\$1\"" | sh -s -- "$bad" 2>/dev/null)
+      [ -z "$out" ] || printf 'ACCEPTED %s\n' "$bad"
+    else
+      printf '%s\n' "$def" "$fn \"\$1\"" | sh -s -- "$bad" 2>/dev/null &&
+        printf 'ACCEPTED %s\n' "$bad"
+    fi
+  done >"$tmp" 2>/dev/null
+  while IFS= read -r line; do
+    note "$script: $fn() accepted ${line#ACCEPTED }"
+  done <"$tmp"
+done
+
+# A validator added later must not escape the corpus. The marker sits at each
+# definition, so registering one is the same act as writing it.
+markers=$(cat "$ROOT/extra/check-results" "$ROOT/extra/ksymoff" |
+  grep -c '@arith-validator')
+if [ "${markers:-0}" -ne "$n_checked" ]; then
+  note "$markers @arith-validator markers but $n_checked exercised -- register the new one in this guard"
+fi
+
+if [ "$fail" -ne 0 ]; then
+  exit 1
+fi
+printf '%scheck-validators: OK%s (%s arithmetic-input validators, none accepts the adversarial corpus)\n' \
+  "$GREEN" "$RESET" "$n_checked"