@blamejs/exceptd-skills 0.10.1 → 0.10.2

package/AGENTS.md

@@ -77,6 +77,57 @@ Operator asks: "is this host vulnerable to Copy Fail?" AI invokes `node lib/play
 
 Schema reference: `lib/schemas/playbook.schema.json`. Reference playbook (read this before authoring a new one): `data/playbooks/kernel.json`.
 
+### feeds_into threshold matrix
+
+Each playbook's `_meta.feeds_into[]` declares downstream playbooks the host AI should consider chaining into after this run, and the condition that fires the chain. The condition expressions evaluate at `close()` against `analyze` + `validate` + `agentSignals` context. AI assistants surface the suggested next playbook to the operator but never auto-execute; the operator decides.
+
+The current (v0.10.x) matrix:
+
+| From | Triggers | To | Why |
+|---|---|---|---|
+| ai-api | `analyze.compliance_theater_check.verdict == 'theater'` | framework | dotfile-cred-exposure theater pattern |
+| ai-api | `analyze.blast_radius_score >= 4` | sbom | broad blast radius → inventory check |
+| ai-api | `finding.includes_mcp_server_credential_exposure == true` | mcp | MCP creds leaked → MCP fleet audit |
+| containers | `finding.severity >= 'high'` | kernel | container escape → kernel surface |
+| containers | `always` | secrets | manifests routinely embed secrets |
+| cred-stores | `finding.severity >= 'high'` | secrets | leaked creds in store → repo grep |
+| cred-stores | `finding.severity == 'critical'` | runtime | critical exposure → listening-surface audit |
+| crypto | `analyze.compliance_theater_check.verdict == 'theater'` | framework | FIPS-claim vs reality |
+| crypto | `analyze.blast_radius_score >= 4` | sbom | crypto blast → SBOM-cve match |
+| framework | `any compliance_theater_check.verdict == 'theater' AND blast_radius_score >= 4` | sbom | theater + breadth → inventory |
+| hardening | `always` | kernel | hardening is corroborator for kernel finding |
+| hardening | `finding.severity >= 'high'` | runtime | weak hardening → check actual exposure |
+| kernel | `finding.severity == 'critical' OR analyze.blast_radius_score >= 4` | sbom | critical kernel → SBOM cross-ref |
+| kernel | `analyze.compliance_theater_check.verdict == 'theater'` | framework | patch-SLA theater |
+| mcp | `finding.severity == 'critical' OR analyze.blast_radius_score >= 4` | sbom | broad MCP impact → inventory |
+| mcp | `analyze.compliance_theater_check.verdict == 'theater'` | framework | MCP-trust theater |
+| mcp | `finding.includes_credential_exposure == true` | ai-api | MCP cred → AI-API cred audit |
+| runtime | `always` | kernel | listener finding always informs kernel triage |
+| runtime | `always` | hardening | runtime exposure pairs with hardening posture |
+| runtime | `finding.severity == 'critical' OR analyze.blast_radius_score >= 3` | cred-stores | critical runtime → check cred stores |
+| sbom | `analyze.compliance_theater_check.verdict == 'theater'` | framework | SBOM-signing theater |
+| sbom | `any matched_cve.attack_class == 'kernel-lpe'` | kernel | kernel CVE in inventory → kernel playbook |
+| sbom | `any matched_cve.attack_class == 'mcp-supply-chain'` | mcp | MCP CVE in inventory → MCP playbook |
+| sbom | `any matched_cve.attack_class IN ['ai-c2', 'prompt-injection']` | ai-api | AI CVE → AI-API playbook |
+| secrets | `finding.severity >= 'high'` | cred-stores | leaked secret in repo → check store posture |
+
+Cross-cutting playbook `framework` is the natural correlation layer — many playbooks chain into it on a theater verdict. `sbom` is the breadth-of-impact follow-up most playbooks suggest when blast radius crosses 4. `kernel` + `hardening` + `runtime` form a tightly-coupled triangle (any one finding raises questions in the other two). When a playbook lists `always` as a feeds_into condition, the chain runs unconditionally — the AI should always at least offer the next playbook to the operator.
+
+### CLI reference
+
+| Verb | What it does |
+|---|---|
+| `exceptd plan` | Default: grouped-by-scope summary of all 13 playbooks. `--scope <type>` filters. `--directives` expands directive IDs/titles per playbook. `--flat` for non-grouped. |
+| `exceptd govern <pb>` | Phase 1 — jurisdiction obligations, theater fingerprints, framework gaps, skills to preload. |
+| `exceptd direct <pb>` | Phase 2 — threat context, RWEP thresholds, skill chain, token budget. |
+| `exceptd look <pb>` | Phase 3 — typed artifact-collection spec + `preconditions` array + submission-shape hint. |
+| `exceptd run <pb>` | Phases 4-7 from agent evidence. Auto-detect cwd when no playbook positional. `--scope <type>` or `--all` for multi-playbook. `--vex <file>` to drop CycloneDX/OpenVEX `not_affected` CVEs. `--ci` for exit-code gating. `--diff-from-latest` for drift mode. `--force-stale` to override currency hard-block. |
+| `exceptd ingest` | Alias for `run`; submission JSON may carry `playbook_id` + `directive_id`. |
+| `exceptd reattest [<sid> \| --latest]` | Replay prior session, diff evidence_hash. `--latest [--playbook <id>] [--since <ISO>]` finds the most recent attestation automatically. |
+| `exceptd list-attestations` | Inventory `.exceptd/attestations/<sid>/` — every prior session, newest first. `--playbook <id>` filters. |
+
+All verbs support `--help` for per-verb usage. JSON output by default; `--pretty` for indented.
+
 ---
 
 ## Recurring Drift Rules

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.10.2 — 2026-05-12
+
+**Patch: v0.10.1 deferred set — framework-gap filter fix, VEX consumption, CI gating, drift mode, 2 new playbooks (13 total), feeds_into matrix.**
+
+### Bug fix (carried from v0.9.x)
+
+**`exceptd framework-gap NIST-800-53 <cve-id>` returned 0 matches** while `framework-gap all <cve-id>` correctly found the same gap. Root cause: catalog stores `g.framework = "NIST SP 800-53 Rev 5"` (spaces) but operators pass `NIST-800-53` (hyphens), and `.includes()` is case + format sensitive. Fix: normalize both sides via `.toLowerCase().replace(/[\s_-]/g, '')` then substring-match against `g.framework` value AND prefix-match against the gap KEY (e.g. `NIST-800-53-SI-2`).
+
+### New CLI flags
+
+- **`run --vex <file>`** — load a CycloneDX or OpenVEX document. CVEs marked `not_affected | resolved | false_positive` (CycloneDX) or `not_affected | fixed` (OpenVEX) drop out of `analyze.matched_cves`. Dropped CVEs surface under `analyze.vex.dropped_cves` so the disposition is preserved for the audit trail.
+- **`run --ci`** — machine-readable verdict for CI gates. Exits 2 when `phases.detect.classification === 'detected'` OR (`classification === 'inconclusive'` AND `rwep.adjusted >= rwep_threshold.escalate`). Logs PASS/FAIL reason to stderr. Pure not_detected runs exit 0 even when the playbook's catalogued CVEs carry high baseline RWEP — the gate is about the host-specific verdict, not the catalog.
+- **`run --diff-from-latest`** — compare evidence_hash against the most recent prior attestation for the same playbook in `.exceptd/attestations/`. Drift mode for cron baselines. Result includes `prior_session_id`, `prior_captured_at`, `prior_evidence_hash`, `new_evidence_hash`, `status: unchanged | drifted | no_prior_attestation_for_playbook`.
+- **`reattest --latest [--playbook <id>] [--since <ISO>]`** — find the most-recent attestation automatically. No session-id required.
+
+### New playbooks (12 → 13)
+
+- **`crypto-codebase`** (scope: code, attack_class: pqc-exposure) — complements the host-side `crypto` playbook. Walks the codebase for in-source crypto choices: weak hash imports (MD5/SHA1), `Math.random()` in security context, PBKDF2 iteration counts, ECDSA curve choices, RSA bit-size constants, PQC adoption signals. Theater fingerprints include `pqc-ready-feature-flag-without-ml-kem` (config toggle with zero ML-KEM call sites), `fips-validated-by-linking-openssl` (link-time vs runtime FIPS provider), `pbkdf2-iterations-set-in-2015` (10k defaults in published packages).
+- **`library-author`** (scope: code, attack_class: supply-chain) — audits what you SHIP, not what you run. Vendored deps, SBOM signing posture, SLSA provenance attestation, VEX issuance, npm provenance, Rekor entries, cosign signing, branch protection, OIDC vs static publish tokens, EU CRA Art.13/14 conformity. Distinct from `sbom` (install-side); this is publish-side. Mutex with `secrets` since both compete for repo-walk cycles.
+
+### feeds_into threshold matrix (v0.10.2 doc pass)
+
+AGENTS.md now ships the full feeds_into matrix — 25 chains across 12 playbooks. Documents what triggers what, so operators understand the suggested-next-playbook routing rather than treating it as opaque magic. Highlights:
+
+- `framework` is the natural correlation layer — many playbooks chain into it on `analyze.compliance_theater_check.verdict == 'theater'`.
+- `sbom` is the breadth-of-impact follow-up most playbooks suggest when `analyze.blast_radius_score >= 4`.
+- `kernel + hardening + runtime` form a tightly-coupled triangle (any one raises questions in the other two).
+- `always` conditions on `hardening → kernel`, `runtime → kernel`, `runtime → hardening`, `containers → secrets` — the AI should always at least offer the next playbook to the operator.
+
+### Internal
+
+- **kernel.json feeds_into typo fix** — `compliance-theater` referent (no such playbook ID) corrected to `framework` (the playbook carrying the compliance-theater attack class). Test updated to assert the corrected chain.
+- **`vexFilterFromDoc` helper** in `lib/playbook-runner.js` — parses CycloneDX VEX or OpenVEX documents into a `Set<string>` of CVE IDs whose disposition is "not_affected" or equivalent.
+- **AGENTS.md** — new "feeds_into threshold matrix" section + "CLI reference" table.
+
+### Still deferred (next pass)
+
+- crypto-codebase playbook ships `eu-ai-act` and `cmmc` in `frameworks_in_scope` but doesn't thread either into `framework_gap_mapping` — Hard Rule #4 (no orphaned references) tidy. Either drop the entries or add concrete mapping in a follow-up.
+- Crypto-codebase byte size (95 KB) is above the 50-60 KB target for new playbooks — load-bearing content but worth a depth audit.
+- `_meta.feeds_into[].condition` parser supports a limited DSL — some playbooks use expressions like `any matched_cve.attack_class IN ['ai-c2', 'prompt-injection']` that the current parser doesn't fully support. Conditions degrade silently to false. Worth a parser pass to either expand the DSL or warn on unknown shapes.
+
 ## 0.10.1 — 2026-05-12
 
 **Patch: operator-reported bugs from v0.10.0 first contact + scope-aware `run` default.**

package/bin/exceptd.js

@@ -335,7 +335,7 @@ function dispatchPlaybook(cmd, argv) {
   }
 
   const args = parseArgs(argv, {
-    bool:  ["pretty", "air-gap", "force-stale", "all", "flat", "directives"],
+    bool:  ["pretty", "air-gap", "force-stale", "all", "flat", "directives", "ci", "latest", "diff-from-latest"],
     multi: ["playbook"],
   });
   const pretty = !!args.pretty;
@@ -429,6 +429,18 @@ Flags:
                             { artifacts, signal_overrides, signals, precondition_checks }
                           Multi-playbook shape:
                             { "<playbook_id>": { artifacts, ... }, ... }
+  --vex <file>            Load a CycloneDX or OpenVEX document. CVEs marked
+                          not_affected | resolved | false_positive (CycloneDX)
+                          or not_affected | fixed (OpenVEX) drop out of
+                          analyze.matched_cves. The disposition is preserved
+                          under analyze.vex.dropped_cves.
+  --diff-from-latest      Compare evidence_hash against the most recent prior
+                          attestation for the same playbook in
+                          .exceptd/attestations/. Emits status: unchanged | drifted.
+  --ci                    Machine-readable verdict for CI gates. Exits non-zero
+                          (code 2) when phases.detect.classification === 'detected'
+                          OR phases.analyze.rwep.adjusted >= rwep_threshold.escalate.
+                          Logs PASS/FAIL reason to stderr.
   --session-id <id>       Reuse a specific session ID.
   --session-key <hex>     HMAC sign the evidence_package with this key.
   --force-stale           Override the threat_currency_score < 50 hard-block.
@@ -444,13 +456,24 @@ Flags:
   --directive <id>        Directive ID (overrides submission.directive_id).
   --evidence <file|->     Submission JSON. May include playbook_id/directive_id.
   --pretty                Indented JSON output.`,
