components: standardise CLI parsing and diagnostic output

New include/kasld/cli.h: one option parser (kasld_cli — -v/--verbose,
-t/--time SECS, -h) and a levelled stderr logger (kasld_info/debug/err/
found). stdout is now the machine channel (wire lines only); every
bracketed [.]/[-]/[+] diagnostic moves to the logger.

mincore gains -t (tunable give-up budget); kernelsnitch's per-iteration
firehose is demoted to kasld_debug so it no longer floods -v.
tests/check-component-output ratchets the stream rule (no new raw stdout
printf); the older non-bracketed data-echo lines are baselined as a
tracked follow-on. Standard documented in CONTRIBUTING.

Author: bcoles

CONTRIBUTING.md

@@ -158,6 +158,40 @@ failed to randomise) 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).
 
+### Diagnostics and options
+
+Two channels, kept separate (`include/kasld/cli.h`):
+
+- **stdout is the machine channel** — *only* the `P`/`V`/`S` wire lines the
+  emitter helpers print. Never write a human message to stdout (so
+  `component 2>/dev/null` is clean, parseable output).
+- **stderr is the human channel** — every diagnostic, through the levelled
+  logger, never a bare `printf`/`fprintf`:
+
+  | Macro | Prefix | Use |
+  |---|---|---|
+  | `kasld_info(fmt, …)` | `[.]` | normal progress |
+  | `kasld_debug(fmt, …)` | `[.]` | firehose detail — printed only under verbose |
+  | `kasld_err(fmt, …)` | `[-]` | failure / data unavailable |
+  | `kasld_found(fmt, …)` | `[+]` | a leak was produced |
+
+  The `info`/`debug` split matters: verbose means different things per component
+  (a couple of lines for `proc_iomem`, a per-collision firehose for
+  `kernelsnitch`). Demote firehose lines to `kasld_debug` so a normal run — and
+  `kasld -v` — stay readable; they surface only under the component's own
+  verbose. `tests/check-component-output` ratchets this: a *new* component
+  printing a diagnostic to stdout fails the build.
+
+**Options** are optional and **manual** (testing/debugging — the orchestrator
+passes none and sets no env). If a component takes any, parse them with
+`kasld_cli(argc, argv)` rather than hand-rolling `argv` — it gives every
+component the same `-v` / `--verbose`, `-t SECS` / `--time` (the component's own
+probe budget, in seconds — *not* kasld's kill timeout), and `-h` / `--help`. A
+component then reads `kasld_verbose` (or `kasld_is_verbose()`) and `kasld_time_s`
+as it cares; one with no options stays `int main(void)`. `kasld_is_verbose()`
+also honours `$KASLD_VERBOSE`, so a `main(void)` component is debuggable without
+an `argc/argv` conversion.
+
 ### Exit code convention
 
 Components signal their outcome to the orchestrator via exit code:

Makefile

@@ -306,6 +306,7 @@ test : $(TEST_BIN) $(TEST_RENDER_BIN) $(TEST_EST_BIN) $(TEST_EV_BIN) $(TEST_ENG_
 	@$(TEST_DIR)/run-all
 	@$(TEST_DIR)/check-self-edges
 	@$(TEST_DIR)/check-truncation
+	@$(TEST_DIR)/check-component-output
 
 .PHONY: test-integration
 test-integration : $(TEST_INT_BIN)

src/components/bcm_msg_head_struct.c

@@ -32,6 +32,7 @@
 // <bcoles@gmail.com>
 
 #include "include/kasld/api.h"
+#include "include/kasld/cli.h"
 #include <fcntl.h>
 #include <linux/can.h>
 #include <linux/can/bcm.h>
@@ -106,7 +107,7 @@ static unsigned long get_kernel_addr_from_bcm_msg_head_struct(void) {
   char *endptr;
   unsigned long addr = 0;
 
-  printf("[.] trying bcm_msg_head struct stack pointer leak ...\n");
+  kasld_info("trying bcm_msg_head struct stack pointer leak ...");
 
   sock = socket(AF_CAN, SOCK_DGRAM, CAN_BCM);
 
@@ -173,7 +174,7 @@ static unsigned long get_kernel_addr_from_bcm_msg_head_struct(void) {
   (void)addrs;
   (void)endptr;
   (void)addr;
-  printf("[-] BCM bcm_msg_head leak shape targets a 64-bit kernel; skipping\n");
+  kasld_err("BCM bcm_msg_head leak shape targets a 64-bit kernel; skipping");
 #endif
 
   return 0;
@@ -184,7 +185,7 @@ static unsigned long get_kernel_addr_from_bcm_msg_head_struct(void) {
 int main(void) {
   unsigned long addr = get_kernel_addr_from_bcm_msg_head_struct();
   if (!addr) {
-    printf("[-] no kernel address leaked via BCM socket\n");
+    kasld_err("no kernel address leaked via BCM socket");
     return 0;
   }
 

src/components/boot_config.c

@@ -18,6 +18,7 @@
 // <bcoles@gmail.com>
 
 #include "include/kasld/api.h"
+#include "include/kasld/cli.h"
 #include "include/kconfig.h"
 #include <errno.h>
 #include <stdio.h>
@@ -66,7 +67,7 @@ static int open_boot_config(FILE **fpp) {
       return 0;
   }
 
-  fprintf(stderr, "[-] could not find kernel config\n");
+  kasld_err("could not find kernel config");
   return -1;
 }
 
@@ -89,7 +90,7 @@ int main(void) {
   /* Detect PAGE_OFFSET (32-bit vmsplit) */
   unsigned long virt_page_offset = get_kconfig_page_offset(fp);
   if (virt_page_offset) {
-    printf("[.] CONFIG_PAGE_OFFSET: %#lx\n", virt_page_offset);
+    kasld_info("CONFIG_PAGE_OFFSET: %#lx", virt_page_offset);
     kasld_result_base(KASLD_TYPE_VIRT, REGION_PAGE_OFFSET, virt_page_offset,
                       NULL, CONF_PARSED);
   }
@@ -101,7 +102,7 @@ int main(void) {
    * raises the floor to the precise position at CONF_PARSED. */
   unsigned long phys_start = get_kconfig_physical_start(fp);
   if (phys_start) {
-    printf("[.] CONFIG_PHYSICAL_START: %#lx\n", phys_start);
+    kasld_info("CONFIG_PHYSICAL_START: %#lx", phys_start);
     kasld_emit_scalar(SF_PHYSICAL_START, phys_start, CONF_PARSED);
   }
 
@@ -112,7 +113,7 @@ int main(void) {
    * Q_KASLR_ALIGN / Q_PHYS_KASLR_ALIGN regardless of source. */
   unsigned long phys_align = get_kconfig_physical_align(fp);
   if (phys_align) {
-    printf("[.] CONFIG_PHYSICAL_ALIGN: %#lx\n", phys_align);
+    kasld_info("CONFIG_PHYSICAL_ALIGN: %#lx", phys_align);
     kasld_emit_scalar(SF_PHYS_KERNEL_ALIGN, phys_align, CONF_PARSED);
   }
 
@@ -133,7 +134,7 @@ int main(void) {
    * with CONFIG_RANDOMIZE_MEMORY=y. Consumed by directmap_kaslr_disabled_pin.
    */
   if (is_kconfig_set(fp, "CONFIG_KASAN")) {
-    printf("[.] CONFIG_KASAN=y\n");
+    kasld_info("CONFIG_KASAN=y");
     kasld_emit_scalar(SF_KASAN_ENABLED, 1, CONF_PARSED);
   }
 

src/components/boot_params_e820.c

@@ -59,6 +59,7 @@
 
 #define _POSIX_C_SOURCE 200809L
 #include "include/kasld/api.h"
+#include "include/kasld/cli.h"
 #include <errno.h>
 #include <fcntl.h>
 #include <stdint.h>
@@ -127,8 +128,8 @@ static inline uint64_t read_le64(const uint8_t *p) {
 int main(void) {
   static uint8_t buf[BOOT_PARAMS_SIZE];
 
-  printf("[.] reading E820 memory map and initrd address from " BOOT_PARAMS_PATH
-         " ...\n");
+  kasld_info("reading E820 memory map and initrd address from " BOOT_PARAMS_PATH
+             " ...");
 
   int fd = kasld_open(BOOT_PARAMS_PATH, O_RDONLY);
   if (fd < 0) {
@@ -143,9 +144,8 @@ int main(void) {
   close(fd);
 
   if (n != (ssize_t)sizeof(buf)) {
-    fprintf(stderr,
-            "[-] short read from " BOOT_PARAMS_PATH " (%zd of %u bytes)\n", n,
-            BOOT_PARAMS_SIZE);
+    kasld_err("short read from " BOOT_PARAMS_PATH " (%zd of %u bytes)", n,
+              BOOT_PARAMS_SIZE);
     return KASLD_EXIT_UNAVAILABLE;
   }
 
@@ -159,7 +159,7 @@ int main(void) {
     e820_entries = E820_MAX_ENTRIES;
 
   if (e820_entries == 0) {
-    printf("[-] E820 table is empty\n");
+    kasld_err("E820 table is empty");
   } else {
     unsigned long lo = ~0ul;
     unsigned long hi = 0;
@@ -193,7 +193,7 @@ int main(void) {
     }
 
     if (ram_count == 0) {
-      printf("[-] no E820 RAM entries found\n");
+      kasld_err("no E820 RAM entries found");
     } else {
       if (lo != ~0ul) {
         printf("leaked E820 DRAM low:  0x%016lx\n", lo);
@@ -243,7 +243,7 @@ int main(void) {
   uint64_t initrd_size = ((uint64_t)hi_sz << 32) | lo_sz;
 
   if (!initrd_start || !initrd_size) {
-    printf("[-] no initrd found in boot_params\n");
+    kasld_err("no initrd found in boot_params");
     return 0;
   }
 

src/components/cmdline_hugepages.c

@@ -22,6 +22,7 @@
 
 #include "include/cmdline.h"
 #include "include/kasld/api.h"
+#include "include/kasld/cli.h"
 #include <stdio.h>
 
 KASLD_EXPLAIN(
@@ -38,10 +39,10 @@ KASLD_META("method:detection\n"
 int main(void) {
 #if defined(__x86_64__) || defined(__i386__)
   if (!cmdline_has_prefix("hugepages=")) {
-    fprintf(stderr, "[-] no `hugepages=` on /proc/cmdline\n");
+    kasld_err("no `hugepages=` on /proc/cmdline");
     return 1;
   }
-  printf("[.] cmdline carries `hugepages=` (EFI stub will zero phys seed)\n");
+  kasld_info("cmdline carries `hugepages=` (EFI stub will zero phys seed)");
   kasld_emit_scalar(SF_CMDLINE_HUGEPAGES, 1, CONF_PARSED);
 #endif
   return 0;

src/components/cmdline_mem.c

@@ -27,6 +27,7 @@
 
 #include "include/cmdline.h"
 #include "include/kasld/api.h"
+#include "include/kasld/cli.h"
 #include <stdio.h>
 
 KASLD_EXPLAIN(
@@ -45,10 +46,10 @@ int main(void) {
 #if defined(__x86_64__) || defined(__i386__)
   unsigned long mem = 0;
   if (!cmdline_get_memparse("mem=", &mem) || mem == 0) {
-    fprintf(stderr, "[-] no `mem=` token on /proc/cmdline\n");
+    kasld_err("no `mem=` token on /proc/cmdline");
     return 1;
   }
-  printf("[.] cmdline mem= cap: %#lx (%lu bytes)\n", mem, mem);
+  kasld_info("cmdline mem= cap: %#lx (%lu bytes)", mem, mem);
   kasld_emit_scalar(SF_PHYS_CMDLINE_MEM, mem, CONF_PARSED);
 #endif
   /* Other arches: emit nothing (mem= does not constrain KASLR placement). */

src/components/cmdline_memmap.c

@@ -36,6 +36,7 @@
 
 #include "include/cmdline.h"
 #include "include/kasld/api.h"
+#include "include/kasld/cli.h"
 #include <stdio.h>
 
 KASLD_EXPLAIN(
@@ -82,7 +83,7 @@ int main(void) {
 #if defined(__x86_64__) || defined(__i386__)
   FILE *f = kasld_fopen("/proc/cmdline", "r");
   if (!f) {
-    fprintf(stderr, "[-] /proc/cmdline unavailable\n");
+    kasld_err("/proc/cmdline unavailable");
     return 1;
   }
   char buf[2048];
@@ -108,7 +109,7 @@ int main(void) {
         if (is_avoid) {
           char name[16];
           snprintf(name, sizeof(name), "memmap%c", sep);
-          printf("[.] cmdline %s -> [%#lx, %#lx]\n", name, lo, hi);
+          kasld_info("cmdline %s -> [%#lx, %#lx]", name, lo, hi);
           kasld_result_range(KASLD_TYPE_PHYS, REGION_CMDLINE_MEMMAP, lo, hi,
                              name, CONF_PARSED);
           emitted_avoid++;
@@ -124,7 +125,7 @@ int main(void) {
   if (with_offset > 0)
     kasld_emit_scalar(SF_CMDLINE_MEMMAP_COUNT, with_offset, CONF_PARSED);
   if (emitted_avoid == 0 && with_offset == 0)
-    fprintf(stderr, "[-] no avoidance `memmap=` reservations on cmdline\n");
+    kasld_err("no avoidance `memmap=` reservations on cmdline");
 #endif
   /* Other arches: emit nothing. */
   return 0;

src/components/dmesg_acpi_dynamic_ssdt.c

@@ -64,6 +64,7 @@
 #define _GNU_SOURCE
 #include "include/dmesg.h"
 #include "include/kasld/api.h"
+#include "include/kasld/cli.h"
 #include <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -144,12 +145,12 @@ static int on_match(const char *line, void *ctx) {
 int main(void) {
   struct ssdt_ctx s = {0, {0}};
 
-  printf("[.] searching dmesg for ACPI dynamic OEM table loads ...\n");
+  kasld_info("searching dmesg for ACPI dynamic OEM table loads ...");
   int ds = dmesg_search("ACPI: SSDT 0x", on_match, &s);
 
   if (!s.addr) {
-    printf("[-] no ACPI dynamic OEM table load with a direct-map virtual "
-           "address found in dmesg\n");
+    kasld_err("no ACPI dynamic OEM table load with a direct-map virtual "
+              "address found in dmesg");
     if (ds < 0)
       return KASLD_EXIT_NOPERM;
     return 0;

src/components/dmesg_android_ion_snapshot.c

@@ -38,6 +38,7 @@
 #define _GNU_SOURCE
 #include "include/dmesg.h"
 #include "include/kasld/api.h"
+#include "include/kasld/cli.h"
 #include <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -79,13 +80,13 @@ static int on_match(const char *line, void *ctx) {
 int main(void) {
   unsigned long addr = 0;
 
-  printf("[.] searching dmesg for 'ion_snapshot: ' ...\n");
+  kasld_info("searching dmesg for 'ion_snapshot: ' ...");
   int ds = dmesg_search("ion_snapshot: ", on_match, &addr);
 
   if (!addr) {
     if (ds < 0)
       return KASLD_EXIT_NOPERM;
-    printf("[-] ion_snapshot not found in dmesg\n");
+    kasld_err("ion_snapshot not found in dmesg");
     return 0;
   }