@blamejs/exceptd-skills 0.13.32 → 0.13.34

package/AGENTS.md

@@ -362,6 +362,44 @@ Maintainers convert approved requests into skill files. The contributor is credi
 
 ---
 
+## Evidence collection roadmap
+
+Today every playbook declares **what** evidence its detect phase needs via `phases.look.artifacts[].source` — a prose-shaped string that an AI assistant (or operator) reads, interprets, and translates into a concrete filesystem walk / shell command / API call. exceptd ships the knowledge layer; evidence collection lives in the consumer.
+
+This split costs every consumer the same translation work on every invocation. CI is the most visible place that hurts (no human-in-loop), but every AI-driven workflow pays the cost on every run. The longer-term direction is **companion collector scripts** under `lib/collectors/<playbook-id>.js` that turn the prose into executable Node — pure stdlib walks + regex + child_process where needed — emitting the evidence JSON in the same shape `exceptd run --evidence -` accepts. The wrapper verb is `exceptd collect <playbook>`; the operator pipes:
+
+```bash
+exceptd collect secrets | exceptd run secrets --evidence -
+```
+
+The collector library is small and grows as playbooks are touched. Three reference collectors ship today (`lib/collectors/secrets.js`, `lib/collectors/kernel.js`, `lib/collectors/sbom.js`); the rest are written when each playbook needs them. Until a playbook has a collector, the AI/operator owns evidence collection as before.
+
+### Precision target for new `look.artifacts[].source` strings
+
+When adding or editing a playbook artifact, treat the `source` string as **the spec a future collector will implement against**. Write it precise enough that an attentive script author could turn it into Node code without guessing. Concretely:
+
+- **File-based artifacts** name explicit globs (`*.tf, *.tfvars, *.tfvars.json`) plus exclusion list when relevant (`exclude **/node_modules/**, **/.git/objects/**, **/dist/**, **/build/**`). Avoid open-ended phrasing like "common config files".
+- **Filesystem-walk artifacts** declare the walk root (cwd, `~`, an explicit path), depth limit if any, and the predicate shape (filename match, content match, permission check, symlink resolution policy).
+- **Command-driven artifacts** name the exact command per platform when the call varies (`AWS: aws iam ... ; GCP: gcloud ... ; Azure: az ...`). The current cloud-incident playbooks follow this pattern; copy that shape.
+- **Regex / content matching** — the canonical pattern lives in the detect phase's `indicators[].value` field, not in the artifact `source`. Reference it explicitly (`grep against the catalogued secret patterns — see detect.indicators for the regex set`) so the collector knows where to read the patterns from.
+- **Aggregations of other artifacts** name the input artifact IDs explicitly (`For every file matched by env-files OR auth-config-files OR ssh-private-keys: stat for ...`). The collector composes per-artifact outputs.
+
+When a `source` string would otherwise drift into prose ("the operator should consider…", "typically located in…"), the artifact is probably under-specified. Tighten it before merging.
+
+### When a collector is required vs optional
+
+For now, collectors are optional — every playbook still works through the AI-evidence path. A new playbook **must** carry a collector when:
+
+- It's a code-scope or system-scope playbook with a deterministic detect-phase regex / filesystem-walk shape (the kind a CI pipeline would gate on).
+- The cost of writing the collector is bounded (≤300 lines of Node, stdlib + child_process only).
+
+A new playbook **should not** ship a collector when:
+
+- The detect phase requires operator judgement (`framework`, `ransomware`, jurisdiction-specific incident playbooks where the inputs are interview-shaped).
+- Evidence collection requires credentials the tool shouldn't ask for (cloud API keys, identity-provider admin tokens). Those stay AI-driven for now.
+
+When in doubt, ship the playbook without a collector and open the gap as a follow-up.
+
 ## Pre-Ship Checklist
 
 - [ ] All new CVEs have complete `data/cve-catalog.json` entries