-    reattest: `reattest <session-id> — replay a prior session and diff the evidence_hash.
+    reattest: `reattest [<session-id> | --latest] — replay a prior session and diff the evidence_hash.
 
 Args / flags:
-  <session-id>            Required positional. Looks under .exceptd/attestations/<id>/.
+  <session-id>            Looks under .exceptd/attestations/<id>/attestation.json.
+  --latest                Find the most-recent attestation automatically.
+  --playbook <id>         Restrict --latest to a specific playbook.
+  --since <ISO>           Restrict --latest to attestations after this ISO 8601 timestamp.
   --pretty                Indented JSON output.
 
 Reports: unchanged | drifted | resolved from evidence_hash + classification deltas.`,
+    "list-attestations": `list-attestations [--playbook <id>] — enumerate prior attestations.
+
+Args / flags:
+  --playbook <id>         Filter to one playbook.
+  --pretty                Indented JSON output.
+
+Lists every attestation under .exceptd/attestations/<session_id>/, sorted
+newest-first, with truncated evidence_hash + capture timestamp + file path.`,
   };
   process.stdout.write((cmds[verb] || `${verb} — no per-verb help available; see \`exceptd help\` for the full list.`) + "\n");
 }
@@ -598,6 +621,19 @@ function cmdRun(runner, args, runOpts, pretty) {
     runOpts.precondition_checks = submission.precondition_checks;
   }
 
