@blamejs/exceptd-skills 0.12.15 → 0.12.16

package/lib/scoring.js

@@ -3,6 +3,40 @@
 /**
  * RWEP — Real-World Exploit Priority scoring engine
  * Supplements CVSS with exploit availability, active exploitation, and operational constraints.
+ *
+ * ----------------------------------------------------------------------------
+ * `rwep_factors` dual-semantics (audit J F2)
+ * ----------------------------------------------------------------------------
+ * Catalog entries (data/cve-catalog.json) store `rwep_factors` as an object
+ * whose values are POST-WEIGHT CONTRIBUTIONS for boolean / ladder factors
+ * but the RAW BLAST RADIUS for `blast_radius`. The two shapes coexist because
+ * each surface has different requirements:
+ *
+ *   cisa_kev:             0 OR +25         (post-weight contribution)
+ *   poc_available:        0 OR +20         (post-weight contribution)
+ *   ai_factor:            0 OR +15         (post-weight contribution)
+ *   active_exploitation:  0 / 10 / 5 / 20  (post-weight contribution from ladder)
+ *   blast_radius:         0..30 RAW        (intentionally NOT post-weight —
+ *                                          mirrors the weight ceiling so it
+ *                                          reads as raw blast magnitude)
+ *   patch_available:      0 OR -15         (post-weight contribution)
+ *   live_patch_available: 0 OR -10         (post-weight contribution)
+ *   reboot_required:      0 OR +5          (post-weight contribution)
+ *
+ * Operator-facing implication: summing `Object.values(rwep_factors)` produces
+ * the stored `rwep_score` for catalog entries because the blast weight is 30
+ * (matches the raw cap). This dual-shape is intentional but easy to misuse;
+ * direct boolean inputs should go through `scoreCustom()` instead.
+ *
+ * scoreCustom() input shape is DIFFERENT — it accepts BOOLEAN factors plus
+ * a numeric blast_radius and a string active_exploitation ladder value.
+ * `deriveRwepFromFactors()` is the shape-detecting bridge: if values look
+ * numeric (post-weighted), it sums; if values look boolean / string-ladder,
+ * it routes through scoreCustom.
+ *
+ * The semantic ambiguity is grandfathered. A clean rename (raw_factors vs
+ * weighted_contributions) is a minor-bump change and is deferred.
+ * ----------------------------------------------------------------------------
  */
 
 const CVE_SCHEMA_REQUIRED = [
@@ -28,6 +62,29 @@ const RWEP_WEIGHTS = {
   reboot_required:       5
 };
 
+// audit J F4: active_exploitation ladder. Aligned with playbook-runner's
+// _activeExploitationLadder so the catalog scorer and the runtime evaluator
+// produce identical results for the same string value. 'unknown' contributes
+// a quarter of the confirmed weight (5 points) — operationally "we have not
+// confirmed, but absence of evidence is not evidence of absence; do not
+// score zero on a fresh CVE that hasn't been triaged yet".
+const ACTIVE_EXPLOITATION_LADDER = {
+  confirmed: 1.0,
+  suspected: 0.5,
+  unknown:   0.25,
+  none:      0,
+};
+
+// The canonical set of factor keys scoreCustom recognises. Used by
+// validateFactors to flag unknown keys (audit J F8).
+const RECOGNISED_FACTOR_KEYS = new Set([
+  'cisa_kev', 'poc_available', 'ai_assisted_weapon', 'ai_discovered',
+  'active_exploitation', 'blast_radius', 'patch_available',
+  'live_patch_available', 'reboot_required',
+  // accepted alias for the catalog field name
+  'patch_required_reboot',
+]);
+
 function score(cveId, catalog) {
   const entry = catalog[cveId];
   if (!entry) throw new Error(`CVE not in catalog: ${cveId}`);
@@ -68,13 +125,29 @@ function validateFactors(factors) {
   } else if (!aeAllowed.includes(factors.active_exploitation)) {
     warnings.push(`active_exploitation: expected one of ${aeAllowed.join(', ')}, got ${JSON.stringify(factors.active_exploitation)}`);
   }
+  // audit J F6: NaN diagnostics. The prior message read "expected number,
+  // got number (null)" because `JSON.stringify(NaN) === 'null'` and `typeof
+  // NaN === 'number'`. Number.isFinite catches NaN + Infinity + -Infinity
+  // and emits a useful message.
   if (factors.blast_radius === undefined || factors.blast_radius === null) {
     warnings.push('blast_radius: missing (treated as 0)');
-  } else if (typeof factors.blast_radius !== 'number' || Number.isNaN(factors.blast_radius)) {
+  } else if (typeof factors.blast_radius !== 'number') {
     warnings.push(`blast_radius: expected number, got ${typeof factors.blast_radius} (${JSON.stringify(factors.blast_radius)})`);
+  } else if (Number.isNaN(factors.blast_radius)) {
+    warnings.push('blast_radius: NaN is not a valid numeric value (treated as 0)');
+  } else if (!Number.isFinite(factors.blast_radius)) {
+    warnings.push(`blast_radius: ${factors.blast_radius > 0 ? 'Infinity' : '-Infinity'} is not a finite numeric value (treated as 0)`);
   } else if (factors.blast_radius < 0 || factors.blast_radius > 30) {
     warnings.push(`blast_radius: ${factors.blast_radius} out of expected range [0, 30] (clamped to weight ceiling, but the value usually indicates a unit-of-measure mistake)`);
   }
+  // audit J F8: surface unknown factor keys so a typo'd answer file
+  // (`patch_avilable`, `cisa-kev`, etc.) doesn't silently default to false
+  // with no diagnostic.
+  for (const k of Object.keys(factors)) {
+    if (!RECOGNISED_FACTOR_KEYS.has(k)) {
+      warnings.push(`unknown factor: ${k} (ignored — not in the recognised key set)`);
+    }
+  }
   return warnings;
 }
 
@@ -113,8 +186,15 @@ function scoreCustom(factors, opts) {
   score += cisa_kev ? RWEP_WEIGHTS.cisa_kev : 0;
   score += poc_available ? RWEP_WEIGHTS.poc_available : 0;
   score += (ai_assisted_weapon || ai_discovered) ? RWEP_WEIGHTS.ai_factor : 0;
-  score += active_exploitation === 'confirmed' ? RWEP_WEIGHTS.active_exploitation : 0;
-  score += active_exploitation === 'suspected' ? Math.floor(RWEP_WEIGHTS.active_exploitation / 2) : 0;
+  // audit J F4 + F16: active_exploitation goes through the ladder rather
+  // than two hand-written branches with `Math.floor(weight/2)`. The floor
+  // was a no-op for even weights (20/2 = 10) but would have silently
+  // truncated to asymmetric results if a future operator bumped the
+  // weight to 21. The ladder + multiplication preserves the contribution
+  // exactly, including the new `unknown → 0.25 × weight = 5` mapping that
+  // aligns the catalog scorer with playbook-runner._activeExploitationLadder.
+  const aeMultiplier = ACTIVE_EXPLOITATION_LADDER[active_exploitation] ?? 0;
+  score += RWEP_WEIGHTS.active_exploitation * aeMultiplier;
   // v0.12.15 (audit J F1, F5): blast_radius numeric coercion must reject
   // NaN, Infinity, and strings explicitly. The prior `typeof === 'number'`
   // check passed NaN (which is `typeof === 'number'`) into `Math.min/max`
@@ -128,15 +208,60 @@ function scoreCustom(factors, opts) {
   score += live_patch_available ? RWEP_WEIGHTS.live_patch_available : 0;
   score += rebootFactor ? RWEP_WEIGHTS.reboot_required : 0;
 
+  // audit J F10: keep the pre-clamp value so collectWarnings consumers can
+  // see deduction magnitude (e.g. a -25 raw score collapsed to 0 hides the
+  // fact that the entry had three mitigating factors).
+  const rawUnclamped = score;
+
   // v0.12.15 (audit J F1): defense-in-depth clamp against any unforeseen
   // NaN production above (negative weight + Infinity + math edge case).
   const clamped = Number.isFinite(score) ? Math.min(100, Math.max(0, score)) : 0;
   if (opts && opts.collectWarnings) {
-    return { score: clamped, _scoring_warnings: validateFactors(factors) };
+    return {
+      score: clamped,
+      _rwep_raw_unclamped: Number.isFinite(rawUnclamped) ? rawUnclamped : null,
+      _scoring_warnings: validateFactors(factors),
+    };
   }
   return clamped;
 }
 
+/**
+ * audit J F3 + audit M P1-C bridge: derive an RWEP score from a
+ * `rwep_factors` object regardless of which shape it uses.
+ *
+ *   - SHAPE A (boolean / string-ladder): values are booleans + an
+ *     active_exploitation string + a numeric blast_radius. Route through
+ *     scoreCustom() — the canonical formula.
+ *   - SHAPE B (catalog post-weight): values are numeric contributions
+ *     (0 / ±N) plus a numeric blast_radius. Sum the numeric values and
+ *     clamp to [0, 100]. This is how catalog `rwep_factors` are stored.
+ *
+ * Heuristic: if every value is a number, treat as Shape B (sum). If any
+ * value is boolean or a recognised ladder string, treat as Shape A
+ * (scoreCustom). This lets the curation apply-path and the auto-discovery
+ * builder share one canonical derivation that handles either operator
+ * input style without duplicating the scoring formula.
+ */
+function deriveRwepFromFactors(factors) {
+  if (!factors || typeof factors !== 'object') return 0;
+  const values = Object.values(factors);
+  if (values.length === 0) return 0;
+  const aeAllowed = new Set(['none', 'unknown', 'suspected', 'confirmed']);
+  const hasBooleanOrLadder = values.some(
+    (v) => typeof v === 'boolean' || (typeof v === 'string' && aeAllowed.has(v)),
+  );
+  if (hasBooleanOrLadder) {
+    return scoreCustom(factors);
+  }
+  // Shape B: catalog post-weight. Sum + clamp.
+  let sum = 0;
+  for (const v of values) {
+    if (typeof v === 'number' && Number.isFinite(v)) sum += v;
+  }
+  return Math.max(0, Math.min(100, sum));
+}
+
 function timeline(rwepScore) {
   if (rwepScore >= 90) return { hours: 4, label: 'Immediate — live patch or isolate within 4 hours' };
   if (rwepScore >= 75) return { hours: 24, label: 'Urgent — patch or compensating controls within 24 hours' };
@@ -146,17 +271,36 @@ function timeline(rwepScore) {
   return { hours: null, label: 'Low — next scheduled maintenance' };
 }
 
-function compare(cveId, catalog) {
+function compare(cveId, catalog, opts) {
   const entry = catalog[cveId];
   if (!entry) throw new Error(`CVE not in catalog: ${cveId}`);
 
-  const rwep = entry.rwep_score;
+  // audit J F11: `--recompute` ignores the stored rwep_score and forces a
+  // fresh computation from rwep_factors. Useful for catching catalog drift
+  // (stored score grew stale relative to current weights) and for auditing
+  // the divergence between stored vs. formula-derived scores.
+  const recompute = !!(opts && opts.recompute);
+  let rwep;
+  if (recompute) {
+    const factors = entry.rwep_factors || {};
+    // The catalog's rwep_factors shape is "post-weight" (Shape B). Route
+    // through the shape-detecting helper so a catalog whose factors were
+    // hand-edited in either shape still produces a usable score.
+    rwep = deriveRwepFromFactors(factors);
+  } else {
+    rwep = entry.rwep_score;
+  }
   const cvss = entry.cvss_score;
   const cvssEquivalent = cvss * 10;
   const delta = rwep - cvssEquivalent;
 
+  // audit J F15: narrow the "broadly aligned" band from ±20 to ±10. The old
+  // ±20 band swallowed the Copy Fail RWEP-vs-CVSS divergence (delta = 12)
+  // where the operator-facing point is precisely that the CVSS-calibrated
+  // SLA is insufficient. ±10 is the tightest classifier that still treats
+  // ordinary CVSS rounding noise as alignment.
   let explanation = '';
-  if (delta > 20) {
+  if (delta > 10) {
     explanation = `RWEP significantly higher than CVSS equivalent. Factors driving delta: `;
     const driving = [];
     if (entry.cisa_kev) driving.push('CISA KEV (+25)');
@@ -166,7 +310,7 @@ function compare(cveId, catalog) {
     if (entry.patch_required_reboot && !entry.live_patch_available) driving.push('reboot required (+5)');
     explanation += driving.join(', ');
     explanation += '. Framework patch SLAs calibrated to CVSS are insufficient for this CVE.';
-  } else if (delta < -20) {
+  } else if (delta < -10) {
     explanation = `RWEP lower than CVSS equivalent. Mitigating factors: `;
     const mitigating = [];
     if (entry.patch_available) mitigating.push('patch available (-15)');
@@ -178,15 +322,20 @@ function compare(cveId, catalog) {
     explanation = 'CVSS and RWEP are broadly aligned for this CVE.';
   }
 
-  return {
+  const out = {
     cve_id: cveId,
     cvss: cvss,
     rwep: rwep,
     cvss_framework_sla: timeline(cvssEquivalent),
     rwep_actual_sla: timeline(rwep),
     delta,
-    explanation
+    explanation,
   };
+  if (recompute) {
+    out.stored_rwep_score = entry.rwep_score;
+    out.recomputed = true;
+  }
+  return out;
 }
 
 function validate(catalog) {
@@ -222,4 +371,15 @@ function validate(catalog) {
   return errors;
 }
 
-module.exports = { score, scoreCustom, timeline, compare, validate, validateFactors, RWEP_WEIGHTS };
+module.exports = {
+  score,
+  scoreCustom,
+  timeline,
+  compare,
+  validate,
+  validateFactors,
+  deriveRwepFromFactors,
+  RWEP_WEIGHTS,
+  ACTIVE_EXPLOITATION_LADDER,
+  RECOGNISED_FACTOR_KEYS,
+};

package/lib/validate-playbooks.js

@@ -31,6 +31,9 @@
  *     govern.jurisdiction_obligations[] (the schema does not give
  *     jurisdiction_obligations an explicit `id` field; the shipped playbooks
  *     reference them by this composite string).
+ *   - _meta.mutex is symmetric across the whole playbook set: if A lists B,
+ *     B must list A. Asymmetry surfaces as a warning in v0.12.16 (and will
+ *     flip to error in v0.13.0) — see checkMutexReciprocity().
  *
  * Finding severity:
  *   - error   — structural problems that block the runner (missing required
@@ -397,6 +400,44 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
   return findings;
 }
 
+/* Cross-playbook mutex-reciprocity check.
+ *
+ * `_meta.mutex` is a symmetric relation: if playbook A lists B, B must list A.
+ * Asymmetry is a latent runner bug — the engine's mutex enforcement only
+ * blocks concurrent execution from whichever side declared the conflict, so
+ * an asymmetric declaration silently degrades to a race condition when the
+ * undeclared side is started first.
+ *
+ * Emits one warning per asymmetric pair (keyed off the side that declares
+ * the edge). v0.12.16 keeps this at warning severity per the patch-class
+ * cadence; v0.13.0 will flip it to error via --strict / predeploy
+ * `informational: false`.
+ */
+function checkMutexReciprocity(playbooks) {
+  const findings = [];
+  const mutexMap = new Map();
+  for (const pb of playbooks) {
+    if (!pb.data || !pb.data._meta || !pb.data._meta.id) continue;
+    const id = pb.data._meta.id;
+    const mutex = Array.isArray(pb.data._meta.mutex) ? pb.data._meta.mutex : [];
+    mutexMap.set(id, new Set(mutex));
+  }
+  const byPlaybook = new Map(); // playbookId -> array of warning messages
+  for (const [id, mset] of mutexMap.entries()) {
+    for (const other of mset) {
+      const otherSet = mutexMap.get(other);
+      if (!otherSet) continue; // unresolved-id warning is already emitted by checkCrossRefs
+      if (!otherSet.has(id)) {
+        const msg = `_meta.mutex: asymmetric mutex with "${other}" — "${other}" does not list "${id}" in its _meta.mutex. v0.13.0 will flip this to a hard error.`;
+        if (!byPlaybook.has(id)) byPlaybook.set(id, []);
+        byPlaybook.get(id).push(msg);
+      }
+    }
+  }
+  findings.push(byPlaybook);
+  return byPlaybook;
+}
+
 function main() {
   const opts = parseArgs(process.argv);
   const schema = readJson(SCHEMA_PATH);
@@ -408,6 +449,7 @@ function main() {
       playbookIds.add(pb.data._meta.id);
     }
   }
+  const mutexAsymmetries = checkMutexReciprocity(playbooks);
 
   let errored = 0;
   let warned = 0;
@@ -425,6 +467,9 @@ function main() {
       ...validate(pb.data, schema, 'playbook', label),
       ...checkCrossRefs(pb.data, ctx, playbookIds),
     ];
+    const reciprocityMsgs =
+      (pb.data && pb.data._meta && mutexAsymmetries.get(pb.data._meta.id)) || [];
+    for (const m of reciprocityMsgs) findings.push({ severity: 'warning', message: m });
     const effective = opts.strict
       ? findings.map((f) => ({ ...f, severity: 'error' }))
       : findings;
@@ -459,6 +504,7 @@ function main() {
 module.exports = {
   validate,
   checkCrossRefs,
+  checkMutexReciprocity,
   loadContext,
   loadPlaybooks,
   obligationKey,