@@ -379,6 +417,8 @@ Maintainers convert approved requests into skill files. The contributor is credi
 - [ ] CHANGELOG.md updated with what changed, what CVEs were added, what gaps were closed or opened
 - [ ] No partial skills — if it can't be completed now, branch it, don't merge it
 - [ ] Global coverage: EU + UK + AU + ISO 27001 present in all framework gap analyses
+- [ ] `look.artifacts[].source` strings meet the precision target (see § Evidence collection roadmap). New artifacts ship globs / commands / artifact-id references — not prose like "typically located in" or "the operator should consider"
+- [ ] When the playbook is code-scope or system-scope with a deterministic detect shape: a companion collector exists at `lib/collectors/<playbook-id>.js` and runs clean via `exceptd collect <id> | exceptd run <id> --evidence -`
 
 ---
 

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.13.34 — 2026-05-20
+
+Evidence-collection layer (Option A from the cold-start workflow audit). New verb `exceptd collect <playbook>` runs a companion script per playbook that walks the cwd, applies the catalogued regex set, stats permissions, and emits the submission JSON in the same shape `exceptd run --evidence -` accepts. The operator pipes:
+
+```bash
+exceptd collect secrets | exceptd run secrets --evidence -
+```
+
+The collector library is small and grows as playbooks are touched.
+
+### Features
+
+- **New verb `exceptd collect <playbook>`.** Loads `lib/collectors/<playbook>.js`, runs `collect({ cwd, env, args })`, emits the submission JSON. `--cwd <path>` collects against a different repo / host. `--pretty` for indented JSON. Default output is a one-screen human digest (preconditions / artifacts / indicators-that-fired / collector warnings / next-step pipe pointer); `--json` for machine consumption. Exit codes: `0` ok, `1` collector-not-found (the AI-evidence path remains — `exceptd lint <pb> -` documents the submission shape), `2` collector threw unhandled.
+- **Three reference collectors ship.** `lib/collectors/secrets.js` walks the cwd tree (depth 6, exclude `node_modules`/`.git`/`dist`/`build`/etc.), runs the catalogued secret regex set against text files (with literal-redaction so the attestation doesn't become a leak vector), stats permission posture on secret-carrier files, and flips `signal_overrides` per indicator that fired. `lib/collectors/kernel.js` derives the `linux-platform` + `uname-available` preconditions, captures `uname -r` + `/proc/cmdline` + selected `/proc/sys/kernel/*` snapshots, and flips `kaslr-disabled` / `unpriv-userns-enabled` / `unpriv-bpf-allowed` from the sysctl values. `lib/collectors/sbom.js` recognises 10 lockfile types (npm / yarn / pnpm / pip / pipenv / poetry / cargo / go / rubygems / composer) plus CycloneDX / SPDX SBOM documents and flips `sbom-document-absent` / `lockfile-absent`.
+- **Collector contract codified at `lib/collectors/README.md`.** Pure stdlib + child_process only, synchronous, errors don't throw (surfaced via `collector_errors[]`), literal secret bytes redacted in artifact values, indicators win over artifacts when the collector can decide deterministically.
+
+### Internal
+
+- `AGENTS.md` § Evidence collection roadmap documents the WHY + the precision target for `look.artifacts[].source` strings (file globs + per-platform commands + artifact-id references — not prose) and the when-required policy for adding a collector with a new playbook.
+
+## 0.13.33 — 2026-05-20
+
+### Features
+
+- **`brief` (no arg) renders a scannable per-scope table.** `exceptd brief` with no playbook positional and no `--all` flag now produces a one-screen human digest: header with playbook count + session id, per-scope summary (`service=9  cross-cutting=4  code=4  system=6`), then a bucketed list per scope showing `<id>  tcs=<score>  <domain.name (truncated to 80 chars)>`, then a `Next:` block pointing at `brief <playbook>` for the full info doc, `discover` for cwd-aware recommendations, and `ci --scope <type>` for gating. Previously the verb dumped 36+ KB of JSON to the terminal — exploration was unscannable. `--json` / `--pretty` reach the structured envelope when automating.
+
 ## 0.13.32 — 2026-05-20
 
 Two more JSON-only paths get human-renderer treatment.

package/bin/exceptd.js

@@ -217,7 +217,7 @@ function suggestVerb(cmd, known) {
 // remain operationally useful and have substantial test coverage.
 const PLAYBOOK_VERBS = new Set([
   "brief", "run", "ai-run", "attest", "discover", "doctor", "ci", "ask",
-  "verify-attestation", "run-all", "lint",
+  "verify-attestation", "run-all", "lint", "collect",
   "reattest", "list-attestations",
 ]);
 
@@ -1151,6 +1151,7 @@ function dispatchPlaybook(cmd, argv) {
     "evidence", "evidence-dir", "session-id", "operator", "csaf-status",
     "publisher-namespace", "mode", "scope", "playbook", "phase", "tlp",
     "against", "since", "bundle-epoch", "attestation-root", "format",
+    "cwd",  // exceptd collect <pb> --cwd <path>
   ]);
   const verbAllowlist = flagsFor(cmd);
   const allowlistSet = new Set(verbAllowlist);
@@ -1576,6 +1577,7 @@ function dispatchPlaybook(cmd, argv) {
       case "ai-run": return cmdAiRun(runner, args, runOpts, pretty);
       case "ask":    return cmdAsk(runner, args, runOpts, pretty);
       case "ci":     return cmdCi(runner, args, runOpts, pretty);
+      case "collect": return cmdCollect(runner, args, runOpts, pretty);
     }
   } catch (e) {
     // v0.11.14 (#131): when the operator typed a skill name (kernel-lpe-triage)
@@ -2181,6 +2183,119 @@ Flags (selected — see \`exceptd run --help\` for the full list):
  * its evidence JSON before going through phases 4-7. Returns a categorized
  * list: ok / missing_required / unknown_keys / type_mismatch / suggestions.
  */
+function cmdCollect(runner, args, runOpts, pretty) {
+  const playbookId = args._[0];
+  if (!playbookId) {
+    return emitError("collect: usage: exceptd collect <playbook>. See `lib/collectors/` for the list of playbooks with companion collectors.", null, pretty);
+  }
+  if (refuseInvalidPlaybookId("collect", playbookId, pretty)) return;
+
+  // Resolve the collector module under lib/collectors/<id>.js.
+  const collectorPath = path.join(PKG_ROOT, "lib", "collectors", `${playbookId}.js`);
+  if (!fs.existsSync(collectorPath)) {
+    const collectorsDir = path.join(PKG_ROOT, "lib", "collectors");
+    let available = [];
+    try {
+      available = fs.readdirSync(collectorsDir)
+        .filter(f => f.endsWith(".js"))
+        .map(f => f.replace(/\.js$/, ""));
+    } catch {}
+    return emitError(
+      `collect: no companion collector for "${playbookId}". The AI-evidence path remains: see \`exceptd lint ${playbookId} -\` for the submission shape and supply your own evidence to \`exceptd run ${playbookId} --evidence -\`.`,
+      {
+        verb: "collect",
+        playbook_id: playbookId,
+        collectors_available: available,
+        type: "collector_not_found",
+        exit_code: 1,
+      },
+      pretty
+    );
+  }
+
+  let mod;
+  try { mod = require(collectorPath); }
+  catch (e) {
+    return emitError(`collect: failed to load collector ${path.relative(PKG_ROOT, collectorPath)}: ${e.message}`, { verb: "collect", playbook_id: playbookId, exit_code: 2 }, pretty);
+  }
+  if (typeof mod.collect !== "function") {
+    return emitError(`collect: collector at ${path.relative(PKG_ROOT, collectorPath)} does not export a collect() function`, { verb: "collect", playbook_id: playbookId, exit_code: 2 }, pretty);
+  }
+
+  // --cwd <path> overrides process.cwd(). Validated as an existing
+  // directory; non-existent / non-directory cwd is operator error.
+  let cwd = process.cwd();
+  if (args.cwd) {
+    const resolved = path.resolve(String(args.cwd));
+    let stat;
+    try { stat = fs.statSync(resolved); }
+    catch (e) {
+      return emitError(`collect: --cwd "${args.cwd}" does not exist (${e.message})`, { verb: "collect", playbook_id: playbookId, provided_cwd: args.cwd }, pretty);
+    }
+    if (!stat.isDirectory()) {
+      return emitError(`collect: --cwd "${args.cwd}" is not a directory`, { verb: "collect", playbook_id: playbookId, provided_cwd: args.cwd }, pretty);
+    }
+    cwd = resolved;
+  }
+
+  let submission;
+  try {
+    submission = mod.collect({ cwd, env: process.env, args });
+  } catch (e) {
+    return emitError(
+      `collect: collector for "${playbookId}" threw an unhandled exception: ${e.message}. File a bug — collectors must catch their own errors and surface them via collector_errors[].`,
+      { verb: "collect", playbook_id: playbookId, stack: e.stack || null, exit_code: 2 },
+      pretty
+    );
+  }
+
+  // Emit the submission JSON to stdout. The operator pipes this into
+  // `exceptd run <playbook> --evidence -` to drive a real verdict.
+  // Human-rendered version is concise so an interactive operator can
+  // see what the collector found without parsing the JSON.
+  emit({ verb: "collect", playbook_id: playbookId, ...submission }, pretty, (obj) => {
+    const lines = [];
+    const meta = obj.collector_meta || {};
+    lines.push(`collect: ${obj.playbook_id}  (${meta.collector_version || "?"} on ${meta.platform || "?"})`);
+    if (meta.duration_ms != null) lines.push(`  duration: ${meta.duration_ms}ms`);
+    const pre = obj.precondition_checks || {};
+    if (Object.keys(pre).length) {
+      lines.push(`\nPreconditions:`);
+      for (const [k, v] of Object.entries(pre)) {
+        const icon = v ? "[ok]" : "[!!]";
+        lines.push(`  ${icon} ${k} = ${v}`);
+      }
+    }
+    const artifacts = obj.artifacts || {};
+    if (Object.keys(artifacts).length) {
+      lines.push(`\nArtifacts:`);
+      for (const [k, a] of Object.entries(artifacts)) {
+        const icon = a.captured ? "[ok]" : "[skip]";
+        const val = (a.value || "").length > 120 ? (a.value || "").slice(0, 117) + "..." : (a.value || "");
+        lines.push(`  ${icon} ${k}: ${val}`);
+        if (!a.captured && a.reason) lines.push(`         reason: ${a.reason}`);
+      }
+    }
+    const signals = obj.signal_overrides || {};
+    const hits = Object.entries(signals).filter(([, v]) => v === "hit");
+    if (hits.length) {
+      lines.push(`\nIndicators that fired (${hits.length}):`);
+      for (const [k] of hits) lines.push(`  [hit]  ${k}`);
+    }
+    const errs = obj.collector_errors || [];
+    if (errs.length) {
+      lines.push(`\nCollector warnings (${errs.length}):`);
+      for (const e of errs.slice(0, 5)) {
+        lines.push(`  [${e.kind || "warning"}] ${e.artifact_id ? e.artifact_id + ": " : ""}${e.reason || "(no detail)"}`);
+      }
+      if (errs.length > 5) lines.push(`  … ${errs.length - 5} more`);
+    }
+    lines.push(`\n→ next: exceptd collect ${obj.playbook_id} --json | exceptd run ${obj.playbook_id} --evidence -`);
+    lines.push(`Full structured result: --json (or --pretty for indented JSON).`);
+    return lines.join("\n");
+  });
+}
+
 function cmdLint(runner, args, runOpts, pretty) {
   const playbookId = args._[0];
   const evidencePath = args._[1] || args.evidence;
@@ -2504,7 +2619,85 @@ function cmdPlan(runner, args, runOpts, pretty) {
       });
     }
   }