+  // --vex <file>: load a CycloneDX/OpenVEX document and pass the not_affected
+  // CVE ID set through to analyze() so matched_cves drops them.
+  if (args.vex) {
+    try {
+      const vexDoc = JSON.parse(fs.readFileSync(args.vex, "utf8"));
+      const vexSet = runner.vexFilterFromDoc(vexDoc);
+      submission.signals = submission.signals || {};
+      submission.signals.vex_filter = [...vexSet];
+    } catch (e) {
+      return emitError(`run: failed to load --vex ${args.vex}: ${e.message}`, null, pretty);
+    }
+  }
+
   const result = runner.run(playbookId, directiveId, submission, runOpts);
 
   // Persist attestation for reattest cycles when the run succeeded.
@@ -624,6 +660,68 @@ function cmdRun(runner, args, runOpts, pretty) {
     process.stderr.write((pretty ? JSON.stringify(result, null, 2) : JSON.stringify(result)) + "\n");
     process.exit(1);
   }
+
+  // --diff-from-latest: compare evidence_hash against the most recent prior
+  // attestation for this playbook. Drift mode for cron baselines.
+  // We've already persisted the CURRENT attestation above, so the find must
+  // skip our session_id to get the actual prior one.
+  if (args["diff-from-latest"] && result && result.evidence_hash) {
+    const prior = findLatestAttestation({ playbookId, excludeSessionId: result.session_id });
+    if (prior) {
+      const priorHash = prior.parsed.evidence_hash;
+      result.diff_from_latest = {
+        prior_session_id: prior.parsed.session_id,
+        prior_captured_at: prior.parsed.captured_at,
+        prior_evidence_hash: priorHash,
+        new_evidence_hash: result.evidence_hash,
+        status: priorHash === result.evidence_hash ? "unchanged" : "drifted",
+      };
+    } else {
+      result.diff_from_latest = { status: "no_prior_attestation_for_playbook", playbook_id: playbookId };
+    }
+  }
+
+  // --ci: machine-readable verdict for CI gates.
+  //
+  // The detect phase classification is the host-specific signal — "is THIS
+  // environment exploitable for the catalogued CVEs". rwep.base is the
+  // worst-known catalog score for the domain, which is roughly constant
+  // regardless of the local environment; we don't fail CI on that alone or
+  // every CI run against a domain with KEV-listed catalog entries would
+  // perma-fail.
+  //
+  // Verdict:
+  //   detected                → FAIL (exit 2)
+  //   inconclusive + rwep ≥ escalate
+  //                           → FAIL (the agent's evidence raised RWEP)
+  //   not_detected            → PASS (exit 0)
+  //   inconclusive + rwep < escalate
+  //                           → PASS with WARN to stderr (visibility gap)
+  if (args.ci && result && result.phases) {
+    const classification = result.phases.detect && result.phases.detect.classification;
+    const rwep = result.phases.analyze && result.phases.analyze.rwep;
+    const threshold = rwep && rwep.threshold && rwep.threshold.escalate;
+    const adjusted = rwep && typeof rwep.adjusted === "number" ? rwep.adjusted : 0;
+    const escalate = typeof threshold === "number" && adjusted >= threshold;
+
+    emit(result, pretty);
+
+    if (classification === "detected") {
+      process.stderr.write(`[exceptd run --ci] FAIL: classification=detected rwep=${adjusted} threshold=${threshold}\n`);
+      process.exit(2);
+    }
+    if (classification === "inconclusive" && escalate) {
+      process.stderr.write(`[exceptd run --ci] FAIL: classification=inconclusive AND rwep=${adjusted} >= threshold=${threshold}\n`);
+      process.exit(2);
+    }
+    if (classification === "inconclusive") {
+      process.stderr.write(`[exceptd run --ci] PASS+WARN: classification=inconclusive rwep=${adjusted} < threshold=${threshold} (visibility gap)\n`);
+    } else {
+      process.stderr.write(`[exceptd run --ci] PASS: classification=${classification} rwep=${adjusted}\n`);
+    }
+    return;
+  }
+
   emit(result, pretty);
 }
 
