components: structured disposition to replace skip-reason

The free-text `R <text>` skip-reason was captured but never surfaced,
and only 8 components emitted it. Replace it with a structured
disposition, `R cat=<category> [gate=<token>] [msg="<text>"]`, in a
closed vocabulary (mitigation / absent / disabled / inconclusive) that
refines the exit code. Typed emitters return the exit code the category
implies, so the two channels cannot disagree; a mitigation names the
control it confirmed.

Surface it per-component in JSON, as a mitigation digest in default text
and markdown, in full under --verbose, and as confirmed_mitigations in
the hardening report. posture-diff now flags a confirmed mitigation that
stopped blocking a leak; posture-summary gains a defenses column. Add a
parse_disposition fuzz harness (and fix an undefined LINE_LEN in two
sibling harnesses). Update CONTRIBUTING and the usage/architecture docs.

Author: bcoles

CONTRIBUTING.md

@@ -63,9 +63,11 @@ protocol — the field grammar, a field-by-field anatomy of a line, and the
 region/confidence vocabularies — is documented in
 [docs/architecture.md → The tagged-line protocol](docs/architecture.md#the-tagged-line-protocol).
 
-The orchestrator ignores any line that does not begin with `P` or `V` followed
-by a space, so a component can freely print diagnostic messages (progress,
-errors, explanations). A component may emit zero, one, or multiple tagged lines.
+Beyond the address records (`P`/`V`), two more tagged kinds share the channel —
+scalar facts (`S`) and dispositions (`R`); the orchestrator parses all three and
+ignores anything else, so a component can freely print diagnostic messages
+(progress, errors, explanations). A component may emit zero, one, or multiple
+tagged lines.
 
 ### Position vs. confidence
 
@@ -182,12 +184,31 @@ failed to randomize) emits scalar facts via `kasld_emit_scalar()` instead of an
 address; which facts, and how the engine consumes each, are documented in
 [docs/architecture.md → KASLR runtime states](docs/architecture.md#kaslr-runtime-states).
 
-A leak or probe that determines it cannot run — or ran and found nothing worth
-attributing to a specific gate — calls `kasld_skip_reason(text)`, which emits a
-short `R` skip-reason line (e.g. "KPTI enabled", "not an Intel CPU"). The
-orchestrator captures it onto the per-component log; it is recorded metadata,
-never engine evidence, and is orthogonal to the exit code: the code names the
-outcome class, the reason names the specific gate within it.
+A leak or probe that ends without a tagged result can report *why* with a
+**disposition** — a short `R` line in a closed category that refines the exit
+code (recorded metadata, never engine evidence). The category carries the
+distinction the exit code cannot: an unavailable technique blocked by a
+*defensive control on the target* versus one that merely lacks a *prerequisite
+on this host*, and an empty run that is a deliberate opt-out versus an honest
+"ran, no clean signal, cannot prove why". The typed emitters emit the line and
+return the exit code the category implies, so the two channels cannot disagree:
+
+| Emitter | Meaning | Returns |
+|---|---|---|
+| `kasld_disp_mitigation(gate, msg)` | A defensive control foiled it; `gate` names the control (`kpti`, a `CONFIG_` id, a CVE id) and is **required** | `KASLD_EXIT_UNAVAILABLE` |
+| `kasld_disp_mitigation_denied(gate, msg)` | A control *denied the source* (the access-denied variant) | `KASLD_EXIT_NOPERM` |
+| `kasld_disp_absent(msg)` | An attacker prerequisite is missing on this host | `KASLD_EXIT_UNAVAILABLE` |
+| `kasld_disp_disabled(msg)` | Deliberate operator opt-out (needs a flag/env) | `KASLD_EXIT_UNAVAILABLE` |
+| `kasld_disp_inconclusive(msg)` | Ran, no clean signal, cannot prove why | `0` |
+
+Use `kasld_disposition(cat, gate, msg)` (no return value) where the exit code is
+decided elsewhere — inside a helper or a loop. A mitigation with no gate is a
+bug and emits nothing. Emit a disposition only when it soundly classifies the
+null result beyond the exit code — above all, a confirmed mitigation; a
+component that merely found no matching entry emits nothing. A `mitigation`
+disposition is confirmed active in the hardening report; the mitigation category
+is surfaced in default output, all categories under `--verbose`, and each
+disposition per-component in JSON.
 
 ### Diagnostics and options
 

Makefile

@@ -718,7 +718,7 @@ test-engine : $(TEST_ENG_BIN)
 FUZZ_CC      ?= clang
 FUZZ_CFLAGS  ?= -O1 -g -fsanitize=fuzzer,address,undefined -DKASLD_TESTING -I src
 FUZZ_OUT     := $(BUILD_DIR)/fuzz
-FUZZ_TARGETS := fuzz_parse_hex fuzz_capture_result fuzz_capture_scalar fuzz_parse_meta fuzz_btf
+FUZZ_TARGETS := fuzz_parse_hex fuzz_capture_result fuzz_capture_scalar fuzz_parse_meta fuzz_parse_disposition fuzz_btf
 FUZZ_BINS    := $(addprefix $(FUZZ_OUT)/,$(FUZZ_TARGETS))
 
 $(FUZZ_OUT)/% : tests/fuzz/%.c

docs/architecture.md

@@ -407,10 +407,12 @@ V vmalloc pos=interior conf=heuristic sample=0xffffc90000123456
 P ram pos=extent conf=parsed lo=0x100000 hi=0x7fedffff
 ```
 
-The orchestrator ignores any line that does not begin with `P` or `V` followed
-by a space, so components can freely print diagnostics. A component may emit
-zero, one, or multiple tagged lines, and it never writes the format by hand — it
-calls one of the five emitter helpers (see
+Address records begin with `P` or `V`; two further tagged kinds share the
+channel — `S` (a scalar system fact, via `kasld_emit_scalar()`) and `R` (a
+component *disposition*: why it produced no tagged result, via the disposition
+emitters). Any other line is a diagnostic and ignored, so components can print
+freely. A component may emit zero, one, or multiple tagged lines, and it never
+writes the format by hand — it calls one of the emitter helpers (see
 [Emitter API](../CONTRIBUTING.md#emitter-api)), which produce the correct shape
 and reject malformed inputs at the source.
 

docs/usage.md

@@ -427,9 +427,11 @@ The `environment` object is the recon vantage: `container`, `seccomp`,
 leak sources (fields are a `null` or enum when they do not apply).
 
 The `components` array holds one record per component — `name`,
-`exit_code`, `outcome`, and the parsed `meta` from
-`KASLD_META` (including `cve` / `patch` / `config` / `sysctl` keys). The
-`hardening` object is described under
+`exit_code`, `outcome`, an optional `disposition` (why a component produced no
+tagged result: `category` — `mitigation` / `absent` / `disabled` /
+`inconclusive` — plus, for a mitigation, the `gate` it confirmed and an optional
+`message`), and the parsed `meta` from `KASLD_META` (including `cve` / `patch` /
+`config` / `sysctl` keys). The `hardening` object is described under
 [Hardening assessment](#hardening-assessment).
 A per-component patch worklist — `{component, cve, fixed_in, leaked_here}`
 — is a direct projection of the `components` array:
@@ -489,7 +491,11 @@ $ ./kasld --explain
 
 The `--hardening` (`-H`) flag appends a post-run hardening assessment that
 evaluates the system's KASLR defenses based on the component results and
-their machine-readable metadata. The assessment has seven sections:
+their machine-readable metadata. It opens with **Confirmed active mitigations**
+(shown when present) — controls a component observed to defeat its leak this
+run, keyed by the gate (`kpti`, an MDS hardware fix, a hardening `CONFIG`); this
+is the runtime-observed complement to the sysctl gates, and appears in json as
+`hardening.confirmed_mitigations`. It is followed by seven analysis sections:
 
 1. **KASLR posture** (only when degraded) — surfaces a runtime KASLR
    state that downgrades effective slot entropy to 0 bits. Fires on

extra/posture-diff

@@ -95,7 +95,8 @@ posture='{
   guar_bits:    (.kaslr.inferred.entropy_bits // 0),
   pguar_bits:   (.kaslr.inferred_physical.entropy_bits // 0),
   unpatched:    ([(.hardening.patched_vulnerabilities.possibly_unpatched // [])[].component] | sort),
-  defenses_off: ([(.hardening.active_defenses // [])[] | select(.active == false) | .gate] | sort)
+  defenses_off: ([(.hardening.active_defenses // [])[] | select(.active == false) | .gate] | sort),
+  confirmed:    ([(.hardening.confirmed_mitigations // [])[].gate] | sort | unique)
 }'
 
 b_posture=$(jq "$posture" "$base") || exit 2
@@ -116,7 +117,12 @@ findings=$(jq -rn --argjson b "$b_posture" --argjson c "$c_posture" '
     then "KASLR posture worsened: \($b.kaslr) -> \($c.kaslr)"
     else empty end ),
   ( ($c.unpatched - $b.unpatched)[] | "new CVE-class leak succeeded: \(.)" ),
-  ( ($c.defenses_off - $b.defenses_off)[] | "defense turned off: \(.)" )
+  ( ($c.defenses_off - $b.defenses_off)[] | "defense turned off: \(.)" ),
+  # A control confirmed to defeat a leak at baseline no longer does — a
+  # non-sysctl defense (KPTI, an MDS hardware fix, a hardening CONFIG) has
+  # weakened. These come from deterministic checks, so a drop is a real change,
+  # not run-to-run noise.
+  ( ($b.confirmed - $c.confirmed)[] | "confirmed mitigation no longer blocking a leak: \(.)" )
 ') || exit 2
 
 if [ -n "$findings" ]; then

extra/posture-summary

@@ -96,6 +96,7 @@ row='{
   pbits:  (.kaslr.inferred_physical.entropy_bits // 0),
   leaks:  (.hardening.exposure.succeeded // 0),
   total:  (.hardening.exposure.total // 0),
+  defenses: ([(.hardening.confirmed_mitigations // [])[].gate] | unique | length),
   cves:   ((.hardening.patched_vulnerabilities.possibly_unpatched // []) | length),
   topfix: ((.hardening.available_hardening // []) | (if length > 0 then .[0].action else "-" end))
 }'
@@ -120,7 +121,7 @@ done
   exit 2
 }
 
-HDR="host arch kernel kaslr vbits pbits leaks cves top-fix"
+HDR="host arch kernel kaslr vbits pbits leaks defenses cves top-fix"
 
 case "$fmt" in
 json)
@@ -129,19 +130,19 @@ json)
 csv)
   echo "$HDR" | tr ' ' ','
   jq -rs 'sort_by(.host)[] | [.host, .arch, .kernel, .kaslr, .vbits, .pbits,
-    "\(.leaks)/\(.total)", .cves, .topfix] | @csv' "$tmp"
+    "\(.leaks)/\(.total)", .defenses, .cves, .topfix] | @csv' "$tmp"
   ;;
 markdown)
   echo "$HDR" | sed 's/ / | /g; s/^/| /; s/$/ |/'
   echo "$HDR" | sed 's/[^ ]*/---/g; s/ / | /g; s/^/| /; s/$/ |/'
-  jq -rs 'sort_by(.host)[] | "| \(.host) | \(.arch) | \(.kernel) | \(.kaslr) | \(.vbits) | \(.pbits) | \(.leaks)/\(.total) | \(.cves) | \(.topfix) |"' "$tmp"
+  jq -rs 'sort_by(.host)[] | "| \(.host) | \(.arch) | \(.kernel) | \(.kaslr) | \(.vbits) | \(.pbits) | \(.leaks)/\(.total) | \(.defenses) | \(.cves) | \(.topfix) |"' "$tmp"
   ;;
 text)
   # Header + rows as tab-separated, then align each column to its widest cell.
   {
     echo "$HDR" | tr ' ' '\t'
     jq -rs 'sort_by(.host)[] | [.host, .arch, .kernel, .kaslr, "\(.vbits)b",
-      "\(.pbits)b", "\(.leaks)/\(.total)", .cves, .topfix] | @tsv' "$tmp"
+      "\(.pbits)b", "\(.leaks)/\(.total)", .defenses, .cves, .topfix] | @tsv' "$tmp"
   } | awk -F'\t' '
     { for (i = 1; i <= NF; i++) { c[NR, i] = $i; if (length($i) > w[i]) w[i] = length($i) } nc = NF; nr = NR }
     END { for (r = 1; r <= nr; r++) { line = ""

src/components/databounce.c

@@ -171,15 +171,13 @@ int main(void) {
   if (!is_intel_cpu()) {
     fprintf(stderr,
             "[-] databounce: not an Intel CPU; attack not applicable\n");
-    kasld_skip_reason("not an Intel CPU");
-    return KASLD_EXIT_UNAVAILABLE;
+    return kasld_disp_absent("not an Intel CPU");
   }
 
   if (!has_rtm()) {
     fprintf(stderr, "[-] databounce: TSX/RTM not available; "
                     "required for store-to-load forwarding\n");
-    kasld_skip_reason("TSX/RTM not available");
-    return KASLD_EXIT_UNAVAILABLE;
+    return kasld_disp_absent("TSX/RTM not available");
   }
 
   fprintf(stderr, "[.] databounce: using TSX abort mode\n");
@@ -221,8 +219,8 @@ int main(void) {
   if (!addr || best_count < DATABOUNCE_SWEEPS / 4) {
     fprintf(stderr, "[-] databounce: no kernel mapping detected "
                     "(CPU may not be vulnerable)\n");
-    kasld_skip_reason("no kernel mapping (CPU may not be vulnerable)");
-    return 0;
+    return kasld_disp_inconclusive(
+        "no kernel mapping (CPU may not be vulnerable)");
   }
 
   /* Same trampoline-vs-stext distinction as echoload: KPTI changes

src/components/echoload.c

@@ -225,14 +225,12 @@ int main(void) {
   if (!getenv("KASLD_EXPERIMENTAL")) {
     fprintf(stderr, "[-] echoload: experimental component; "
                     "set KASLD_EXPERIMENTAL=1 to enable\n");
-    kasld_skip_reason("experimental (set KASLD_EXPERIMENTAL=1)");
-    return KASLD_EXIT_UNAVAILABLE;
+    return kasld_disp_disabled("experimental (set KASLD_EXPERIMENTAL=1)");
   }
 
   if (!is_intel_cpu()) {
     fprintf(stderr, "[-] echoload: not an Intel CPU; attack not applicable\n");
-    kasld_skip_reason("not an Intel CPU");
-    return KASLD_EXIT_UNAVAILABLE;
+    return kasld_disp_absent("not an Intel CPU");
   }
 
   int use_tsx;
@@ -280,18 +278,17 @@ int main(void) {
   if (!addr) {
     fprintf(stderr, "[-] echoload: no kernel mapping detected "
                     "(CPU may not be vulnerable)\n");
-    kasld_skip_reason("no kernel mapping (CPU may not be vulnerable)");
-    return 0;
+    return kasld_disp_inconclusive(
+        "no kernel mapping (CPU may not be vulnerable)");
   }
 
   /* Unanimity verification: repeat the full sweep and require every result to
    * match. If any sweep disagrees, the result is rejected entirely. */
   for (int v = 0; v < ECHOLOAD_VERIFY; v++) {
     if (addr != echoload_sweep(use_tsx)) {
       fprintf(stderr, "[-] echoload: inconsistent results. Aborting ...\n");
-      kasld_skip_reason(
+      return kasld_disp_inconclusive(
           "inconsistent results (noise); a quieter run may resolve");
-      return 0;
     }
   }
 

src/components/entrybleed.c

@@ -273,8 +273,7 @@ static int detect_kernel_version(void) {
 
   if (strstr(u.machine, "64") == NULL) {
     kasld_err("system is not using a 64-bit kernel");
-    kasld_skip_reason("not a 64-bit kernel");
-    exit(KASLD_EXIT_UNAVAILABLE);
+    exit(kasld_disp_absent("not a 64-bit kernel"));
   }
 
   snprintf(kernel_version, KERNEL_VERSION_SIZE_BUFFER, "%s %s", u.release,
@@ -289,7 +288,8 @@ static int detect_kernel_version(void) {
   }
 
   kasld_err("kernel version '%s' not recognized", kernel_version);
-  kasld_skip_reason("no offsets for this kernel build");
+  kasld_disposition(DISP_INCONCLUSIVE, NULL,
+                    "no offsets for this kernel build");
   return -1;
 }
 
@@ -336,8 +336,7 @@ static unsigned long get_kernel_addr_entrybleed(void) {
 
   if (cpu == CPU_VENDOR_UNKNOWN) {
     kasld_err("Unknown CPU vendor");
-    kasld_skip_reason("unknown CPU vendor");
-    exit(KASLD_EXIT_UNAVAILABLE);
+    exit(kasld_disp_absent("unknown CPU vendor"));
   }
 
   bool pti = detect_kpti();
@@ -347,8 +346,7 @@ static unsigned long get_kernel_addr_entrybleed(void) {
 
   if (cpu == CPU_VENDOR_AMD && pti) {
     kasld_err("AMD systems with KPTI enabled are not affected by EntryBleed");
-    kasld_skip_reason("AMD with KPTI enabled (not affected)");
-    exit(KASLD_EXIT_UNAVAILABLE);
+    exit(kasld_disp_mitigation("kpti", "AMD with KPTI enabled (not affected)"));
   }
 
   int kernel = detect_kernel_version();
@@ -368,7 +366,8 @@ static unsigned long get_kernel_addr_entrybleed(void) {
     if (addr != leak_syscall_entry(offset)) {
       addr = 0;
       kasld_err("Inconsistent results. Aborting ...");
-      kasld_skip_reason(
+      kasld_disposition(
+          DISP_INCONCLUSIVE, NULL,
           "inconsistent results (noise); a quieter run may resolve");
       break;
     }

src/components/kernelsnitch.c

@@ -769,8 +769,7 @@ int main(void) {
   if (!getenv("KASLD_EXPERIMENTAL")) {
     fprintf(stderr, "[-] kernelsnitch: experimental component; "
                     "set KASLD_EXPERIMENTAL=1 to enable\n");
-    kasld_skip_reason("experimental (set KASLD_EXPERIMENTAL=1)");
-    return KASLD_EXIT_UNAVAILABLE;
+    return kasld_disp_disabled("experimental (set KASLD_EXPERIMENTAL=1)");
   }
 
   kasld_info("trying KernelSnitch (futex hash timing) ...");
@@ -785,8 +784,8 @@ int main(void) {
   if (prctl(PR_FUTEX_HASH, PR_FUTEX_HASH_GET_SLOTS, 0, 0, 0) >= 0) {
     fprintf(stderr, "[-] kernelsnitch: CONFIG_FUTEX_PRIVATE_HASH is enabled; "
                     "attack not possible\n");
-    kasld_skip_reason("CONFIG_FUTEX_PRIVATE_HASH enabled");
-    return KASLD_EXIT_UNAVAILABLE;
+    return kasld_disp_mitigation("CONFIG_FUTEX_PRIVATE_HASH",
+                                 "CONFIG_FUTEX_PRIVATE_HASH enabled");
   }
 
   /* Determine futex hash table size. */
@@ -806,8 +805,7 @@ int main(void) {
 
   /* Phase 1: Pile-up. */
   if (create_pileup() < 0) {
-    kasld_skip_reason("could not create the futex pile-up");
-    return 0;
+    return kasld_disp_inconclusive("could not create the futex pile-up");
   }
 
   /* Phase 2: Find collision addresses. */
@@ -816,7 +814,8 @@ int main(void) {
   if (find_collisions(collisions, &num_collisions, hashsize) < 0) {
     fprintf(stderr, "[-] kernelsnitch: insufficient collisions; "
                     "timing signal too noisy?\n");
-    kasld_skip_reason("insufficient collisions (timing too noisy)");
+    kasld_disposition(DISP_INCONCLUSIVE, NULL,
+                      "insufficient collisions (timing too noisy)");
     cleanup_pileup();
     return 0;
   }
@@ -872,8 +871,8 @@ int main(void) {
   if (!result) {
     fprintf(stderr, "[-] kernelsnitch: brute-force failed to find "
                     "mm_struct address\n");
-    kasld_skip_reason("brute-force did not find the mm_struct address");
-    return 0;
+    return kasld_disp_inconclusive(
+        "brute-force did not find the mm_struct address");
   }
 
   /* The brute-forced address is the current task's mm_struct, allocated