@blamejs/exceptd-skills 0.18.16 → 0.18.18

package/lib/auto-discovery.js

@@ -185,8 +185,15 @@ function readCachedJson(cacheDir, source, id) {
   return parsed;
 }
 
-function extractNvdMetrics(payload) {
-  const vuln = payload?.vulnerabilities?.[0]?.cve;
+function extractNvdMetrics(payload, id) {
+  // Resolve the NVD vuln by id, not by position. vulnerabilities[0] blindly
+  // took the first record, so a cache entry keyed under `id` that held another
+  // CVE's response would attribute that CVE's CVSS/CWE/description to this id.
+  // When no id is supplied (legacy callers), fall back to the first record.
+  const cves = (payload?.vulnerabilities || []).map((v) => v?.cve).filter(Boolean);
+  const vuln = id
+    ? cves.find((c) => c.id && String(c.id).toUpperCase() === String(id).toUpperCase())
+    : cves[0];
   if (!vuln) return null;
   // Prefer the newest CVSS version (Primary within it) and normalize a bare
   // v2 vector to its canonical prefix so an auto-imported draft never carries
@@ -238,7 +245,7 @@ function extractEpss(payload, id) {
  */
 function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
   const id = String(kevEntry.cveID);
-  const nvd = nvdPayload ? extractNvdMetrics(nvdPayload) : null;
+  const nvd = nvdPayload ? extractNvdMetrics(nvdPayload, id) : null;
   const epss = epssPayload ? extractEpss(epssPayload, id) : null;
 
   const knownRansomware =

package/lib/collectors/ai-api.js

@@ -63,6 +63,16 @@ const AI_KEY_VALUE_RE = {
   openai: /OPENAI_API_KEY\s*[= ]\s*['"]?(sk-[A-Za-z0-9_-]+)/,
   anthropic: /ANTHROPIC_API_KEY\s*[= ]\s*['"]?(sk-ant-[A-Za-z0-9_-]+)/,
   huggingface: /(?:HUGGINGFACE_TOKEN|HF_TOKEN)\s*[= ]\s*['"]?(hf_[A-Za-z0-9]+)/,
+  // Azure/Google/Cohere keys carry no vendor prefix, so the captured value IS
+  // the entropy body. Without these, cleartextFpIndices found no value for an
+  // azure/google/cohere-only dotfile, returned an empty attestation, and the
+  // runner downgraded a real cleartext-key hit to inconclusive — the indicator
+  // fired then vanished for half the supported vendors. The 30-char entropy
+  // floor (the `: 30` else-branch below) and PLACEHOLDER_RE both apply, since
+  // the prefix-strip leaves these values unchanged.
+  azure: /AZURE_OPENAI(?:_API)?_KEY\s*[= ]\s*['"]?([A-Za-z0-9]{20,})/,
+  google: /(?:GOOGLE_API_KEY|GOOGLE_GENAI_API_KEY|GEMINI_API_KEY)\s*[= ]\s*['"]?([A-Za-z0-9_-]{20,})/,
+  cohere: /COHERE_API_KEY\s*[= ]\s*['"]?([A-Za-z0-9-]{30,})/,
 };
 const PLACEHOLDER_RE = /placeholder|example|redacted|dummy|x{4,}|0{6,}|test-/i;
 

package/lib/collectors/citation-hygiene.js

@@ -110,8 +110,50 @@ const CVE_CANONICAL_RE = /^CVE-\d{4}-\d{4,}$/;
 // RFC citation: `RFC 9404`, `RFC9404`, `RFC-9404`. Capture the number.
 const RFC_CITATION_RE = /RFC[\s-]?(\d{1,5})\b/gi;
 
-// Words that mark a catalog note as recording a rejected / disputed status.
-const REJECT_DISPUTE_RE = /\b(reject(?:ed|s|ion)?|disputed?|withdrawn)\b/i;
+// A catalog note records a rejected/disputed RECORD for THIS CVE only when a
+// reject/dispute/withdraw word refers to the citation's own record — not to a
+// CVSS *scoring* disagreement, a disclosure-coordination dispute, or a
+// DIFFERENT CVE the note merely mentions. A bare word-anywhere scan matched all
+// three, producing a false "citation to a rejected record" hit AND a false
+// __fp_checks[1] attestation (telling the runner not to downgrade), so a valid,
+// often actively-exploited CVE surfaced as a confirmed rejected/disputed
+// citation. `selfId` is the citation's own CVE id.
+function recordRejectedOrDisputed(note, selfId) {
+  if (!note) return false;
+  const self = String(selfId || "").toUpperCase();
+  const re = /\b(reject(?:ed|s|ion)?|disputed?|withdrawn)\b/gi;
+  // Qualifier nouns that make a "dispute" a disagreement about something OTHER
+  // than the record's validity (the score, the severity, the disclosure
+  // process, …). 'rejected'/'withdrawn' are record-level words and bypass this.
+  const QUALIFIER = /\b(cvss|scoring|score|severity|coordination|disclosure|methodolog\w*|attribution|naming|assignment|priorit\w*)\b/i;
+  // A "duplicate of / superseded by / replaced by / merged into / in favour of"
+  // construction names the REPLACEMENT cve — THIS record is still the rejected
+  // one, so a different cve appearing as that replacement must NOT suppress the
+  // flag (e.g. "this record was rejected as a duplicate of CVE-Y").
+  const REPLACEMENT_OF = /\b(?:duplicate|dup)\b[\s\w-]*\bof\b|\b(?:supersed\w+|replaced|merged)\b[\s\w-]*\b(?:by|into)\b|\bin\s+favou?r\s+of\b/i;
+  const otherCve = (s) => (s.match(/CVE-\d{4}-\d{4,}/gi) || []).some((c) => c.toUpperCase() !== self);
+  let m;
+  while ((m = re.exec(note)) !== null) {
+    const word = m[1].toLowerCase();
+    const before = note.slice(Math.max(0, m.index - 60), m.index);
+    const after = note.slice(re.lastIndex, re.lastIndex + 60);
+    // (a) A different cve BEFORE the word is the subject ("CVE-Y was rejected")
+    //     — the status is about that record, not this citation.
+    if (otherCve(before)) continue;
+    // (b) A different cve AFTER the word suppresses too, UNLESS it is the
+    //     replacement target of a duplicate-of/superseded-by construction, in
+    //     which case THIS record is the rejected one — keep it flagged.
+    if (otherCve(after) && !REPLACEMENT_OF.test(after)) continue;
+    // (c) A 'dispute(d)' qualified by a non-record noun is a disagreement about
+    //     that noun, not a record rejection.
+    if (word.startsWith("disput")) {
+      const lastTokens = before.trim().split(/[\s-]+/).slice(-3).join(" ");
+      if (QUALIFIER.test(lastTokens)) continue;
+    }
+    return true;
+  }
+  return false;
+}
 
 // Draft-language proximity for the (unflipped) draft-as-RFC heuristic.
 const DRAFT_LANGUAGE_RE = /\b(draft-[a-z0-9-]+|internet[- ]draft|work[- ]in[- ]progress|i-d\b)\b/i;
@@ -356,7 +398,7 @@ function collect({ cwd = process.cwd() } = {}) {
       // Well-formed. Cross-reference the catalog.
       if (cveKeys.has(full)) {
         const note = cveNotes.get(full) || "";
-        if (REJECT_DISPUTE_RE.test(note) && !illustrative) {
+        if (recordRejectedOrDisputed(note, full) && !illustrative) {
           hits["rejected-or-disputed-cve"].push({ file: f.rel, citation: full, line: cveLine });
         }
       } else if (catalogsLoaded && !illustrative) {
@@ -603,4 +645,4 @@ async function applyResolution(submission, opts = {}) {
   return out;
 }
 
-module.exports = { playbook_id: COLLECTOR_ID, collect, applyResolution };
+module.exports = { playbook_id: COLLECTOR_ID, collect, applyResolution, recordRejectedOrDisputed };

package/lib/collectors/cred-stores.js

@@ -84,7 +84,16 @@ function parseAwsCredentials(content) {
   const staticKeys = {};
   for (const [name, kv] of Object.entries(profiles)) {
     const hasKey = !!kv["aws_access_key_id"];
-    const hasFederation = !!(kv["sso_session"] || kv["credential_process"] || kv["role_arn"]);
+    // role_arn is NOT a federation marker for this predicate. A profile that
+    // carries a static aws_access_key_id (AKIA*) alongside a role_arn is the
+    // canonical source_profile/assume-role setup where the static key IS the
+    // long-lived credential that bootstraps the assumed role — a real static-key
+    // exposure. The playbook's aws-static-key-present predicate lists only
+    // sso_session / credential_process as federation; treating role_arn as
+    // federation here suppressed a genuinely-present IAM user key. A pure
+    // assume-role profile (role_arn, no own access key) is still excluded by the
+    // hasKey gate below.
+    const hasFederation = !!(kv["sso_session"] || kv["credential_process"]);
     if (hasKey && !hasFederation) {
       staticProfiles.push(name);
       staticKeys[name] = kv["aws_access_key_id"];

package/lib/collectors/mcp.js

@@ -120,7 +120,13 @@ function isPinnedNoIntegrity(server) {
     if (typeof tok !== "string") continue;
     // npm package@version (excluding scope name@version)
     if (/@[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+@\d+\.\d+\.\d+\b/.test(tok)) return true;
-    if (/\bpip\s+install\b/.test(tok)) continue;
+    // A `==X.Y.Z` pin (pip/uvx/poetry) with no integrity is the python analog
+    // of the npm pin above. A single-token launch command like
+    // `sh -c "pip install some-mcp==1.2.3"` carries the whole pip invocation in
+    // one token, so testing the token for `pip install` and `continue`-ing here
+    // skipped the `==version` check below for exactly the shape the comment
+    // says operators care about. A bare `pip install requests` (no `==`) can't
+    // match the pin regex, so checking every token is safe.
     if (/==\d+\.\d+\.\d+/.test(tok)) return true;
   }
   return false;

package/lib/collectors/runtime.js

@@ -341,6 +341,17 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   return {
     precondition_checks: {
       "linux-platform": true,
+      // The collector performs a read-only inventory directly via fs (reads
+      // /etc/sudoers, /etc/passwd, /proc/<pid>/status) and execs no commands,
+      // so the `exec-allowed` precondition ('permitted to execute read-only
+      // inventory commands') is satisfied by construction once the collection
+      // reaches at least one inventory source. The runner cannot mechanically
+      // resolve `agent_has_command_exec == true`, so without this attestation
+      // the on_fail=halt preflight blocked the canonical `collect runtime | run
+      // runtime` pipe even with valid evidence — the sibling fs-only cred-stores
+      // collector attests its own halt precondition the same way. Gated on
+      // readability so a fully-masked /proc+/etc scope reports it false.
+      "exec-allowed": Boolean(sudoersReadable || passwdContent != null || procWalkable || anyTpReadable),
     },
     artifacts,
     signal_overrides,

package/lib/collectors/secrets.js

@@ -488,7 +488,14 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   //   any .env / .env.* / .envrc with mode 0666 or 0664 (group/world writable)
   // i.e. group-write OR world-write bit set (mode & 0o022).
   const envFilePostures = process.platform === "win32" ? [] : envFiles.map(f => ({ file: f.rel, ...statPosture(f.full) }));
-  signal_overrides["world-writable-env-file"] = envFilePostures.some(p => p.error == null && (p.mode & 0o022) !== 0) ? "hit" : "miss";
+  // POSIX mode bits are unreadable on win32, so this posture cannot be checked
+  // there. OMIT the signal on Windows (mirroring cred-stores' credentials-file-
+  // bad-perms) so the runner returns `inconclusive` rather than a deterministic
+  // false `miss` for a check that physically cannot run. (The posture array is
+  // still declared — empty on win32 — for the SARIF per-indicator locations.)
+  if (process.platform !== "win32") {
+    signal_overrides["world-writable-env-file"] = envFilePostures.some(p => p.error == null && (p.mode & 0o022) !== 0) ? "hit" : "miss";
+  }
 
   // ssh-key-bad-perms predicate (per playbook):
   //   restricted to ssh-private-keys artifact + ~/.ssh/id_* paths
@@ -499,7 +506,11 @@ function collect({ cwd = process.cwd(), env = process.env, args = {} } = {}) {
   // (prodSshPrivateKeys) — matching ssh-private-key-block — so a fixture
   // key checked in under a test/ path doesn't raise a bad-perms posture.
   const sshKeyPostures = process.platform === "win32" ? [] : prodSshPrivateKeys.map(f => ({ file: f.rel, ...statPosture(f.full) }));
-  signal_overrides["ssh-key-bad-perms"] = sshKeyPostures.some(p => p.error == null && p.mode !== 0o600) ? "hit" : "miss";
+  // Same as world-writable-env-file: omit on win32 (mode bits unreadable) so the
+  // runner returns inconclusive instead of a forced false `miss`.
+  if (process.platform !== "win32") {
+    signal_overrides["ssh-key-bad-perms"] = sshKeyPostures.some(p => p.error == null && p.mode !== 0o600) ? "hit" : "miss";
+  }
 
   // Per-indicator file locations for every indicator flipped to "hit", so
   // a SARIF result points at the file carrying the secret / bad posture.

package/lib/cross-ref-api.js

@@ -303,13 +303,67 @@ function bySkill(skillName) {
   return { skill: skillName, summary_card: card, cve_refs: cveRefs, ttp_refs: ttpRefs };
 }
 
+// global-frameworks.json is keyed by REGION (EU/UK/AU/...), each with a nested
+// `frameworks: { SHORTKEY: {full_name, catalog_aliases?, ...} }` map. A flat
+// `global[frameworkId]` lookup therefore ALWAYS returned null — frameworkId is a
+// short key or a catalog display name, never a region — so framework_meta was
+// universally null. Walk the nested structure and match the requested id against
+// the short key, the full_name, or any catalog_alias (normalized), returning the
+// matched framework object annotated with its region + jurisdiction.
+function resolveFrameworkMeta(global, frameworkId) {
+  if (!global || frameworkId == null) return null;
+  const norm = (s) => String(s == null ? '' : s).toLowerCase().replace(/\([^)]*\)/g, '').replace(/[\s_-]/g, '');
+  const want = norm(frameworkId);
+  if (!want) return null;
+  for (const [region, rv] of Object.entries(global)) {
+    if (region === '_meta' || !rv || typeof rv !== 'object') continue;
+    const fws = rv.frameworks || {};
+    for (const [shortKey, fv] of Object.entries(fws)) {
+      if (!fv || typeof fv !== 'object') continue;
+      const aliases = Array.isArray(fv.catalog_aliases) ? fv.catalog_aliases.map(norm) : [];
+      if (shortKey === frameworkId ||
+          norm(shortKey) === want ||
+          (fv.full_name && norm(fv.full_name) === want) ||
+          aliases.some((a) => a && (a === want || a.includes(want) || want.includes(a)))) {
+        return { ...fv, _framework_key: shortKey, _region: region, _jurisdiction: rv.jurisdiction || null };
+      }
+    }
+  }
+  return null;
+}
+
 function byFramework(frameworkId) {
   const gaps = loadCatalog('framework-control-gaps.json');
   const global = loadCatalog('global-frameworks.json');
+  const fwMeta = resolveFrameworkMeta(global, frameworkId);
+  // Match gap rows by the framework's full LABEL SET, not just the literal id.
+  // The catalog stores a framework's gaps under labels (au-ism / AU ISM / ACSC
+  // ISM …) that diverge from its short key and full_name, so an exact
+  // `g.framework === frameworkId` match returned a gap set inconsistent with the
+  // (now alias-resolved) framework_meta — non-null metadata but a partial,
+  // sometimes empty, gap list. Resolve the same alias set used for the metadata
+  // and match any gap label (string or array element) against it.
+  const norm = (s) => String(s == null ? '' : s).toLowerCase().replace(/\([^)]*\)/g, '').replace(/[\s_-]/g, '');
+  const labels = new Set([norm(frameworkId)]);
+  if (fwMeta) {
+    if (fwMeta._framework_key) labels.add(norm(fwMeta._framework_key));
+    if (fwMeta.full_name) labels.add(norm(fwMeta.full_name));
+    for (const a of (Array.isArray(fwMeta.catalog_aliases) ? fwMeta.catalog_aliases : [])) labels.add(norm(a));
+  }
+  labels.delete('');
+  const labelMatch = (fw) => {
+    const n = norm(fw);
+    if (!n) return false;
+    for (const l of labels) if (n === l || n.includes(l) || l.includes(n)) return true;
+    return false;
+  };
   const matching = entries(gaps)
-    .filter(([, g]) => g.framework === frameworkId || g.framework === 'ALL')
+    .filter(([, g]) => {
+      if (g.framework === 'ALL') return true;
+      const fwList = Array.isArray(g.framework) ? g.framework : [g.framework];
+      return fwList.some(labelMatch);
+    })
     .map(([id, g]) => ({ id, ...g }));
-  const fwMeta = global[frameworkId] || null;
   return { framework: frameworkId, framework_meta: fwMeta, gaps: matching, gap_count: matching.length };
 }
 

package/lib/framework-gap.js

@@ -108,6 +108,17 @@ function lagScore(frameworkId, controlGaps, globalFrameworks) {
   const normalize = (s) => String(s).toLowerCase().replace(/[\s_-]/g, '');
   const idNorm = normalize(frameworkId);
   const nameNorm = frameworkData?.full_name ? normalize(frameworkData.full_name) : null;
+  // Data-driven aliases close the naming divergence between a framework's
+  // global-frameworks full_name and the (often different) labels the control-gap
+  // catalog uses for it — e.g. ASD_ISM's full_name is "Australian Signals
+  // Directorate Information Security Manual" but the catalog labels its 5 gaps
+  // "au-ism" / "ACSC ISM" / "Australian Government Information Security Manual",
+  // so neither nameNorm nor idNorm matched and lagScore reported 0 gaps. Aliases
+  // live in data/global-frameworks.json (catalog_aliases) so this generalizes to
+  // any future framework whose catalog label diverges from its name.
+  const aliasNorms = Array.isArray(frameworkData?.catalog_aliases)
+    ? frameworkData.catalog_aliases.map((a) => normalize(a)).filter(Boolean)
+    : [];
   const gaps = Object.entries(controlGaps).filter(([key, g]) => {
     if (key.startsWith('_')) return false;
     if (g.status !== 'open' || !g.framework) return false;
@@ -116,10 +127,17 @@ function lagScore(frameworkId, controlGaps, globalFrameworks) {
       const fwNorm = normalize(fw);
       if (nameNorm && fwNorm.includes(nameNorm)) return true;   // display-name match
       if (fwNorm.includes(idNorm)) return true;                 // short-key substring
+      if (aliasNorms.some((a) => a && (fwNorm.includes(a) || a.includes(fwNorm)))) return true; // catalog-label alias
     }
     if (normalize(key).startsWith(idNorm)) return true;         // gap-key prefix
     return false;
   });
+  // Observable backstop: a framework that EXISTS in global-frameworks resolving
+  // to zero catalog gaps is almost always a fresh naming divergence (a new
+  // catalog label not yet in catalog_aliases), not a genuinely gap-free
+  // framework. Surface it as a structured flag rather than a silent 0 so a
+  // regression is greppable in the breakdown instead of invisible.
+  const resolvedButZeroGaps = Boolean(frameworkData && gaps.length === 0);
 
   const universalGaps = Object.values(controlGaps).filter(g =>
     g.framework === 'ALL' && g.status === 'open'
@@ -149,7 +167,10 @@ function lagScore(frameworkId, controlGaps, globalFrameworks) {
       ai_coverage: { coverage: frameworkData?.ai_coverage ?? 'unknown', score: aiCoverageScore },
       pqc_coverage: { coverage: frameworkData?.pqc_coverage ?? 'unknown', score: pqcScore },
       universal_gaps: { count: universalGaps.length, score: universalGapScore },
-      framework_specific_gaps: gaps.length
+      framework_specific_gaps: gaps.length,
+      // True only when the framework resolves in global-frameworks yet matched
+      // zero catalog gaps — a likely naming divergence worth investigating.
+      framework_resolved_but_zero_gaps: resolvedButZeroGaps
     }
   };
 }

package/lib/playbook-runner.js

@@ -4137,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,
@@ -4152,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,
   };
 }