@@ -760,11 +858,52 @@ function cmdIngest(runner, args, runOpts, pretty) {
   emit(result, pretty);
 }
 
+/**
+ * Find the latest attestation file under .exceptd/attestations/.
+ * Filters: optional playbook ID and optional "since" ISO timestamp.
+ * Returns { sessionId, playbookId, file, parsed } or null.
+ */
+function findLatestAttestation(opts = {}) {
+  const root = path.join(process.cwd(), ".exceptd", "attestations");
+  if (!fs.existsSync(root)) return null;
+  const sessions = fs.readdirSync(root, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name);
+  const candidates = [];
+  for (const sid of sessions) {
+    const sdir = path.join(root, sid);
+    for (const f of fs.readdirSync(sdir).filter(x => x.endsWith(".json"))) {
+      try {
+        const p = path.join(sdir, f);
+        const j = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (opts.playbookId && j.playbook_id !== opts.playbookId) continue;
+        if (opts.since && (j.captured_at || "") < opts.since) continue;
+        if (opts.excludeSessionId && sid === opts.excludeSessionId) continue;
+        candidates.push({ sessionId: sid, playbookId: j.playbook_id, file: p, parsed: j });
+      } catch { /* skip malformed */ }
+    }
+  }
+  candidates.sort((a, b) => (b.parsed.captured_at || "").localeCompare(a.parsed.captured_at || ""));
+  return candidates[0] || null;
+}
+
 function cmdReattest(runner, args, runOpts, pretty) {
-  const sessionId = args._[0];
-  if (!sessionId) return emitError("reattest: missing <session-id> positional argument.", null, pretty);
+  // --latest [--playbook <id>] [--since <ISO>] — find prior attestation
+  // without requiring the operator to know the session-id.
+  let sessionId = args._[0];
+  let attFile = null;
+  if (!sessionId && args.latest) {
+    const found = findLatestAttestation({
+      playbookId: args.playbook ? (Array.isArray(args.playbook) ? args.playbook[0] : args.playbook) : null,
+      since: args.since || null,
+    });
+    if (!found) return emitError("reattest: --latest found no matching attestations.", { filter: { playbook: args.playbook || null, since: args.since || null } }, pretty);
+    sessionId = found.sessionId;
+    attFile = found.file;
+  }
+  if (!sessionId) return emitError("reattest: missing <session-id>. Pass a session-id or --latest [--playbook <id>] [--since <ISO>].", null, pretty);
   const dir = path.join(process.cwd(), ".exceptd", "attestations", sessionId);
-  const attFile = path.join(dir, "attestation.json");
+  if (!attFile) attFile = path.join(dir, "attestation.json");
   if (!fs.existsSync(attFile)) {
     return emitError(`reattest: no attestation found at ${path.relative(process.cwd(), attFile)}`, { session_id: sessionId }, pretty);
   }

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-05-12T13:36:15.948Z",
+  "generated_at": "2026-05-12T13:50:32.319Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 49,
   "source_hashes": {
-    "manifest.json": "f71c110a187ffaf19db2bbbb1f15ceb27f88bbb844d81329c21ba6705badac8a",
+    "manifest.json": "3614ad87835688365283c95a8b7af1d66f14928c07efef750c206ba2f13aab33",
     "data/atlas-ttps.json": "1500b5830dab070c4252496964a8c0948e1052a656e2c7c6e1efaf0350645e13",
     "data/cve-catalog.json": "a81d3e4b491b27ccc084596b063a6108ff10c9eb01d7776922fc393980b534fe",
     "data/cwe-catalog.json": "c3367d469b4b3d31e4c56397dd7a8305a0be338ecd85afa27804c0c9ce12157b",