Phase 1: module interface + registry + top-level dispatcher

- core/module.h: struct iamroot_module + iamroot_result_t
- core/registry.{h,c}: flat-array module registry with find-by-name
- modules/copy_fail_family/iamroot_modules.{h,c}: bridge layer
  exposing 5 modules (copy_fail, copy_fail_gcm, dirty_frag_esp,
  dirty_frag_esp6, dirty_frag_rxrpc) wired to the absorbed DIRTYFAIL
  detect/exploit functions; df_result_t/iamroot_result_t share numeric
  values intentionally for zero-cost translation
- iamroot.c: top-level CLI dispatcher with --scan / --list / --exploit /
  --mitigate / --cleanup, JSON output, --i-know gate
- Restored modules/copy_fail_family/src/ structure (DIRTYFAIL Makefile
  expects it; the initial flat copy broke that contract)
- Top-level Makefile builds one binary; filters out DIRTYFAIL's
  original dirtyfail.c main so it doesn't conflict with iamroot.c

Verified end-to-end on kctf-mgr (Linux): clean compile, 5 modules
register, --scan --json output ingest-ready, exit codes propagate.

core/module.h

@@ -0,0 +1,89 @@
+/*
+ * IAMROOT — core module interface
+ *
+ * Every CVE module exports one or more `struct iamroot_module` entries
+ * via a registry function. The top-level dispatcher (iamroot.c) walks
+ * the global registry to implement --scan, --exploit, --mitigate, etc.
+ *
+ * This is intentionally a small interface. Modules carry the
+ * complexity; the dispatcher just routes.
+ */
+
+#ifndef IAMROOT_MODULE_H
+#define IAMROOT_MODULE_H
+
+#include <stddef.h>
+#include <stdbool.h>
+
+/* Standard result codes returned by detect()/exploit()/mitigate().
+ *
+ * These map to top-level exit codes when iamroot is invoked with a
+ * single-module operation:
+ *
+ *   IAMROOT_OK            exit 0   detect: not vulnerable / clean
+ *   IAMROOT_VULNERABLE    exit 2   detect: confirmed vulnerable
+ *   IAMROOT_PRECOND_FAIL  exit 4   detect: preconditions missing
+ *   IAMROOT_TEST_ERROR    exit 1   detect/exploit: error
+ *   IAMROOT_EXPLOIT_OK    exit 5   exploit: succeeded (root achieved)
+ *   IAMROOT_EXPLOIT_FAIL  exit 3   exploit: attempted but did not land
+ *
+ * Implementation note: copy_fail_family's df_result_t shares these
+ * numeric values intentionally so the family code can return its
+ * existing constants without translation.
+ */
+typedef enum {
+    IAMROOT_OK              = 0,
+    IAMROOT_TEST_ERROR      = 1,
+    IAMROOT_VULNERABLE      = 2,
+    IAMROOT_EXPLOIT_FAIL    = 3,
+    IAMROOT_PRECOND_FAIL    = 4,
+    IAMROOT_EXPLOIT_OK      = 5,
+} iamroot_result_t;
+
+/* Per-invocation context passed to module callbacks. Lightweight for
+ * now; will grow as modules need shared state (host fingerprint,
+ * leaked kbase, etc.). */
+struct iamroot_ctx {
+    bool          no_color;     /* --no-color */
+    bool          json;         /* --json (machine-readable output) */
+    bool          active_probe; /* --active (do invasive probes in detect) */
+    bool          no_shell;     /* --no-shell (exploit prep but don't pop) */
+    bool          authorized;   /* user typed --i-know on exploit */
+};
+
+struct iamroot_module {
+    /* Short id used on the command line: `iamroot --exploit copy_fail`. */
+    const char *name;
+
+    /* CVE identifier (or "VARIANT" if no CVE assigned). */
+    const char *cve;
+
+    /* One-line human description. */
+    const char *summary;
+
+    /* Family this module belongs to (e.g. "copy_fail_family"). Modules
+     * with shared infrastructure live in the same family. */
+    const char *family;
+
+    /* Affected kernel range, prose. Machine-readable range goes in
+     * the module's kernel-range.json (consumed by CI). */
+    const char *kernel_range;
+
+    /* Probe the host. Should be side-effect-free unless ctx->active_probe
+     * is true. Return IAMROOT_VULNERABLE if confirmed,
+     * IAMROOT_PRECOND_FAIL if not applicable here, IAMROOT_OK if patched
+     * or otherwise immune, IAMROOT_TEST_ERROR on probe error. */
+    iamroot_result_t (*detect)(const struct iamroot_ctx *ctx);
+
+    /* Run the exploit. Caller has already passed the --i-know gate. */
+    iamroot_result_t (*exploit)(const struct iamroot_ctx *ctx);
+
+    /* Apply a temporary mitigation. NULL if none offered. */
+    iamroot_result_t (*mitigate)(const struct iamroot_ctx *ctx);
+
+    /* Undo --exploit (e.g. evict from page cache) or --mitigate side
+     * effects. NULL if no cleanup applies. */
+    iamroot_result_t (*cleanup)(const struct iamroot_ctx *ctx);
+};
+
+#endif /* IAMROOT_MODULE_H */

