@blamejs/exceptd-skills 0.18.15 → 0.18.17

package/lib/playbook-runner.js

@@ -1994,14 +1994,26 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     const triggered = evalCondition(c.exception_generation.trigger_condition, closeEvalCtx, playbook);
     if (triggered) {
       const t = c.exception_generation.exception_template;
+      // Track unresolved ${placeholder} tokens the SAME way the draft_notification
+      // render does (missing_interpolation_vars). Exception-template tokens are
+      // operator-fill values (affected_host_count, compensating_controls,
+      // patch_available_status, …) that analyzeFindingShape does NOT supply and
+      // that operators rarely pre-stage on the standard `exceptd run` path, so the
+      // auditor-ready risk-acceptance language otherwise ships literal
+      // `<MISSING:…>` tokens with no machine-readable signal of which placeholders
+      // failed. Surface them as exception.missing_interpolation_vars (empty when
+      // all resolved) so a `ci`/JSON consumer — and the operator filling the
+      // exception — sees exactly what still needs a value.
+      const exMissing = [];
+      const findingShape = (() => { try { return analyzeFindingShape(analyzeResult); } catch { return {}; } })();
       exception = {
-        scope: interpolate(t.scope, { ...agentSignals, ...analyzeFindingShape(analyzeResult) }),
+        scope: interpolate(t.scope, { ...agentSignals, ...findingShape }, exMissing),
         duration: t.duration,
         compensating_controls: t.compensating_controls,
         risk_acceptance_owner: t.risk_acceptance_owner,
         auditor_ready_language: interpolate(t.auditor_ready_language, {
           ...agentSignals,
-          ...analyzeFindingShape(analyzeResult),
+          ...findingShape,
           framework_id: playbook.domain.frameworks_in_scope[0] || 'unspecified',
           control_id: analyzeResult.framework_gap_mapping?.[0]?.claimed_control || 'unspecified',
           ciso_name: agentSignals.ciso_name || '<CISO NAME>',
@@ -2010,8 +2022,16 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
           // same auditor-facing date.
           acceptance_date: (deterministic ? frozenEpoch : new Date().toISOString()).slice(0, 10),
           duration_expiry: agentSignals.duration_expiry || 'until vendor patch'
-        })
+        }, exMissing),
+        missing_interpolation_vars: exMissing,
       };
+      // Make the unresolved-placeholder gap observable to JSON/ci consumers, not
+      // just present on the exception object.
+      if (exMissing.length && Array.isArray(runOpts._runErrors)) {
+        pushRunError(runOpts._runErrors,
+          { kind: 'exception_unresolved_placeholders', placeholders: exMissing.slice() },
+          { dedupeKey: e => (e.placeholders || []).join(',') });
+      }
     }
   }
 
