@blamejs/exceptd-skills 0.12.13 → 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;
 }
 
@@ -99,31 +172,96 @@ function scoreCustom(factors, opts) {
     blast_radius = 0,
     patch_available = false,
     live_patch_available = false,
-    reboot_required = false
+    reboot_required = false,
+    // v0.12.15 (audit J F9): the CVE catalog field is `patch_required_reboot`
+    // but scoreCustom historically expected `reboot_required`. validate()
+    // already aliases at the call site; accept either spelling here so a
+    // direct caller passing the catalog entry doesn't silently lose the
+    // reboot factor.
+    patch_required_reboot,
   } = factors || {};
+  const rebootFactor = (reboot_required === true) || (patch_required_reboot === true);
 
   let score = 0;
   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;
-  // Clamp blast_radius into the weight-ceiling band [0, RWEP_WEIGHTS.blast_radius]
-  // before adding. Out-of-range values still produce a clamped contribution but
-  // validateFactors() surfaces the anomaly so operators see the unit error.
-  const brClamped = Math.max(0, Math.min(RWEP_WEIGHTS.blast_radius, typeof blast_radius === 'number' ? blast_radius : 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`
+  // 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;
+  const brClamped = Math.max(0, Math.min(RWEP_WEIGHTS.blast_radius, brRaw));
   score += brClamped;
   score += patch_available ? RWEP_WEIGHTS.patch_available : 0;
   score += live_patch_available ? RWEP_WEIGHTS.live_patch_available : 0;
-  score += reboot_required ? RWEP_WEIGHTS.reboot_required : 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;
 
-  const clamped = Math.min(100, Math.max(0, 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' };
@@ -133,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)');
@@ -153,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)');
@@ -165,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) {
@@ -209,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/source-ghsa.js

@@ -26,6 +26,7 @@
 
 const https = require("https");
 const fs = require("fs");
+const { withRetry } = require("../vendor/blamejs/retry.js");
 
 const GHSA_HOST = "api.github.com";
 const GHSA_PATH = "/advisories?per_page=50&type=reviewed&sort=published&direction=desc";
@@ -33,40 +34,93 @@ const REQUEST_TIMEOUT_MS = 10000;
 const USER_AGENT = "exceptd-security/source-ghsa (+https://exceptd.com)";
 
 /**
- * Fetch a page of advisories (default: latest 50).
+ * Field-dropped watch set — fields the buildDiff regression-detector
+ * watches when the upstream still has an entry but a previously-populated
+ * local value has gone null. Mirrors lib/source-osv.js. Finding 9.
+ */
+const FIELD_DROPPED_WATCH = Object.freeze([
+  "cvss_score",
+  "cisa_kev_pending",
+  "active_exploitation",
+  "ai_discovered",
+  "poc_available",
+]);
+
+/**
+ * Return true when the runtime context requests air-gap mode. Sources MUST
+ * refuse network calls when this is set — fall through to fixture or return
+ * a structured `air-gap: no fixture available` error so the operator sees
+ * an explicit refusal, not a silent network attempt. Mirrors source-osv.
+ */
+function isAirGap(opts) {
+  if (opts && opts.airGap) return true;
+  if (process.env.EXCEPTD_AIR_GAP === "1") return true;
+  return false;
+}
+
+/**
+ * Read EXCEPTD_GHSA_FIXTURE and return a structured envelope. Finding 5:
+ * mirror the OSV-source convention so a fixture file containing `null`,
+ * a number, or a string at its root doesn't slip through as an empty
+ * advisories array — the strict catalog validator would later swallow the
+ * resulting drift as "no advisories returned" instead of surfacing it as
+ * a fixture configuration error. Returns:
  *
- * Returns:
- *   { ok: true,  advisories: [...], source: "github-api" | "fixture", rate_limit?: { remaining, reset } }
- *   { ok: false, error, source: "offline" }
+ *   null                                          when env var is unset
+ *   { ok: true, advisories: [...], source }       on success
+ *   { ok: false, error, source: "offline" }       on any failure
  */
-async function fetchAdvisories({ timeoutMs = REQUEST_TIMEOUT_MS, path = GHSA_PATH, token = null } = {}) {
-  if (process.env.EXCEPTD_GHSA_FIXTURE) {
-    try {
-      const arr = JSON.parse(fs.readFileSync(process.env.EXCEPTD_GHSA_FIXTURE, "utf8"));
-      return { ok: true, advisories: Array.isArray(arr) ? arr : [arr], source: "fixture" };
-    } catch (e) {
-      return { ok: false, error: `fixture: ${e.message}`, source: "offline" };
-    }
+function readFixture() {
+  const fp = process.env.EXCEPTD_GHSA_FIXTURE;
+  if (!fp) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(fp, "utf8");
+  } catch (e) {
+    return { ok: false, error: `fixture: ${e.message}`, source: "offline" };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return { ok: false, error: `fixture: ${e.message}`, source: "offline" };
   }
+  if (parsed == null || typeof parsed !== "object") {
+    return { ok: false, error: `fixture: invalid root shape (got ${typeof parsed}); expected GHSA advisory object or array`, source: "offline" };
+  }
+  return { ok: true, advisories: Array.isArray(parsed) ? parsed : [parsed], source: "fixture" };
+}
 
-  return new Promise((resolve) => {
-    const headers = {
-      "Accept": "application/vnd.github+json",
-      "User-Agent": USER_AGENT,
-      "X-GitHub-Api-Version": "2022-11-28",
-    };
-    if (token || process.env.GITHUB_TOKEN) {
-      headers.Authorization = `Bearer ${token || process.env.GITHUB_TOKEN}`;
-    }
+/**
+ * One HTTPS GET against api.github.com. Throws on retryable conditions so
+ * withRetry's default classifier (HTTP 408/425/429/5xx + ECONNRESET et al)
+ * picks them up; resolves to a structured envelope on permanent conditions.
+ */
+function ghsaRequestOnce({ path, headers, timeoutMs }) {
+  return new Promise((resolve, reject) => {
     const req = https.get({
       host: GHSA_HOST,
       path,
       headers,
       timeout: timeoutMs,
     }, (res) => {
-      if (res.statusCode !== 200) {
+      const status = res.statusCode;
+      if (status === 429 || status === 503 ||
+          (status >= 500 && status <= 599) ||
+          status === 408 || status === 425) {
         res.resume();
-        return resolve({ ok: false, error: `GHSA returned HTTP ${res.statusCode}`, source: "offline" });
+        const err = new Error(`GHSA returned HTTP ${status}`);
+        err.statusCode = status;
+        const ra = res.headers["retry-after"];
+        if (ra) {
+          const secs = parseInt(ra, 10);
+          if (Number.isFinite(secs)) err.retryAfterMs = secs * 1000;
+        }
+        return reject(err);
+      }
+      if (status !== 200) {
+        res.resume();
+        return resolve({ ok: false, error: `GHSA returned HTTP ${status}`, source: "offline" });
       }
       const chunks = [];
       res.on("data", (c) => chunks.push(c));
@@ -88,11 +142,60 @@ async function fetchAdvisories({ timeoutMs = REQUEST_TIMEOUT_MS, path = GHSA_PAT
         }
       });
     });
-    req.on("timeout", () => req.destroy(new Error("timeout")));
-    req.on("error", (e) => resolve({ ok: false, error: e.message, source: "offline" }));
+    req.on("timeout", () => {
+      const err = new Error("timeout");
+      err.code = "ETIMEDOUT";
+      req.destroy(err);
+    });
+    req.on("error", (e) => {
+      if (e && e.code && /^(ECONNRESET|ECONNREFUSED|ECONNABORTED|ETIMEDOUT|EPIPE|EAGAIN|ENOTFOUND|ENETUNREACH)$/.test(e.code)) {
+        return reject(e);
+      }
+      resolve({ ok: false, error: e.message, source: "offline" });
+    });
   });
 }
 
+/**
+ * Fetch a page of advisories (default: latest 50). Wraps the underlying
+ * HTTPS request in withRetry so transient 429/503/5xx + net errors back off
+ * automatically.
+ *
+ * Returns:
+ *   { ok: true,  advisories: [...], source: "github-api" | "fixture", rate_limit?: { remaining, reset } }
+ *   { ok: false, error, source: "offline" }
+ */
+async function fetchAdvisories({ timeoutMs = REQUEST_TIMEOUT_MS, path = GHSA_PATH, token = null, airGap = false } = {}) {
+  const fixture = readFixture();
+  if (fixture) return fixture;
+  // Finding 7: air-gap hard-refuses network when no fixture is configured.
+  if (isAirGap({ airGap })) {
+    return { ok: false, error: "air-gap: no fixture available (set EXCEPTD_GHSA_FIXTURE)", source: "offline" };
+  }
+  const headers = {
+    "Accept": "application/vnd.github+json",
+    "User-Agent": USER_AGENT,
+    "X-GitHub-Api-Version": "2022-11-28",
+  };
+  if (token || process.env.GITHUB_TOKEN) {
+    headers.Authorization = `Bearer ${token || process.env.GITHUB_TOKEN}`;
+  }
+  try {
+    return await withRetry(() => ghsaRequestOnce({ path, headers, timeoutMs }), {
+      maxAttempts: 3,
+      baseDelayMs: 100,
+      maxDelayMs: 2000,
+      jitterFactor: 0.5,
+    });
+  } catch (e) {
+    const status = typeof e?.statusCode === "number" ? e.statusCode : null;
+    const error = status
+      ? `GHSA returned HTTP ${status}`
+      : `GHSA request failed: ${e.message || e}`;
+    return { ok: false, error, status, source: "offline" };
+  }
+}
+
 /**
  * Fetch a single advisory by ID — accepts CVE-* or GHSA-* identifiers.
  *
@@ -103,12 +206,18 @@ async function fetchAdvisoryById(id, opts = {}) {
   if (!id || typeof id !== "string") {
     return { ok: false, error: "id is required (CVE-* or GHSA-*)", source: "offline" };
   }
+  // Finding 8: trim whitespace at the entry seam.
+  id = id.trim();
+  if (!id) {
+    return { ok: false, error: "id is required (CVE-* or GHSA-*)", source: "offline" };
+  }
   if (process.env.EXCEPTD_GHSA_FIXTURE) {
     const r = await fetchAdvisories(opts);
     if (!r.ok) return r;
+    const want = id.toUpperCase();
     const match = r.advisories.find(a =>
-      (a.ghsa_id && a.ghsa_id.toUpperCase() === id.toUpperCase()) ||
-      (a.cve_id && a.cve_id.toUpperCase() === id.toUpperCase())
+      (a.ghsa_id && String(a.ghsa_id).toUpperCase() === want) ||
+      (a.cve_id && String(a.cve_id).toUpperCase() === want)
     );
     if (!match) return { ok: false, error: `${id} not in fixture`, source: "fixture" };
     return { ok: true, advisories: [match], source: "fixture" };
@@ -128,6 +237,23 @@ async function fetchAdvisoryById(id, opts = {}) {
   return { ok: false, error: `unrecognized id format: ${id}. Expected one of: CVE-YYYY-NNNN, GHSA-* (routed through source-ghsa); MAL-* / SNYK-* / RUSTSEC-* / USN-* / PYSEC-* / GO-* / MGASA-* / UVI- (routed through source-osv).`, source: "offline" };
 }
 
+/**
+ * Validate + slice a published_at timestamp. Findings 2 + 17:
+ *  - typeof guard so non-string inputs (number, object, undefined) become
+ *    null instead of throwing on .slice().
+ *  - ISO-prefix + year sanity bound so garbage timestamps don't pollute
+ *    downstream surfaces.
+ */
+function safeDateSlice(value) {
+  if (typeof value !== "string") return null;
+  const head = value.slice(0, 10);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(head)) return null;
+  const year = parseInt(head.slice(0, 4), 10);
+  const now = new Date().getUTCFullYear();
+  if (!Number.isFinite(year) || year < 1990 || year > now + 1) return null;
+  return head;
+}
+
 /**
  * Normalize a GHSA advisory object to the exceptd catalog draft shape.
  * Fields the GHSA carries authoritatively: cve_id, ghsa_id, summary,
@@ -146,7 +272,9 @@ function normalizeAdvisory(adv) {
   const ecosystems = new Set();
   const affected = [];
   const ecosystemPackages = [];
-  for (const v of (adv.vulnerabilities || [])) {
+  // Finding 3: vulnerabilities may not be an array — guard before iterating.
+  const vulnList = Array.isArray(adv.vulnerabilities) ? adv.vulnerabilities : [];
+  for (const v of vulnList) {
     if (v?.package?.ecosystem) ecosystems.add(v.package.ecosystem);
     if (v?.package?.name) {
       ecosystemPackages.push(`${v.package.ecosystem || "?"}:${v.package.name}`);
@@ -156,7 +284,14 @@ function normalizeAdvisory(adv) {
     }
   }
 
-  const cvssScore = adv.cvss?.score ?? null;
+  // Finding 4: cvss.score may arrive as a string ("9.8") rather than a
+  // number. Number-coerce + finite-check so the catalog field stays
+  // numeric across upstream shape drift.
+  let cvssScore = null;
+  if (adv.cvss != null && adv.cvss.score !== undefined && adv.cvss.score !== null) {
+    const n = Number(adv.cvss.score);
+    cvssScore = Number.isFinite(n) ? n : null;
+  }
   const cvssVector = adv.cvss?.vector_string || null;
   const severity = (adv.severity || "").toLowerCase();
   // Derive a coarse type from package ecosystem when nothing better available.
@@ -166,6 +301,13 @@ function normalizeAdvisory(adv) {
     : ecosystems.has("rubygems") ? "supply-chain-gem"
     : "supply-chain-other";
 
+  // Finding 2 + 17: type-safe + format-validated published_at slicing.
+  const publishedDate = safeDateSlice(adv.published_at);
+
+  // Finding 20: references may not be an array — guard the spread before
+  // it silently truncates to an empty list.
+  const refList = Array.isArray(adv.references) ? adv.references : [];
+
   return {
     [adv.cve_id]: {
       name: adv.summary || adv.cve_id,
@@ -205,7 +347,7 @@ function normalizeAdvisory(adv) {
       verification_sources: [
         ...(adv.html_url ? [adv.html_url] : []),
         ...(adv.cve_id ? [`https://nvd.nist.gov/vuln/detail/${adv.cve_id}`] : []),
-        ...(adv.references || []).slice(0, 10),
+        ...refList.slice(0, 10),
       ],
       vendor_advisories: [
         {
@@ -213,7 +355,7 @@ function normalizeAdvisory(adv) {
           advisory_id: adv.ghsa_id || null,
           url: adv.html_url || `https://github.com/advisories?query=${encodeURIComponent(adv.cve_id)}`,
           severity: severity || null,
-          published_date: (adv.published_at || "").slice(0, 10) || null,
+          published_date: publishedDate,
         },
       ],
       iocs: null,
@@ -231,19 +373,51 @@ function normalizeAdvisory(adv) {
  * Build a refresh diff for the existing refresh-external orchestrator.
  * Compares the latest 50 advisories' CVE IDs against the local catalog;
  * any CVE ID not in the catalog becomes an "add" diff.
+ *
+ * Finding 9: when the advisory is already in the catalog but a watched
+ * field has dropped from populated -> null, surface a `field_dropped`
+ * diff so curators don't silently lose signal.
+ *
+ * Finding 18: count + surface GHSA-only advisories (no CVE id) that were
+ * skipped, so the summary explains why N upstream advisories produced
+ * fewer than N diffs.
  */
 async function buildDiff(ctx) {
-  const result = await fetchAdvisories({});
+  const result = await fetchAdvisories({ airGap: ctx?.airGap });
   if (!result.ok) {
     return { status: "unreachable", diffs: [], errors: 1, summary: `GHSA fetch failed: ${result.error}` };
   }
-  const existing = new Set(Object.keys(ctx.cveCatalog || {}).filter(k => /^CVE-/.test(k)));
+  const cveCatalog = ctx.cveCatalog || {};
+  const existing = new Set(Object.keys(cveCatalog).filter(k => /^CVE-/.test(k)));
   const diffs = [];
+  let ghsaOnlySkipped = 0;
   for (const adv of result.advisories) {
-    if (!adv.cve_id) continue;
-    if (existing.has(adv.cve_id)) continue;
+    if (!adv.cve_id) { ghsaOnlySkipped++; continue; }
     const normalized = normalizeAdvisory(adv);
     if (!normalized) continue;
+    if (existing.has(adv.cve_id)) {
+      // Finding 9: field-dropped detection on the existing entry.
+      const before = cveCatalog[adv.cve_id] || {};
+      const after = normalized[adv.cve_id];
+      for (const field of FIELD_DROPPED_WATCH) {
+        const had = before[field];
+        const has = after[field];
+        const wasPopulated = had !== null && had !== undefined && had !== "" && had !== false;
+        const isNowEmpty = has === null || has === undefined;
+        if (wasPopulated && isNowEmpty) {
+          diffs.push({
+            id: adv.cve_id,
+            field,
+            before: had,
+            after: null,
+            severity: null,
+            source: "ghsa",
+            variant: "field_dropped",
+          });
+        }
+      }
+      continue;
+    }
     diffs.push({
       id: adv.cve_id,
       field: "_new_entry",
@@ -257,9 +431,17 @@ async function buildDiff(ctx) {
     status: "ok",
     diffs,
     errors: 0,
-    summary: `GHSA returned ${result.advisories.length} reviewed advisories; ${diffs.length} new CVE ID(s) not yet in local catalog.`,
+    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.`,
     rate_limit: result.rate_limit || null,
   };
 }
 
-module.exports = { fetchAdvisories, fetchAdvisoryById, normalizeAdvisory, buildDiff };
+module.exports = {
+  fetchAdvisories,
+  fetchAdvisoryById,
+  normalizeAdvisory,
+  buildDiff,
+  FIELD_DROPPED_WATCH,
+  safeDateSlice,
+};