core/registry.c

@@ -0,0 +1,60 @@
+/*
+ * IAMROOT — module registry implementation
+ *
+ * Simple flat array. Resized in chunks of 16. We never expect more
+ * than a few dozen modules, so this is fine.
+ */
+
+#include "registry.h"
+
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define REGISTRY_CHUNK 16
+
+static const struct iamroot_module **g_modules = NULL;
+static size_t g_count = 0;
+static size_t g_cap = 0;
+
+void iamroot_register(const struct iamroot_module *m)
+{
+    if (m == NULL || m->name == NULL) {
+        fprintf(stderr, "[!] iamroot_register: NULL module or unnamed module\n");
+        return;
+    }
+    if (g_count == g_cap) {
+        size_t new_cap = g_cap + REGISTRY_CHUNK;
+        const struct iamroot_module **n =
+            realloc((void *)g_modules, new_cap * sizeof(*g_modules));
+        if (n == NULL) {
+            fprintf(stderr, "[!] iamroot_register: OOM\n");
+            return;
+        }
+        g_modules = n;
+        g_cap = new_cap;
+    }
+    g_modules[g_count++] = m;
+}
+
+size_t iamroot_module_count(void)
+{
+    return g_count;
+}
+
+const struct iamroot_module *iamroot_module_at(size_t i)
+{
+    if (i >= g_count) return NULL;
+    return g_modules[i];
+}
+
+const struct iamroot_module *iamroot_module_find(const char *name)
+{
+    if (name == NULL) return NULL;
+    for (size_t i = 0; i < g_count; i++) {
+        if (strcmp(g_modules[i]->name, name) == 0)
+            return g_modules[i];
+    }
+    return NULL;
+}

core/registry.h

@@ -0,0 +1,25 @@
+/*
+ * IAMROOT — module registry
+ *
+ * Global list of registered modules. Each family contributes via
+ * register_<family>_modules() called from iamroot main() at startup.
+ */
+
+#ifndef IAMROOT_REGISTRY_H
+#define IAMROOT_REGISTRY_H
+
+#include "module.h"
+
+void iamroot_register(const struct iamroot_module *m);
+
+size_t iamroot_module_count(void);
+const struct iamroot_module *iamroot_module_at(size_t i);
+
+/* Find a module by name. Returns NULL if not found. */
+const struct iamroot_module *iamroot_module_find(const char *name);
+
+/* Each module family declares one of these in its public header. The
+ * top-level iamroot main() calls them in order at startup. */
+void iamroot_register_copy_fail_family(void);
+
+#endif /* IAMROOT_REGISTRY_H */