@@ -2330,12 +2350,23 @@ function vulnIdToUrn(id) {
 function buildCsafBranches(matchedCves, runOpts) {
   // Build a (vendor → product → Set<version>) map.
   const tree = new Map();
-  const addLeaf = (vendor, product, version) => {
+  // Track which CVE contributed each leaf so the emitted CSAFPID-N product_ids
+  // can be bound back into that CVE's vulnerabilities[].product_status — without
+  // this the branch tree's per-version products are referenced by nothing and a
+  // CSAF consumer correlating product_status to the tree resolves only the
+  // generic synthetic product. leafKey = vendor\0product\0version.
+  const leafKey = (vendor, product, version) => JSON.stringify([vendor, product, version]);
+  const cveLeaves = new Map(); // cve_id → Set<leafKey>
+  const addLeaf = (vendor, product, version, cveId) => {
     if (!vendor || !product || !version) return;
     if (!tree.has(vendor)) tree.set(vendor, new Map());
     const products = tree.get(vendor);
     if (!products.has(product)) products.set(product, new Set());
     products.get(product).add(version);
+    if (cveId) {
+      if (!cveLeaves.has(cveId)) cveLeaves.set(cveId, new Set());
+      cveLeaves.get(cveId).add(leafKey(vendor, product, version));
+    }
   };
 
   // Comparison / range operators that appear between a package name and a
@@ -2386,7 +2417,7 @@ function buildCsafBranches(matchedCves, runOpts) {
     if (Array.isArray(c.affected_products) && c.affected_products.length > 0) {
       for (const ap of c.affected_products) {
         if (ap && typeof ap === 'object' && ap.vendor && ap.product && ap.version) {
-          addLeaf(String(ap.vendor), String(ap.product), String(ap.version));
+          addLeaf(String(ap.vendor), String(ap.product), String(ap.version), c.cve_id);
         }
       }
       continue;
@@ -2396,7 +2427,7 @@ function buildCsafBranches(matchedCves, runOpts) {
     for (const comp of components) {
       const parsed = parseComponentString(comp);
       if (parsed) {
-        addLeaf(parsed.vendor, parsed.product, parsed.version);
+        addLeaf(parsed.vendor, parsed.product, parsed.version, c.cve_id);
       } else if (typeof comp === 'string' && comp.trim() && runOpts && Array.isArray(runOpts._runErrors)) {
         pushRunError(runOpts._runErrors, {
           kind: 'csaf_branch_unparseable',
@@ -2409,6 +2440,7 @@ function buildCsafBranches(matchedCves, runOpts) {
 
   // Sort + emit.
   const productIds = [];
+  const leafKeyToPid = new Map();
   let pidCounter = 0;
   const vendors = Array.from(tree.keys()).sort();
   const branches = vendors.map(vendor => {
@@ -2425,6 +2457,7 @@ function buildCsafBranches(matchedCves, runOpts) {
           branches: versions.map(version => {
             const pid = `CSAFPID-${pidCounter++}`;
             productIds.push({ vendor, product, version, product_id: pid });
+            leafKeyToPid.set(leafKey(vendor, product, version), pid);
             return {
               category: 'product_version',
               name: version,
@@ -2438,7 +2471,15 @@ function buildCsafBranches(matchedCves, runOpts) {
       }),
     };
   });
-  return { branches, productIds };
+  // Per-CVE CSAFPID binding so the caller can add the version leaves to each
+  // vulnerability's product_status.known_affected.
+  const cveProductIds = {};
+  for (const [cveId, keys] of cveLeaves.entries()) {
+    const pids = [];
+    for (const k of keys) { const pid = leafKeyToPid.get(k); if (pid) pids.push(pid); }
+    if (pids.length) cveProductIds[cveId] = pids.sort();
+  }
+  return { branches, productIds, cveProductIds };
 }
 
 // Slugify a string into a URN-safe segment (RFC 8141 NSS). Empty input →
@@ -2545,6 +2586,24 @@ function sarifLocationsForIndicator(playbook, indicator) {
   return [{ physicalLocation: { artifactLocation: { uri: candidates[0] } } }];
 }
 
+// Locations for a finding-class SARIF result, with a guaranteed non-empty
+// fallback. sarifLocationsForIndicator returns a PHYSICAL location only when the
+// agent supplied evidence_locations or the playbook's look-artifact source is a
+// bare path token; the dominant catalog shape is a prose / glob / shell-command
+// source (which carries whitespace and is rejected by looksLikePath), so the
+// physical fallback is null for ~most playbooks. A SARIF result with no
+// `locations[]` is silently DROPPED by GitHub Code Scanning — so a result with
+// no concrete file still gets a `logicalLocations` entry naming its rule, which
+// is SARIF-conformant (§3.33), keeps the finding attributable + visible in the
+// alerts list and in SARIF viewers, and is honest (there is no physical file to
+// point at when the agent supplied no evidence location). Physical location is
+// always preferred when available.
+function sarifResultLocations(playbook, indicator, fqRuleId) {
+  const phys = sarifLocationsForIndicator(playbook, indicator);
+  if (phys && phys.length) return phys;
+  return [{ logicalLocations: [{ name: fqRuleId, fullyQualifiedName: fqRuleId, kind: 'rule' }] }];
+}
+
 // Resolve the package version once per process so CSAF tracking.generator
 // can name the engine that emitted the advisory. Best-effort read — bundle
 // emission must not crash if package.json is missing (e.g. exotic install).
@@ -2783,6 +2842,11 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     };
     const CSAF_CVE_RE = /^CVE-\d{4}-\d{4,}$/;
 
+    // Build the product-tree branches up front so each CVE's per-version CSAFPID
+    // leaves can be bound into its product_status.known_affected (and the same
+    // tree reused for product_tree below — buildCsafBranches is not re-run).
+    const csafProductTree = buildCsafBranches(analyze.matched_cves || [], runOpts);
+
     const cveVulns = analyze.matched_cves.map(c => {
       const isFixed = c.vex_status === 'fixed';
       const remediations = [{
@@ -2867,7 +2931,17 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         scores,
         threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: `Active exploitation confirmed${c.cisa_kev ? ' (CISA KEV)' : ''}.` }] : [],
         remediations,
-        product_status: isFixed ? { fixed: [productId] } : { known_affected: [productId] }
+        // Bind this CVE's per-version CSAFPID leaves (from the product tree) into
+        // known_affected, so a CSAF consumer correlating product_status back to
+        // the branches tree resolves the real affected versions, not only the
+        // opaque synthetic product. The leaves are parsed from affected_products
+        // / affected_versions — VULNERABLE version ranges — so they belong ONLY
+        // under known_affected. The VEX-fixed disposition keeps just the synthetic
+        // target product under `fixed`; adding affected ranges there would
+        // mislabel vulnerable versions as fixed releases.
+        product_status: isFixed
+          ? { fixed: [productId] }
+          : { known_affected: [productId, ...(csafProductTree.cveProductIds[c.cve_id] || [])] }
       };
       // route by id shape.
       if (idIsCve) {
@@ -3054,7 +3128,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           // from catalog data. CSAF §3.1.5.1 makes branches[] strongly
           // recommended because NVD / ENISA / Red Hat dashboards render the
           // affected-product list off the branches tree, not full_product_names[].
-          const { branches } = buildCsafBranches(analyze.matched_cves || [], runOpts);
+          const branches = csafProductTree.branches;
           const tree = { full_product_names: fullProductNames };
           if (branches.length > 0) tree.branches = branches;
           return tree;
@@ -3109,7 +3183,6 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     // (passing a null indicator skips the per-indicator evidence-locations
     // branch). Without any `locations`, GitHub Code Scanning silently DROPS
     // these results — the highest-severity result class would never surface.
-    const cveFallbackLocs = sarifLocationsForIndicator(playbook, null);
     const cveResults = analyze.matched_cves.map(c => {
       const result = {
         ruleId: `${rulePrefix}${c.cve_id}`,
@@ -3125,12 +3198,15 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           blast_radius_score: analyze.blast_radius_score,
         }),
       };
-      if (cveFallbackLocs) result.locations = cveFallbackLocs;
+      // Always carry a location (physical when known, else a rule-scoped
+      // logicalLocations fallback) so GitHub Code Scanning does not drop the
+      // highest-severity result class.
+      result.locations = sarifResultLocations(playbook, null, result.ruleId);
       return result;
     });
     const indicatorHits = (analyze._detect_indicators || []).filter(i => i.verdict === 'hit');
     const indicatorResults = indicatorHits.map(i => {
-      const locs = sarifLocationsForIndicator(playbook, i);
+      const locs = sarifResultLocations(playbook, i, `${rulePrefix}${i.id}`);
       const result = {
         ruleId: `${rulePrefix}${i.id}`,
         level: i.deterministic ? 'error' : (i.confidence === 'high' ? 'warning' : 'note'),
@@ -3143,7 +3219,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           attack_ref: i.attack_ref,
         }),
       };
-      if (locs) result.locations = locs;
+      result.locations = locs; // always present (physical or logical fallback)
       return result;
     });
     const gapResults = (analyze.framework_gap_mapping || []).map((g, idx) => ({
@@ -4061,6 +4137,36 @@ function canonicalStringify(v, _depth = 0) {
   return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalStringify(v[k], _depth + 1)).join(',') + '}';
 }
 
+// Re-key an artifacts map by the stable indicator id each artifact was bound to
+// (recovered by inverting _signal_origins: indicator-id -> observation-key), so
+// the evidence_hash reflects the evidence VALUE + its stable binding rather than
+// the operator's free-text observation label. Without this, two submissions with
+// identical (indicator, value) evidence under different observation keys
+// (obs-kver vs x1) hashed differently and attest/reattest reported false drift —
+// the attest diff re-keys the COMPARISON (bin/exceptd.js); the hash itself was
+// not covered. Collision-safe (mirrors that helper): re-key only when the stable
+// id is not already a DISTINCT original key and has not been claimed by an
+// earlier entry, else keep the original key so no artifact is silently dropped.
+function _rekeyArtifactsByStableId(artifacts, signalOrigins) {
+  // The sole caller (extractSubmissionForHash) only invokes this inside
+  // `if (sub.artifacts && typeof sub.artifacts === 'object')`, so `artifacts`
+  // is always a non-null object — guard only on the re-key map being usable.
+  if (!signalOrigins || typeof signalOrigins !== 'object') return artifacts;
+  const obsKeyToIndicator = {};
+  for (const [indicatorId, obsKey] of Object.entries(signalOrigins)) {
+    if (typeof obsKey === 'string') obsKeyToIndicator[obsKey] = indicatorId;
+  }
+  const originalKeys = new Set(Object.keys(artifacts));
+  const out = {};
+  for (const [k, v] of Object.entries(artifacts)) {
+    const mapped = obsKeyToIndicator[k];
+    const stable = (mapped && mapped !== k && !originalKeys.has(mapped)
+      && !Object.prototype.hasOwnProperty.call(out, mapped)) ? mapped : k;
+    out[stable] = v;
+  }
+  return out;
+}
+
 /**
  * Pick the operator-meaningful fields out of the normalized submission
  * for hashing. captured_at, _signal_origins, _signal_origins_collisions,
@@ -4076,15 +4182,20 @@ function extractSubmissionForHash(sub) {
   // optional indicator binding) is what matters for "did the operator
   // submit the same evidence?".
   if (sub.artifacts && typeof sub.artifacts === 'object') {
-    pick.artifacts = {};
+    const stripped = {};
     for (const [k, v] of Object.entries(sub.artifacts)) {
       if (v && typeof v === 'object') {
         const { captured_at, _captured_at, ...rest } = v;
-        pick.artifacts[k] = rest;
+        stripped[k] = rest;
       } else {
-        pick.artifacts[k] = v;
+        stripped[k] = v;
       }
     }
+    // Re-key by the stable indicator id so the digest reflects the evidence
+    // VALUE + its binding, never the operator's free-text observation label.
+    // Identical (indicator, value) evidence under different observation keys
+    // must produce the SAME evidence_hash / submission_digest / session_id.
+    pick.artifacts = _rekeyArtifactsByStableId(stripped, sub._signal_origins);
   }
   if (sub.signal_overrides && typeof sub.signal_overrides === 'object') {
     pick.signal_overrides = sub.signal_overrides;

package/lib/prefetch.js

@@ -39,7 +39,7 @@
 const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
-const { JobQueue } = require("./job-queue");
+const { JobQueue, isRetryable } = require("./job-queue");
 
 const ROOT = path.join(__dirname, "..");
 const DEFAULT_CACHE = path.join(ROOT, ".cache", "upstream");
@@ -220,11 +220,21 @@ function errorBudget(maxErrors, planned) {
 }
 
 // Decide prefetch's 0-vs-1 exit code from a completed run. Per-entry fetch
-// errors are counted only after the job queue exhausts its retries, so they
-// are genuine failures — but a best-effort cache warm should tolerate a few
-// transient upstream misses. `opts.maxErrors` is the budget (default 0, so any
-// error exits 1 — the strict contract a manual operator expects). Fatal
-// errors (bad flags, an unhandled throw) are handled in main() and exit 2.
+// errors are counted only after the job queue exhausts its retries. They split
+// into two classes that mean very different things for a best-effort cache
+// warm:
+//   - HARD errors (404/410/parse failure/4xx-not-429) are real data faults.
+//     These count toward `opts.maxErrors` (default 0, so any hard error exits
+//     1 — the strict contract a manual operator expects).
+//   - TRANSIENT errors (HTTP 408/425/429/5xx + ETIMEDOUT/ECONNRESET et al that
+//     exhausted their retry budget) are the upstream throttling us, not a data
+//     fault. They are surfaced in the summary and deferred to the next run
+//     (where the entries that DID land this run are fresh-skipped, freeing rate
+//     budget for the throttled ones) — they never fail the run on their own.
+// Without the split, a daily NVD rate-limit on a subset of CVEs hard-failed the
+// whole scheduled refresh and skipped the auto-PR every single run, since the
+// ephemeral runner cache restarts cold each time and re-hits the same throttle.
+// Fatal errors (bad flags, an unhandled throw) are handled in main() and exit 2.
 function exitCodeForResult(result, opts = {}) {
   const errors = (result && result.errors) || 0;
   if (errors === 0) return 0;
@@ -232,16 +242,22 @@ function exitCodeForResult(result, opts = {}) {
   // and nothing already fresh in the cache, yet errors recorded — is entirely
   // unreachable, and the refresh would silently skip it. A dead KEV feed is
   // only one error (well under any global budget) but means the run missed
-  // every new KEV flag. Fail regardless of the budget so a single fully-dead
-  // feed can't pass quietly.
+  // every new KEV flag. Fail regardless of the budget OR error class so a
+  // single fully-dead feed (incl. an NVD that 429s/503s every single request)
+  // can't pass quietly.
   const bySource = (result && result.by_source) || {};
   for (const s of Object.values(bySource)) {
     if (s && (s.errors || 0) > 0 && (s.fetched || 0) === 0 && (s.skipped_fresh || 0) === 0) {
       return 1;
     }
   }
+  // Only HARD errors gate the exit code against the budget. Back-compat: a
+  // result built without the split (errors_hard undefined) treats every error
+  // as hard, preserving the prior strict behavior for callers/tests that
+  // construct a bare { errors } result.
+  const hardErrors = (result && result.errors_hard != null) ? result.errors_hard : errors;
   const budget = errorBudget(opts.maxErrors, plannedCount(result));
-  return errors > budget ? 1 : 0;
+  return hardErrors > budget ? 1 : 0;
 }
 
 // One-line run summary. When a run has errors, names the per-source counts so
@@ -254,6 +270,12 @@ function formatSummary(result, opts = {}) {
       .map(([name, s]) => `${name}=${s.errors}`);
     if (parts.length) line += ` [${parts.join(", ")}]`;
   }
+  // Name the transient vs hard split when present so a large error count that
+  // is purely upstream throttling reads as "throttled — retried, deferred to
+  // next run" rather than a silent data failure. Only hard errors gate exit 1.
+  if (result.errors > 0 && result.errors_transient != null && result.errors_hard != null) {
+    line += ` (${result.errors_transient} transient/throttled, ${result.errors_hard} hard)`;
+  }
   if (opts.noNetwork) line += " (dry-run)";
   return line;
 }
@@ -275,8 +297,11 @@ Options:
   --no-network        report-only; list what would be fetched.
   --cache-dir <path>  override cache root (default .cache/upstream).
   --quiet             suppress per-entry log lines.
-  --max-errors <n|n%> tolerate up to n (or n% of planned) per-entry fetch
-                      errors before exit 1. Default: 0 (any error exits 1).
+  --max-errors <n|n%> tolerate up to n (or n% of planned) HARD per-entry fetch
+                      errors before exit 1. Default: 0 (any hard error exits 1).
+                      Transient errors (rate-limit / timeout / 5xx that
+                      exhausted retries) never fail the run on their own — they
+                      are surfaced in the summary and retried on the next run.
                       A fully-dead source still exits 1 regardless of budget.
 
 Use NVD_API_KEY / GITHUB_TOKEN env vars to lift rate limits.
@@ -599,6 +624,12 @@ function authHeadersForSource(source) {
 
 async function prefetch(options = {}) {
   const opts = { maxAgeMs: 24 * 3600 * 1000, source: null, force: false, noNetwork: false, cacheDir: DEFAULT_CACHE, quiet: false, ...options };
+  // Honor the global air-gap switch for programmatic callers too. parseArgs
+  // applies EXCEPTD_AIR_GAP for the CLI path, but a direct prefetch({...}) call
+  // bypasses parseArgs — so without this guard an air-gapped host that imports
+  // and calls prefetch() would egress live. Bind it here, at the function that
+  // actually issues the fetches, covering both the CLI and exported-API callers.
+  if (process.env.EXCEPTD_AIR_GAP === "1" || opts.airGap) opts.noNetwork = true;
   const ctx = loadCtx();
   // Distinguish "operator omitted --source" (resolve to all sources, the
   // documented default) from "operator passed --source but it resolved to
@@ -659,8 +690,8 @@ async function prefetch(options = {}) {
   log(`Cache dir: ${path.relative(ROOT, opts.cacheDir)}`);
   log(`Max age:   ${(opts.maxAgeMs / 3_600_000).toFixed(1)}h${opts.force ? "  (forced)" : ""}`);
 
-  const result = { fetched: 0, skipped_fresh: 0, errors: 0, by_source: {} };
-  for (const s of chosen) result.by_source[s] = { fetched: 0, skipped_fresh: 0, errors: 0 };
+  const result = { fetched: 0, skipped_fresh: 0, errors: 0, errors_transient: 0, errors_hard: 0, by_source: {} };
+  for (const s of chosen) result.by_source[s] = { fetched: 0, skipped_fresh: 0, errors: 0, errors_transient: 0, errors_hard: 0 };
 
   if (opts.noNetwork) {
     for (const item of plan) {
@@ -756,10 +787,25 @@ async function prefetch(options = {}) {
       .catch((err) => {
         result.errors++;
         result.by_source[item.source].errors++;
+        // Classify the post-retry error. Transient iff the job queue would
+        // have retried it (the same isRetryable classifier the queue used):
+        // HTTP 408/425/429/5xx + ETIMEDOUT/ECONNRESET et al — the upstream
+        // throttling/timing-out, not a data fault. Anything else (404/410/
+        // parse failure) is hard. Only hard errors gate the exit code; a
+        // best-effort warm tolerates transient throttling and retries it on
+        // the next run. The split is surfaced in the summary so nothing hides.
+        const transient = isRetryable(err);
+        if (transient) {
+          result.errors_transient++;
+          result.by_source[item.source].errors_transient++;
+        } else {
+          result.errors_hard++;
+          result.by_source[item.source].errors_hard++;
+        }
         // Errors go to stderr unconditionally — they are diagnostics, not the
         // per-entry success chatter --quiet suppresses. A CI run with --quiet
-        // still surfaces which source/id failed.
-        console.error(`  [${item.source}] ${item.id} — error: ${err.message}`);
+        // still surfaces which source/id failed and whether it was transient.
+        console.error(`  [${item.source}] ${item.id} — ${transient ? "transient" : "hard"} error: ${err.message}`);
       });
   });
 

package/lib/refresh-external.js

@@ -1023,7 +1023,13 @@ function epssDiffFromCache(ctx) {
   for (const id of cves) {
     const payload = readCachedJson(ctx.cacheDir, "epss", id, { forceStale: ctx.forceStale });
     if (!payload) { errors++; continue; }
-    const row = (payload.data || []).find((r) => r?.cve === id) || (payload.data || [])[0];
+    // Match the EPSS row by id. The old `|| data[0]` blanket fallback
+    // attributed a DIFFERENT CVE's score to this id whenever the cache entry
+    // keyed under `id` actually held another CVE's payload. Accept the
+    // single-row fallback ONLY when that row carries no cve key (a keyless
+    // legacy payload), never a row naming a different CVE.
+    let row = (payload.data || []).find((r) => r?.cve === id);
+    if (!row && (payload.data || []).length === 1 && (payload.data || [])[0]?.cve == null) row = (payload.data || [])[0];
     if (!row) continue;
     const score = row.epss != null ? Number(row.epss) : null;
     const pct = row.percentile != null ? Number(row.percentile) : null;
@@ -1051,7 +1057,15 @@ function nvdDiffFromCache(ctx) {
   for (const id of cves) {
     const payload = readCachedJson(ctx.cacheDir, "nvd", id, { forceStale: ctx.forceStale });
     if (!payload) { errors++; continue; }
-    const vuln = payload.vulnerabilities?.[0]?.cve;
+    // Resolve the NVD vuln by id, not by position. vulnerabilities[0] blindly
+    // took the first record, attributing a DIFFERENT CVE's CVSS to this id when
+    // the cache entry keyed under `id` held another CVE's response.
+    const vulnCves = (payload.vulnerabilities || []).map((v) => v?.cve).filter(Boolean);
+    let vuln = vulnCves.find((c) => c.id && String(c.id).toUpperCase() === id.toUpperCase());
+    // Keyless single-record fallback: a single vulnerability whose cve carries
+    // no id can't be a mismatch — the id-keyed cache file IS the binding — so
+    // use it. A record whose id names a DIFFERENT cve is still rejected.
+    if (!vuln && vulnCves.length === 1 && vulnCves[0].id == null) vuln = vulnCves[0];
     if (!vuln) continue;
     // Prefer the newest CVSS version NVD publishes (Primary within that
     // version), and normalize a bare v2 vector to its canonical prefix.

package/lib/scoring.js

@@ -520,7 +520,22 @@ function compare(cveId, catalog, opts) {
     if (entry.cisa_kev) driving.push('CISA KEV (+25)');
     if (entry.poc_available) driving.push('public PoC (+20)');
     if (entry.ai_discovered || entry.ai_assisted_weaponization) driving.push('AI-discovered (+15 weaponization)');
-    if (String(entry.active_exploitation || '').trim().toLowerCase() === 'confirmed') driving.push('confirmed exploitation (+20)');
+    // active_exploitation via the SAME ladder scoreCustom uses, so suspected
+    // (+10) and unknown (+5) are listed with their actual contribution rather
+    // than only 'confirmed' (+20). The bare confirmed-only test dropped every
+    // suspected/unknown driver — so the enumerated factors summed to less than
+    // the delta, or (on a purely suspected/blast-driven entry) to nothing,
+    // leaving a dangling "driving delta: .".
+    const ae = resolveActiveExploitation(entry.active_exploitation);
+    if (ae.multiplier > 0) {
+      driving.push(`${ae.normalised} exploitation (+${Math.round(RWEP_WEIGHTS.active_exploitation * ae.multiplier)})`);
+    }
+    // blast_radius contributes its raw value (0..30) to RWEP but never appeared
+    // in the driver list, so a blast-driven delta showed a higher RWEP with no
+    // stated cause. List the clamped contribution when positive.
+    const blastRaw = Number((entry.rwep_factors || {}).blast_radius);
+    const blast = Number.isFinite(blastRaw) ? Math.max(0, Math.min(RWEP_WEIGHTS.blast_radius, blastRaw)) : 0;
+    if (blast > 0) driving.push(`blast radius (+${Math.round(blast)})`);
     // Mirror scoreCustom's rebootFactor EXACTLY: the +5 reboot weight is added
     // whenever a reboot is required, regardless of live_patch_available (a live
     // patch is a temporary workaround; the full-remediation window still extends
@@ -529,7 +544,9 @@ function compare(cveId, catalog, opts) {
     // delta on any entry that both requires a reboot AND has a live patch
     // available, hiding a driver the score actually counted.
     if (entry.reboot_required || entry.patch_required_reboot) driving.push('reboot required (+5)');
-    explanation += driving.join(', ');
+    // A positive delta with no enumerated driver still names the structural
+    // cause instead of a dangling "driving delta: .".
+    explanation += driving.length ? driving.join(', ') : 'blast magnitude / structural RWEP factors';
     explanation += '. Framework patch SLAs calibrated to CVSS are insufficient for this CVE.';
   } else if (delta < -10) {
     explanation = `RWEP lower than CVSS equivalent. Mitigating factors: `;
@@ -538,7 +555,9 @@ function compare(cveId, catalog, opts) {
     if (entry.live_patch_available) mitigating.push('live patch available (-10)');
     if (!entry.poc_available) mitigating.push('no public PoC');
     if (!entry.cisa_kev) mitigating.push('not CISA KEV');
-    explanation += mitigating.join(', ');
+    // A negative delta with no enumerated mitigator still names the structural
+    // cause (high CVSS base vs. a modest RWEP) instead of a dangling list.
+    explanation += mitigating.length ? mitigating.join(', ') : 'high CVSS base vs. a modest RWEP (low blast radius / no exploitation signal)';
   } else {
     explanation = 'CVSS and RWEP are broadly aligned for this CVE.';
   }

package/lib/source-ghsa.js

@@ -49,11 +49,14 @@ function ghsaResponseCapBytes() {
  * local value has gone null. Mirrors lib/source-osv.js. Finding 9.
  */
 const FIELD_DROPPED_WATCH = Object.freeze([
+  // Only fields the upstream feed actually populates can legitimately "drop"
+  // from populated -> null on a re-import. active_exploitation / ai_discovered /
+  // poc_available are EDITORIAL (curated by hand, never upstream-sourced), so
+  // the normalize step always nulls them — watching them flagged a field_dropped
+  // "regression" on every single curated re-import. Restrict the watch to the
+  // upstream-sourced fields.
   "cvss_score",
   "cisa_kev_pending",
-  "active_exploitation",
-  "ai_discovered",
-  "poc_available",
 ]);
 
 /**
@@ -460,12 +463,17 @@ async function buildDiff(ctx) {
       source: "ghsa",
     });
   }
+  // diffs holds BOTH _new_entry and field_dropped records — count them
+  // separately so the summary doesn't mislabel field-dropped regressions as
+  // brand-new CVE IDs.
+  const newCount = diffs.filter((d) => d.field === "_new_entry").length;
+  const droppedCount = diffs.filter((d) => d.variant === "field_dropped").length;
   return {
     status: "ok",
     diffs,
     errors: 0,
     ghsa_only_skipped: ghsaOnlySkipped,
-    summary: `GHSA returned ${result.advisories.length} reviewed advisories; ${diffs.length} new CVE ID(s) not yet in local catalog, ${ghsaOnlySkipped} ghsa_only_skipped.`,
+    summary: `GHSA returned ${result.advisories.length} reviewed advisories; ${newCount} new CVE ID(s) not yet in local catalog, ${droppedCount} field-dropped regression(s), ${ghsaOnlySkipped} ghsa_only_skipped.`,
     rate_limit: result.rate_limit || null,
   };
 }

package/lib/source-osv.js

@@ -95,11 +95,13 @@ const OSV_ID_PREFIXES = [
  * fields here MUST be ones the editorial review process can re-source.
  */
 const FIELD_DROPPED_WATCH = Object.freeze([
+  // Only fields the upstream feed actually populates can legitimately "drop"
+  // from populated -> null on a re-import. active_exploitation / ai_discovered /
+  // poc_available are EDITORIAL (curated by hand, never upstream-sourced), so
+  // the normalize step always nulls them — watching them flagged a field_dropped
+  // "regression" on every curated re-import. Restrict to upstream-sourced fields.
   "cvss_score",
   "cisa_kev_pending",
-  "active_exploitation",
-  "ai_discovered",
-  "poc_available",
 ]);
 
 /**
@@ -942,7 +944,12 @@ async function buildDiff(ctx) {
     });
   }
   const errors = unreachable + normalizeErrors;
-  const summary = `OSV fetched ${ids.length} id(s); ${diffs.length} new entry diff(s), ${unreachable} unreachable, ${normalizeErrors} normalize-rejected, ${ghsaOnlySkipped} ghsa_only_skipped.`;
+  // diffs holds BOTH _new_entry and field_dropped records — count them
+  // separately so the summary doesn't mislabel field-dropped regressions as
+  // brand-new entries.
+  const newCount = diffs.filter((d) => d.field === "_new_entry").length;
+  const droppedCount = diffs.filter((d) => d.variant === "field_dropped").length;
+  const summary = `OSV fetched ${ids.length} id(s); ${newCount} new entry diff(s), ${droppedCount} field-dropped regression(s), ${unreachable} unreachable, ${normalizeErrors} normalize-rejected, ${ghsaOnlySkipped} ghsa_only_skipped.`;
   return {
     status: errors === 0 ? "ok" : errors === ids.length ? "unreachable" : "partial",
     diffs,