-  emit(plan, pretty);
+  emit(plan, pretty, (obj) => {
+    // Human renderer for `brief` / `brief --all` / `plan`. Pre-fix this
+    // verb dumped 36+ KB of JSON to the terminal — operators running
+    // `exceptd brief` to explore had no scannable view.
+    const lines = [];
+    const summary = obj.scope_summary || {};
+    const totalScope = Object.values(summary).reduce((a, b) => a + b, 0);
+    const total = obj.playbooks?.length || 0;
+    lines.push(`brief: ${total} playbook(s)  session-id: ${obj.session_id}`);
+    if (totalScope > 0) {
+      const scopeLine = Object.entries(summary).map(([s, n]) => `${s}=${n}`).join("  ");
+      lines.push(`  ${scopeLine}`);
+    }
+    lines.push("");
+
+    // Group by scope when grouped output is available; else flat list.
+    // grouped_by_scope is `{ scope: [<playbook-id>, ...] }` — look up
+    // domain.name + threat_currency_score from the flat playbooks list.
+    const byId = {};
+    for (const pb of obj.playbooks || []) {
+      if (pb && pb.id) byId[pb.id] = pb;
+    }
+    // Render directive sub-bullets when each playbook entry carries a
+    // directives[] array (set by cmdPlan when --directives is on).
+    // Without this, the documented contract of --directives — expand
+    // directive metadata — is silently dropped in default human mode.
+    const renderDirectives = (pb) => {
+      const dirs = pb && Array.isArray(pb.directives) ? pb.directives : null;
+      if (!dirs || !dirs.length) return;
+      for (const d of dirs) {
+        const title = d.title || d.id || "?";
+        const truncTitle = title.length > 80 ? title.slice(0, 77) + "..." : title;
+        lines.push(`      → ${(d.id || "?").padEnd(48)}  ${truncTitle}`);
+        if (d.threat_context_preview) {
+          const ctx = d.threat_context_preview;
+          const truncCtx = ctx.length > 140 ? ctx.slice(0, 137) + "..." : ctx;
+          lines.push(`        ${truncCtx}`);
+        }
+      }
+    };
+
+    const grouped = obj.grouped_by_scope;
+    if (grouped) {
+      const scopeOrder = ["code", "system", "service", "cross-cutting"];
+      const otherScopes = Object.keys(grouped).filter(s => !scopeOrder.includes(s));
+      for (const scope of [...scopeOrder, ...otherScopes]) {
+        const list = grouped[scope];
+        if (!list || !list.length) continue;
+        lines.push(`[${scope}]  (${list.length})`);
+        for (const id of list) {
+          const pb = byId[id] || {};
+          const tcs = pb.threat_currency_score != null ? ` tcs=${pb.threat_currency_score}` : "";
+          const dom = pb.domain?.name || "";
+          const truncDom = dom.length > 80 ? dom.slice(0, 77) + "..." : dom;
+          lines.push(`  ${(id || "?").padEnd(28)}${tcs.padEnd(8)}  ${truncDom}`);
+          renderDirectives(pb);
+        }
+        lines.push("");
+      }
+    } else {
+      // Flat list (filtered or --flat). No scope buckets.
+      for (const pb of obj.playbooks || []) {
+        const tcs = pb.threat_currency_score != null ? ` tcs=${pb.threat_currency_score}` : "";
+        const sc = pb.scope ? `[${pb.scope}]` : "[?]";
+        const dom = pb.domain?.name || "";
+        const truncDom = dom.length > 80 ? dom.slice(0, 77) + "..." : dom;
+        lines.push(`  ${sc.padEnd(16)} ${(pb.id || "?").padEnd(28)}${tcs.padEnd(8)}  ${truncDom}`);
+        renderDirectives(pb);
+      }
+      lines.push("");
+    }
+
+    lines.push(`Next:`);
+    lines.push(`  exceptd brief <playbook>          # full info doc (jurisdictions + threat + indicators + artifacts)`);
+    lines.push(`  exceptd discover                  # cwd-aware playbook recommendations`);
+    lines.push(`  exceptd ci --scope <type>         # gate a cwd against every playbook in <type>`);
+    lines.push(`\nFull structured result: --json (or --pretty for indented JSON).`);
+    return lines.join("\n");
+  });
 }
 
 // v0.12.15: --scope must validate against the accepted

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-20T20:45:51.276Z",
+  "generated_at": "2026-05-20T23:16:10.900Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 54,
   "source_hashes": {
-    "manifest.json": "7fd55bae58a680322553f9c0c646c6a0a5308e306053d8116512582a14f47cf7",
+    "manifest.json": "d479c5acd441d98c8e4f75ab90366994affe4eea457f43b7180209f696af9ea2",
     "data/atlas-ttps.json": "d296c1d3e71807c9279b731f047e57796e85137f186586743a8cdad214b408f9",
     "data/attack-techniques.json": "49b6010b317edd219def135171ea8f3b1bbf1e00e9c5a08bf7237215ff54e2c3",
     "data/cve-catalog.json": "a09c83af3f9679a7ea73935726a1ff9de2cab94b4ab6321fc017fc147747d7c3",

package/lib/collectors/README.md

@@ -0,0 +1,76 @@
+# Evidence collectors
+
+Companion scripts that turn a playbook's `phases.look.artifacts[]` declarations into an actual evidence submission, so an operator (or a CI workflow) can produce a real verdict without a human-in-loop AI translating prose into filesystem walks every time.
+
+## Interface contract
+
+Each collector lives at `lib/collectors/<playbook-id>.js` and exports:
+
+```js
+module.exports = {
+  // Playbook id this collector implements. Must match the file name.
+  playbook_id: "<playbook-id>",
+
+  // Pure synchronous function. Walks the filesystem, runs child_process
+  // commands as needed, returns the submission JSON in the same shape
+  // `exceptd run --evidence -` accepts.
+  collect({ cwd, env, args }) {
+    return {
+      precondition_checks: { /* "<precondition-id>": true|false */ },
+      artifacts: {
+        /* "<artifact-id>": { value: <captured text>, captured: true|false, reason?: "<why captured=false>" } */
+      },
+      signal_overrides: { /* "<indicator-id>": "hit"|"miss"|"inconclusive" */ },
+      collector_meta: {
+        // Self-describing metadata so the operator knows WHAT the
+        // collector did and which version produced this evidence.
+        collector_id: "<playbook-id>",
+        collector_version: "<semver-or-date>",
+        platform: process.platform,
+        captured_at: new Date().toISOString(),
+        cwd: cwd,
+      },
+      // Collector-level errors that did NOT prevent producing a
+      // submission (e.g. "couldn't read /proc/version on Windows").
+      // Each entry is { artifact_id?, kind, reason }.
+      collector_errors: [],
+    };
+  },
+};
+```
+
+### Rules
+
+- **Stdlib + child_process only.** No npm dependencies beyond what's already vendored. The point is to ship inside the npm tarball and run anywhere Node runs.
+- **No network calls.** Evidence collection is a local snapshot. Refreshing upstream data lives in `exceptd refresh`.
+- **Synchronous.** Matches the rest of the bin/lib code shape. Async machinery would force colored functions through the runner.
+- **Errors don't throw.** Catch every recoverable error and add an entry to `collector_errors[]` with a human-readable `reason`. The CLI wrapper turns `collector_errors[]` into runtime warnings on the run output.
+- **Cwd is the only entry point.** Default `cwd` is `process.cwd()`. The operator can override via `exceptd collect <pb> --cwd <path>`.
+- **Walk caps.** Filesystem walks default to depth 6 + the standard exclusion set (`node_modules/`, `.git/objects/`, `dist/`, `build/`, `.venv/`, `__pycache__/`). Override the depth + exclusions via the playbook's `look.artifacts[].source` declaration when it says so.
+- **Don't leak secrets.** When an artifact captures file *contents* (e.g. the secret-regex-scan output), redact the matched literal in `value` — keep file path + offset + classifier, drop the actual key material. The point of the audit is finding the leak; persisting the leak in the attestation makes the attestation itself a leak vector.
+- **Indicators win over artifacts.** When the collector can determine an indicator verdict deterministically (e.g. a regex match means `aws-access-key-id: hit`), set the `signal_overrides[<indicator>]` rather than relying on the runner to re-evaluate the artifact text. Faster + more honest.
+
+## CLI
+
+```bash
+exceptd collect <playbook>                  # walk cwd, emit submission JSON to stdout
+exceptd collect <playbook> --cwd <path>     # collect against a different repo / host
+exceptd collect <playbook> --pretty         # indented JSON for the dev loop
+exceptd collect <playbook> | exceptd run <playbook> --evidence -   # full loop
+```
+
+Exit codes:
+
+- `0` — submission emitted successfully (operator should check `collector_errors[]` for partial-evidence warnings)
+- `1` — no collector exists for the playbook id (the AI-evidence path remains)
+- `2` — collector threw an unhandled exception (file a bug)
+
+## When to write a collector
+
+See `AGENTS.md § Evidence collection roadmap` for the policy. Summary: code-scope and system-scope playbooks with deterministic detect shapes are good candidates; judgement-shaped playbooks (`framework`, `ransomware`, incident playbooks) stay AI-driven.
+
+## Reference collectors
+
+- [`secrets.js`](secrets.js) — filesystem walk + regex against the catalogued secret patterns + permission-posture stat
+- [`kernel.js`](kernel.js) — `uname -s` / `uname -r` for linux-platform + kernel-release detection
+- [`sbom.js`](sbom.js) — lockfile presence + ecosystem fingerprint

package/lib/collectors/kernel.js

@@ -0,0 +1,159 @@
+"use strict";
+
+/**
+ * lib/collectors/kernel.js
+ *
+ * Companion collector for the `kernel` playbook. Establishes
+ * preconditions (linux-platform / uname-available) and captures the
+ * kernel release string for the kver-in-affected-range indicator.
+ *
+ * Scope: Linux only. On macOS / Windows the playbook's linux-platform
+ * precondition halts at preflight; the collector reports that
+ * truthfully so the operator sees the visibility gap without the
+ * runner having to re-derive it.
+ *
+ * Interface: see lib/collectors/README.md
+ */
+
+const { execFileSync } = require("node:child_process");
+const path = require("node:path");
+
+const COLLECTOR_ID = "kernel";
+
+function runUname(arg) {
+  try {
+    const out = execFileSync("uname", [arg], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000 });
+    return { ok: true, value: out.trim() };
+  } catch (e) {
+    return { ok: false, reason: (e && e.message) || String(e) };
+  }
+}
+
+function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
+  const errors = [];
+
+  // Precondition 1: linux-platform. Use process.platform first
+  // (Node-derived, always available); cross-check against uname -s
+  // when available.
+  const linuxPlatform = process.platform === "linux";
+
+  // Precondition 2: uname-available. Pure capability check.
+  const unameR = runUname("-r");
+  const unameAvailable = unameR.ok;
+  if (!unameAvailable && linuxPlatform) {
+    errors.push({
+      kind: "command_unavailable",
+      reason: `\`uname -r\` failed on linux: ${unameR.reason}`,
+    });
+  }
+
+  // Artifact: kernel-release. The exact string returned by `uname -r`,
+  // e.g. "5.15.0-69-generic". When uname is unavailable, the artifact
+  // is captured=false with the reason; the runner treats the
+  // dependent indicators as inconclusive.
+  const artifacts = {};
+  if (unameR.ok) {
+    artifacts["kernel-release"] = { value: unameR.value, captured: true };
+  } else {
+    artifacts["kernel-release"] = {
+      value: null,
+      captured: false,
+      reason: linuxPlatform
+        ? `uname -r failed: ${unameR.reason}`
+        : `non-linux platform (${process.platform}); uname not invoked`,
+    };
+  }
+
+  // Optional artifact: cmdline. Not always required but useful for
+  // KASLR / unpriv-userns / unpriv-bpf indicator evaluation. Read
+  // from /proc directly so we don't fork another process.
+  if (linuxPlatform) {
+    try {
+      const fs = require("node:fs");
+      const cmdline = fs.readFileSync("/proc/cmdline", "utf8").trim();
+      artifacts["kernel-cmdline"] = { value: cmdline, captured: true };
+    } catch (e) {
+      errors.push({
+        artifact_id: "kernel-cmdline",
+        kind: "read_failed",
+        reason: `/proc/cmdline read failed: ${e.message}`,
+      });
+    }
+    // sysctl snapshot for kernel.unprivileged_userns_clone +
+    // kernel.unprivileged_bpf_disabled when readable.
+    try {
+      const fs = require("node:fs");
+      const sysctls = {};
+      const paths = [
+        "/proc/sys/kernel/unprivileged_userns_clone",
+        "/proc/sys/kernel/unprivileged_bpf_disabled",
+        "/proc/sys/kernel/randomize_va_space",
+      ];
+      for (const p of paths) {
+        try {
+          sysctls[path.basename(p)] = fs.readFileSync(p, "utf8").trim();
+        } catch {
+          // Best-effort; a missing file usually means the sysctl
+          // doesn't exist on this kernel.
+        }
+      }
+      if (Object.keys(sysctls).length) {
+        artifacts["sysctl-snapshot"] = { value: JSON.stringify(sysctls), captured: true };
+      }
+    } catch (e) {
+      errors.push({
+        artifact_id: "sysctl-snapshot",
+        kind: "read_failed",
+        reason: e.message,
+      });
+    }
+  }
+
+  // Signal overrides: we can't decide kver-in-affected-range without
+  // the CVE-affected-version catalog (the runner does that
+  // correlation). But we CAN flip the deterministic indicators that
+  // read directly off the sysctl snapshot.
+  const signal_overrides = {};
+  const sysctl = artifacts["sysctl-snapshot"];
+  if (sysctl && sysctl.captured) {
+    let parsed = null;
+    try { parsed = JSON.parse(sysctl.value); } catch {}
+    if (parsed) {
+      // kaslr-disabled: randomize_va_space < 2 (0 = off, 1 = partial, 2 = full).
+      if (parsed.randomize_va_space != null) {
+        const v = parseInt(parsed.randomize_va_space, 10);
+        signal_overrides["kaslr-disabled"] = (v < 2) ? "hit" : "miss";
+      }
+      // unpriv-userns-enabled: clone == 1 means enabled (risky).
+      if (parsed.unprivileged_userns_clone != null) {
+        const v = parseInt(parsed.unprivileged_userns_clone, 10);
+        signal_overrides["unpriv-userns-enabled"] = (v === 1) ? "hit" : "miss";
+      }
+      // unpriv-bpf-allowed: bpf_disabled == 0 means unprivileged BPF
+      // is allowed (risky).
+      if (parsed.unprivileged_bpf_disabled != null) {
+        const v = parseInt(parsed.unprivileged_bpf_disabled, 10);
+        signal_overrides["unpriv-bpf-allowed"] = (v === 0) ? "hit" : "miss";
+      }
+    }
+  }
+
+  return {
+    precondition_checks: {
+      "linux-platform": linuxPlatform,
+      "uname-available": unameAvailable,
+    },
+    artifacts,
+    signal_overrides,
+    collector_meta: {
+      collector_id: COLLECTOR_ID,
+      collector_version: "2026-05-20",
+      platform: process.platform,
+      captured_at: new Date().toISOString(),
+      cwd,
+    },
+    collector_errors: errors,
+  };
+}
+
+module.exports = { playbook_id: COLLECTOR_ID, collect };