@blamejs/exceptd-skills 0.16.29 → 0.16.30

package/lib/refresh-external.js

@@ -301,6 +301,13 @@ const KEV_SOURCE = {
           errors.push(`KEV: no local entry for ${d.id}`);
           continue;
         }
+        // A de-listing flagged for review (a curated entry with strong
+        // exploitation signal that upstream KEV no longer lists) is surfaced
+        // in the report but NOT auto-applied: the curated flag, factor, score
+        // and dates are left intact so a maintainer can confirm a genuine
+        // CISA removal vs a transient / incomplete feed before the entry is
+        // downgraded. Skip the write here.
+        if (d.review_only) continue;
         catalog[d.id][d.field] = d.after;
         // A cisa_kev flip changes the entry's RWEP: the KEV factor carries
         // RWEP_WEIGHTS.cisa_kev points, and the catalog invariant requires
@@ -864,6 +871,28 @@ function readCachedJson(cacheDir, source, id, opts) {
   return parsed;
 }
 
+// A curated entry carries strong human-curated exploitation signal when its
+// active_exploitation is confirmed/suspected, or it has a non-empty PoC
+// description / verification sources. A de-listing of such an entry is far
+// more likely a transient or incomplete upstream feed than a genuine CISA
+// removal, so it is surfaced for review rather than auto-applied.
+function hasCuratedExploitSignal(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  const ae = typeof entry.active_exploitation === "string" ? entry.active_exploitation.toLowerCase() : "";
+  if (ae === "confirmed" || ae === "suspected") return true;
+  if (typeof entry.poc_description === "string" && entry.poc_description.trim()) return true;
+  if (Array.isArray(entry.verification_sources) && entry.verification_sources.length > 0) return true;
+  return false;
+}
+
+// Below this many entries the cached KEV feed is treated as truncated /
+// incomplete rather than a genuine CISA snapshot. CISA KEV has carried well
+// over a thousand entries since 2021 and only grows; a feed this small means
+// a partial download or a tampered cache, and trusting it to de-list curated
+// entries would silently erase confirmed-exploitation intel. De-listings are
+// refused wholesale when the feed is implausibly small.
+const KEV_FEED_MIN_PLAUSIBLE = 500;
+
 function kevDiffFromCache(ctx) {
   const feed = readCachedJson(ctx.cacheDir, "kev", "known_exploited_vulnerabilities", { forceStale: ctx.forceStale });
   if (!feed) {
@@ -877,12 +906,39 @@ function kevDiffFromCache(ctx) {
       if (v.dateAdded) kevDates.set(v.cveID, v.dateAdded);
     }
   }
+  // An implausibly small feed cannot be trusted to de-list curated entries.
+  // First-listings (false→true) still flow — a small feed never invents new
+  // exploitation; only the de-list direction is suppressed.
+  const feedComplete = kevSet.size >= KEV_FEED_MIN_PLAUSIBLE;
   const diffs = [];
   for (const [id, entry] of Object.entries(ctx.cveCatalog)) {
     if (!/^CVE-\d{4}-\d{4,7}$/.test(id)) continue;
     const upstream = kevSet.has(id);
     if (typeof entry.cisa_kev === "boolean" && entry.cisa_kev !== upstream) {
-      diffs.push({ id, field: "cisa_kev", before: entry.cisa_kev, after: upstream, severity: "high" });
+      const isDelist = entry.cisa_kev === true && upstream === false;
+      // Symmetric with the NVD path's curated-downgrade guard: never silently
+      // regress curated exploitation intel against an upstream that disagrees.
+      // A de-listing of a curated entry with strong exploitation signal, OR
+      // any de-listing when the feed is implausibly small, is re-tagged as a
+      // review-only diff — surfaced in the report so a maintainer confirms a
+      // genuine CISA removal, but NOT auto-applied (applyDiff skips
+      // review_only diffs, leaving cisa_kev / rwep / dates intact).
+      if (isDelist && (!feedComplete || hasCuratedExploitSignal(entry))) {
+        diffs.push({
+          id,
+          field: "cisa_kev",
+          before: entry.cisa_kev,
+          after: upstream,
+          severity: "high",
+          review_only: true,
+          kev_delist_review: true,
+          note: !feedComplete
+            ? `KEV de-listing held for review: cached feed has only ${kevSet.size} entries (< ${KEV_FEED_MIN_PLAUSIBLE}), likely incomplete. Confirm against a complete CISA KEV snapshot before de-listing.`
+            : "KEV de-listing held for review: entry carries curated exploitation signal (active_exploitation / PoC / verification sources). Confirm a genuine CISA removal vs a transient feed gap before de-listing.",
+        });
+      } else {
+        diffs.push({ id, field: "cisa_kev", before: entry.cisa_kev, after: upstream, severity: "high" });
+      }
     }
     const upDate = kevDates.get(id) || null;
     // First listings arrive with a null local date — emit the date diff
@@ -1553,10 +1609,54 @@ async function main() {
   // refresh loop and could egress + write refresh-report.json despite
   // --no-network.
   if (opts.prefetch || opts.noNetwork) {
+    // Validate --source against the prefetchable (cache-backed) subset BEFORE
+    // delegating to prefetch.js. prefetch.js only knows kev/nvd/epss/rfc/pins;
+    // the refresh-only sources (ghsa, osv, advisories, cve-regression-watcher)
+    // resolve advisories by live id lookup and have no cache layer. Without
+    // this guard, `refresh --prefetch --source osv` reached prefetch.js and
+    // died with `prefetch: fatal: unknown source "osv"` — leaking the internal
+    // verb name (the operator typed `refresh`) and calling a source "unknown"
+    // that the refresh help just listed as valid. Emit a refresh-prefixed,
+    // actionable message instead and forward only the cacheable subset.
+    const PREFETCHABLE = new Set(["kev", "nvd", "epss", "rfc", "pins"]);
+    let forwardSource = opts.source;
+    if (opts.source) {
+      const names = opts.source.split(",").map((s) => s.trim()).filter(Boolean);
+      if (names.length === 0) {
+        process.stderr.write(JSON.stringify({
+          ok: false,
+          verb: "refresh",
+          error: `refresh: --source given but resolved to no source names (empty or comma-only value); prefetchable sources: ${[...PREFETCHABLE].join(",")}`,
+        }) + "\n");
+        process.exitCode = 2;
+        return;
+      }
+      const unsupported = names.filter((n) => !PREFETCHABLE.has(n) && ALL_SOURCES[n]);
+      const unknown = names.filter((n) => !PREFETCHABLE.has(n) && !ALL_SOURCES[n]);
+      if (unknown.length > 0) {
+        process.stderr.write(JSON.stringify({
+          ok: false,
+          verb: "refresh",
+          error: `refresh: unknown source ${unknown.map((n) => `"${n}"`).join(", ")}; prefetchable sources: ${[...PREFETCHABLE].join(",")}`,
+        }) + "\n");
+        process.exitCode = 2;
+        return;
+      }
+      if (unsupported.length > 0) {
+        process.stderr.write(JSON.stringify({
+          ok: false,
+          verb: "refresh",
+          error: `refresh: source ${unsupported.map((n) => `"${n}"`).join(", ")} has no prefetch cache layer (live id lookup only); prefetchable sources: ${[...PREFETCHABLE].join(",")}`,
+        }) + "\n");
+        process.exitCode = 2;
+        return;
+      }
+      forwardSource = names.join(",");
+    }
     const { spawnSync } = require("child_process");
     const pfArgs = [require.resolve("./prefetch.js")];
     if (opts.noNetwork) pfArgs.push("--no-network");
-    if (opts.source) pfArgs.push("--source", opts.source);
+    if (forwardSource) pfArgs.push("--source", forwardSource);
     if (opts.quiet) pfArgs.push("--quiet");
     const r = spawnSync(process.execPath, pfArgs, { stdio: "inherit" });
     process.exitCode = r.status == null ? 1 : r.status;
@@ -1740,4 +1840,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { ALL_SOURCES, loadCtx, parseArgs, seedSingleAdvisory, withCatalogLock, writeJsonAtomic, nvdDiffFromCache };
+module.exports = { ALL_SOURCES, loadCtx, parseArgs, seedSingleAdvisory, withCatalogLock, writeJsonAtomic, nvdDiffFromCache, kevDiffFromCache };

package/lib/scoring.js

@@ -214,7 +214,23 @@ function scoreCustom(factors, opts) {
   // which propagates NaN through the final clamp, defeating the [0,100]
   // contract. Number.isFinite + Number() coercion catches all four classes:
   // NaN, Infinity, undefined, stringified-number.
-  const brRaw = Number.isFinite(Number(blast_radius)) ? Number(blast_radius) : 0;
+  // Match validateFactors' contract exactly. Bare `Number()` coercion would
+  // turn `true` into 1 and a single-element array like `[7]` into 7 — both of
+  // which validateFactors rejects as "expected number" — so the scorer would
+  // silently add a blast contribution the validator says is invalid. Accept
+  // only a finite number or a trimmed-nonempty numeric string; everything
+  // else (boolean, array, object, NaN, Infinity, empty/whitespace string)
+  // contributes 0.
+  let brRaw = 0;
+  if (typeof blast_radius === 'number' && Number.isFinite(blast_radius)) {
+    brRaw = blast_radius;
+  } else if (
+    typeof blast_radius === 'string' &&
+    blast_radius.trim() !== '' &&
+    Number.isFinite(Number(blast_radius))
+  ) {
+    brRaw = Number(blast_radius);
+  }
   const brClamped = Math.max(0, Math.min(RWEP_WEIGHTS.blast_radius, brRaw));
   score += brClamped;
   score += patch_available ? RWEP_WEIGHTS.patch_available : 0;
@@ -303,9 +319,21 @@ function compare(cveId, catalog, opts) {
   } else {
     rwep = entry.rwep_score;
   }
-  const cvss = entry.cvss_score;
-  const cvssEquivalent = cvss * 10;
-  const delta = rwep - cvssEquivalent;
+  // Normalize cvss before any arithmetic. An absent or non-finite cvss_score
+  // must not flow into `cvss * 10` — `undefined * 10 === NaN` poisons the
+  // delta, and NaN fails every `delta > 10` / `delta < -10` band, so the
+  // entry would otherwise fall through to the "broadly aligned" arm and
+  // assert an alignment that was never computed. Treat absent CVSS as
+  // not-comparable instead.
+  const cvss = (typeof entry.cvss_score === 'number' && Number.isFinite(entry.cvss_score))
+    ? entry.cvss_score
+    : null;
+  const cvssAbsent = cvss == null;
+  const cvssEquivalent = cvssAbsent ? 0 : cvss * 10;
+  // delta is null (not NaN) when there is no CVSS to compare against, so the
+  // emitted result serializes cleanly and never claims a numeric divergence
+  // that does not exist.
+  const delta = cvssAbsent ? null : rwep - cvssEquivalent;
 
   // narrow the "broadly aligned" band from ±20 to ±10. The old
   // ±20 band swallowed the Copy Fail RWEP-vs-CVSS divergence (delta = 12)
@@ -321,6 +349,11 @@ function compare(cveId, catalog, opts) {
   // catalog gap rather than a false sense of alignment.
   if ((rwep == null || rwep === 0) && (cvss == null || cvss === 0)) {
     explanation = 'No scoring signal — both RWEP and CVSS are zero/null. Investigate the catalog entry; this CVE has no usable risk score.';
+  } else if (cvssAbsent) {
+    // RWEP carries a real signal but there is no CVSS to compare it against.
+    // The two scores are not comparable, so do not assert alignment or a
+    // divergence direction — surface the missing CVSS instead.
+    explanation = 'CVSS absent — RWEP is the only usable score for this CVE; no CVSS comparison is possible. Backfill cvss_score in the catalog to enable the comparison.';
   } else if (delta > 10) {
     explanation = `RWEP significantly higher than CVSS equivalent. Factors driving delta: `;
     const driving = [];
@@ -460,13 +493,24 @@ function validate(catalog) {
         active_exploitation: RWEP_WEIGHTS.active_exploitation * aeMultiplier,
         patch_available: entry.patch_available === true ? RWEP_WEIGHTS.patch_available : 0,
         live_patch_available: entry.live_patch_available === true ? RWEP_WEIGHTS.live_patch_available : 0,
-        reboot_required: entry.patch_required_reboot === true ? RWEP_WEIGHTS.reboot_required : 0,
       };
       for (const [k, want] of Object.entries(implied)) {
         if (k in f && typeof f[k] === 'number' && f[k] !== want) {
           errors.push(`${cveId}: rwep_factors.${k} is ${f[k]} but the entry's source fields imply ${want}`);
         }
       }
+      // The reboot contribution has ONE implied weight but TWO accepted
+      // spellings — `reboot_required` (canonical) and `patch_required_reboot`
+      // (the catalog field-name alias scoreCustom also honors). Check both
+      // against that single weight; keying only on `reboot_required` let a
+      // contradictory value stored under the alias slip past the coherence
+      // gate, inflating the derived score.
+      const rebootWant = entry.patch_required_reboot === true ? RWEP_WEIGHTS.reboot_required : 0;
+      for (const rebootKey of ['reboot_required', 'patch_required_reboot']) {
+        if (rebootKey in f && typeof f[rebootKey] === 'number' && f[rebootKey] !== rebootWant) {
+          errors.push(`${cveId}: rwep_factors.${rebootKey} is ${f[rebootKey]} but the entry's source fields imply ${rebootWant}`);
+        }
+      }
     }
     const calculatedRwep = scoreCustom({
       cisa_kev: entry.cisa_kev,

package/lib/validate-cve-catalog.js

@@ -264,8 +264,20 @@ function additionalChecks(key, entry, ctx) {
   for (const { field, set, file } of REF_FIELDS) {
     if (!set) continue; // catalog absent — skip silently (defense-in-depth)
     const refs = entry[field];
-    if (!Array.isArray(refs)) continue;
-    for (const ref of refs) {
+    // Most ref fields are arrays of id strings (atlas_refs, cwe_refs, ...),
+    // but framework_control_gaps is a map keyed BY control id. An
+    // Array.isArray-only guard skipped the map form entirely, so orphaned
+    // control ids never surfaced. Derive the candidate ids from whichever
+    // shape the field uses: array elements, or the keys of a plain object.
+    let ids;
+    if (Array.isArray(refs)) {
+      ids = refs;
+    } else if (refs && typeof refs === 'object') {
+      ids = Object.keys(refs);
+    } else {
+      continue;
+    }
+    for (const ref of ids) {
       if (typeof ref !== 'string') continue;
       if (!set.has(ref)) {
         warnings.push(

package/lib/validate-playbooks.js

@@ -25,6 +25,14 @@
  *   - phases.detect.indicators[].cve_ref    → data/cve-catalog.json
  *   - phases.detect.false_positive_profile[].indicator_id
  *                                     → phases.detect.indicators[].id
+ *   - directives[].applies_to.cve     → data/cve-catalog.json keys
+ *   - directives[].applies_to.atlas_ttp → data/atlas-ttps.json keys
+ *   - directives[].applies_to.attack_technique → data/attack-techniques.json
+ *   - directives[].phase_overrides.govern.jurisdiction_obligations[].clock_starts
+ *                                     → closed clock_starts vocabulary
+ *   - directives[].phase_overrides.direct.rwep_threshold → ordering + range
+ *   - directives[].phase_overrides.close.notification_actions[].obligation_ref
+ *                                     → effective jurisdiction_obligations
  *
  * Internal consistency:
  *   - Indicator ids are unique within a playbook.
@@ -438,28 +446,15 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
   }
 
   // rwep_threshold ordering. Hard error — a misordered threshold actively
-  // breaks the scoring path.
-  const rwep = direct.rwep_threshold || {};
-  if (
-    typeof rwep.close === 'number' &&
-    typeof rwep.monitor === 'number' &&
-    typeof rwep.escalate === 'number'
-  ) {
-    if (!(rwep.close <= rwep.monitor && rwep.monitor <= rwep.escalate)) {
-      err(
-        `phases.direct.rwep_threshold: ordering violation — expected close <= monitor <= escalate, got close=${rwep.close} monitor=${rwep.monitor} escalate=${rwep.escalate}`,
-      );
-    }
-    for (const [k, v] of [
-      ['close', rwep.close],
-      ['monitor', rwep.monitor],
-      ['escalate', rwep.escalate],
-    ]) {
-      if (v < 0 || v > 100) {
-        err(`phases.direct.rwep_threshold.${k}: ${v} outside 0..100`);
-      }
-    }
-  }
+  // breaks the scoring path. Factored into a helper so the same check runs
+  // against the playbook-level direct phase AND any directive-level
+  // phase_overrides.direct copy the runner deep-merges at run time.
+  checkRwepThreshold(direct.rwep_threshold, 'phases.direct.rwep_threshold');
+
+  // clock_starts closed-vocab against the base govern phase. Factored into a
+  // helper for the same reason — an override-supplied jurisdiction_obligations
+  // copy must pass the same closed-vocabulary gate.
+  checkClockStarts(govern.jurisdiction_obligations, 'phases.govern.jurisdiction_obligations');
 
   // notification_actions obligation_ref resolution.
   const obligationKeys = new Set(
@@ -553,22 +548,9 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     );
   }
 
-  // Closed controlled-vocabulary enums: a value outside the schema's closed
-  // enum is an error, not a warning, so a typo cannot ship. Unlike the
-  // evolving-drift enums (artifact `type`, indicator `type`) which the generic
-  // validator keeps at warning, these vocabularies are fixed and load-bearing
-  // (clock_starts decides when a notification deadline starts counting;
-  // frameworks_in_scope drives gap-analysis routing).
-  if (ctx.clockStartsEnum) {
-    for (const [i, o] of (govern.jurisdiction_obligations || []).entries()) {
-      if (!o || typeof o !== 'object') continue;
-      if (o.clock_starts !== undefined && !ctx.clockStartsEnum.has(o.clock_starts)) {
-        err(
-          `phases.govern.jurisdiction_obligations[${i}].clock_starts: invalid value ${JSON.stringify(o.clock_starts)} — not in closed vocabulary ${JSON.stringify([...ctx.clockStartsEnum])}`,
-        );
-      }
-    }
-  }
+  // frameworks_in_scope closed vocabulary. A value outside the schema's closed
+  // enum is an error, not a warning, so a typo cannot ship — frameworks_in_scope
+  // drives gap-analysis routing.
   if (ctx.frameworksEnum) {
     for (const [i, f] of (domain.frameworks_in_scope || []).entries()) {
       if (typeof f === 'string' && !ctx.frameworksEnum.has(f)) {
@@ -579,7 +561,120 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     }
   }
 
+  // Directive-level coverage. A directive's applies_to fields and its
+  // phase_overrides both reach the runner live (the runner selects directives
+  // by id, deep-merges phase_overrides into the base phase, and surfaces
+  // applies_to in the discovery API) but neither was cross-referenced or
+  // re-validated — so a stale CVE/TTP reference or a tampered override
+  // (bogus clock_starts, out-of-range rwep_threshold) shipped past this gate
+  // even though the identical content is a hard error at playbook level.
+  for (const [i, d] of (playbook.directives || []).entries()) {
+    if (!d || typeof d !== 'object') continue;
+    const label = d.id ? `directives[${i}] (${d.id})` : `directives[${i}]`;
+
+    // applies_to.{cve,atlas_ttp,attack_technique} resolution, mirroring the
+    // domain-ref checks at warning severity (promoted to error under --strict).
+    const at = d.applies_to;
+    if (at && typeof at === 'object') {
+      if (at.cve && !ctx.cveKeys.has(at.cve)) {
+        warn(`${label}.applies_to.cve: unresolved "${at.cve}" (not in data/cve-catalog.json)`);
+      }
+      if (at.atlas_ttp && !ctx.atlasKeys.has(at.atlas_ttp)) {
+        warn(`${label}.applies_to.atlas_ttp: unresolved "${at.atlas_ttp}" (not in data/atlas-ttps.json)`);
+      }
+      // Guard the attack catalog the same way domain.attack_refs does:
+      // attack-techniques.json is loaded via readJsonIfExists and may be null.
+      if (at.attack_technique && ctx.attackKeys && !ctx.attackKeys.has(at.attack_technique)) {
+        warn(`${label}.applies_to.attack_technique: unresolved "${at.attack_technique}" (not in data/attack-techniques.json)`);
+      }
+    }
+
+    // phase_overrides re-validation. The runner merges these into the base
+    // phase before govern()/close() consume them, so an override-supplied
+    // clock_starts or rwep_threshold must pass the same gates as the base
+    // phase or the regulatory clock / scoring path breaks at run time.
+    const ov = d.phase_overrides;
+    if (ov && typeof ov === 'object') {
+      if (ov.govern && typeof ov.govern === 'object') {
+        checkClockStarts(
+          ov.govern.jurisdiction_obligations,
+          `${label}.phase_overrides.govern.jurisdiction_obligations`,
+        );
+      }
+      if (ov.direct && typeof ov.direct === 'object') {
+        checkRwepThreshold(
+          ov.direct.rwep_threshold,
+          `${label}.phase_overrides.direct.rwep_threshold`,
+        );
+      }
+      // An override-supplied notification obligation_ref must resolve against
+      // the EFFECTIVE obligation set the runner sees after the merge: the
+      // base govern obligations, plus any the override adds. Warning severity,
+      // matching the base-phase obligation_ref precedent.
+      if (ov.close && typeof ov.close === 'object' && Array.isArray(ov.close.notification_actions)) {
+        const overrideObligations =
+          (ov.govern && Array.isArray(ov.govern.jurisdiction_obligations))
+            ? ov.govern.jurisdiction_obligations
+            : (govern.jurisdiction_obligations || []);
+        const effectiveKeys = new Set(overrideObligations.map(obligationKey));
+        for (const [j, na] of ov.close.notification_actions.entries()) {
+          if (!na || typeof na !== 'object') continue;
+          if (na.obligation_ref && !effectiveKeys.has(na.obligation_ref)) {
+            warn(
+              `${label}.phase_overrides.close.notification_actions[${j}].obligation_ref: unresolved "${na.obligation_ref}" — no matching jurisdiction_obligations entry (synthesized as "<jurisdiction>/<regulation> <window_hours>h")`,
+            );
+          }
+        }
+      }
+    }
+  }
+
   return findings;
+
+  // ---- local helpers (hoisted; close over `findings`/`ctx`/`err`) ----
+
+  // rwep_threshold ordering + range. close <= monitor <= escalate, each in
+  // 0..100. Error severity — a misordered or out-of-range threshold actively
+  // breaks the scoring path. `pathPrefix` keeps the message accurate whether
+  // the source is the base phase or a directive override.
+  function checkRwepThreshold(rwepObj, pathPrefix) {
+    const rwep = rwepObj || {};
+    if (
+      typeof rwep.close === 'number' &&
+      typeof rwep.monitor === 'number' &&
+      typeof rwep.escalate === 'number'
+    ) {
+      if (!(rwep.close <= rwep.monitor && rwep.monitor <= rwep.escalate)) {
+        err(
+          `${pathPrefix}: ordering violation — expected close <= monitor <= escalate, got close=${rwep.close} monitor=${rwep.monitor} escalate=${rwep.escalate}`,
+        );
+      }
+      for (const [k, v] of [
+        ['close', rwep.close],
+        ['monitor', rwep.monitor],
+        ['escalate', rwep.escalate],
+      ]) {
+        if (v < 0 || v > 100) {
+          err(`${pathPrefix}.${k}: ${v} outside 0..100`);
+        }
+      }
+    }
+  }
+
+  // clock_starts closed-vocabulary check over a jurisdiction_obligations list.
+  // Error severity — clock_starts decides when a notification deadline starts
+  // counting; an out-of-vocabulary value silently never starts the clock.
+  function checkClockStarts(obligations, pathPrefix) {
+    if (!ctx.clockStartsEnum || !Array.isArray(obligations)) return;
+    for (const [i, o] of obligations.entries()) {
+      if (!o || typeof o !== 'object') continue;
+      if (o.clock_starts !== undefined && !ctx.clockStartsEnum.has(o.clock_starts)) {
+        err(
+          `${pathPrefix}[${i}].clock_starts: invalid value ${JSON.stringify(o.clock_starts)} — not in closed vocabulary ${JSON.stringify([...ctx.clockStartsEnum])}`,
+        );
+      }
+    }
+  }
 }
 
 /* Cross-playbook mutex-reciprocity check.