@blamejs/exceptd-skills 0.10.1 → 0.10.3

package/sources/validators/cve-validator.js

@@ -0,0 +1,277 @@
+'use strict';
+
+/**
+ * cve-validator.js — Cross-check local CVE catalog entries against NVD, CISA KEV, and EPSS.
+ *
+ * Zero npm dependencies. Node 24 stdlib only.
+ *
+ * Exported:
+ *   validateCve(cveId, localCatalogEntry) -> Promise<ValidationResult>
+ *   getKevCache()                          -> Map (KEV map by CVE ID, lazy-loaded)
+ *   resetKevCache()                        -> void (testing helper)
+ *
+ * ValidationResult shape:
+ *   {
+ *     cve_id: 'CVE-YYYY-NNNNN',
+ *     status: 'match' | 'drift' | 'unreachable' | 'missing',
+ *     discrepancies: [ { field, local, fetched, severity } ],
+ *     fetched: {
+ *       cvss_score, cvss_vector, in_kev, kev_date,
+ *       epss: { score, percentile, date } | null,
+ *       sources: { nvd, kev, epss }
+ *     },
+ *     local: {
+ *       cvss_score, cvss_vector, cisa_kev, cisa_kev_date,
+ *       epss_score, epss_percentile, epss_date
+ *     },
+ *     drift: { local_epss, fetched_epss } | null   // populated when EPSS drift is present
+ *   }
+ *
+ * Network resilience:
+ *   - Every fetch has a 10s AbortController timeout.
+ *   - Network/parse errors return { status: 'unreachable', ... } — never throw.
+ *   - The KEV feed is fetched once per process and cached in module-level memory.
+ *   - The EPSS API is queried per-CVE (FIRST recommends per-CVE lookups for fresh data).
+ */
+
+const NVD_API = 'https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=';
+const KEV_FEED = 'https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json';
+const EPSS_API = 'https://api.first.org/data/v1/epss?cve=';
+const REQUEST_TIMEOUT_MS = 10_000;
+const EPSS_DRIFT_THRESHOLD = 0.05; // |Δscore| or |Δpercentile| > 0.05 flags drift
+const USER_AGENT = 'exceptd-security/cve-validator (+https://exceptd.com)';
+
+let kevCachePromise = null; // Promise<Map<cveId, kevEntry>> | null
+let kevCacheError = null;   // { code, message } if last attempt failed (per process)
+
+async function timedFetch(url) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      headers: { 'User-Agent': USER_AGENT, Accept: 'application/json' },
+    });
+    if (!res.ok) {
+      return { ok: false, error: `HTTP ${res.status}`, status: res.status };
+    }
+    const json = await res.json();
+    return { ok: true, json };
+  } catch (err) {
+    const code = err.name === 'AbortError' ? 'timeout' : (err.code || 'network_error');
+    return { ok: false, error: `${code}: ${err.message}`, code };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function loadKevCache() {
+  if (kevCachePromise) return kevCachePromise;
+  kevCachePromise = (async () => {
+    const result = await timedFetch(KEV_FEED);
+    if (!result.ok) {
+      kevCacheError = { code: 'kev_unreachable', message: result.error };
+      return null;
+    }
+    const map = new Map();
+    const items = Array.isArray(result.json?.vulnerabilities) ? result.json.vulnerabilities : [];
+    for (const v of items) {
+      if (v && v.cveID) map.set(v.cveID, v);
+    }
+    return map;
+  })();
+  return kevCachePromise;
+}
+
+function getKevCache() {
+  return kevCachePromise;
+}
+
+function resetKevCache() {
+  kevCachePromise = null;
+  kevCacheError = null;
+}
+
+function extractNvdCvss(nvdJson) {
+  // NVD response: vulnerabilities[0].cve.metrics.cvssMetricV31[0].cvssData
+  const vuln = nvdJson?.vulnerabilities?.[0]?.cve;
+  if (!vuln) return null;
+  const metrics = vuln.metrics || {};
+  const ordered = [
+    ...(metrics.cvssMetricV31 || []),
+    ...(metrics.cvssMetricV30 || []),
+    ...(metrics.cvssMetricV2 || []),
+  ];
+  // Prefer Primary type if present
+  const primary = ordered.find(m => m.type === 'Primary') || ordered[0];
+  if (!primary?.cvssData) return null;
+  return {
+    score: typeof primary.cvssData.baseScore === 'number' ? primary.cvssData.baseScore : null,
+    vector: primary.cvssData.vectorString || null,
+    source: primary.source || null,
+  };
+}
+
+function pushDiscrepancy(list, field, local, fetched, severity = 'warning') {
+  list.push({ field, local, fetched, severity });
+}
+
+function extractEpss(epssJson, cveId) {
+  // FIRST EPSS response shape: { status: "OK", data: [ { cve, epss, percentile, date } ] }
+  const data = Array.isArray(epssJson?.data) ? epssJson.data : [];
+  if (data.length === 0) return null;
+  const row = data.find(r => r?.cve === cveId) || data[0];
+  if (!row) return null;
+  // EPSS returns strings; coerce defensively.
+  const score = row.epss !== undefined && row.epss !== null ? Number(row.epss) : null;
+  const percentile = row.percentile !== undefined && row.percentile !== null ? Number(row.percentile) : null;
+  return {
+    score: Number.isFinite(score) ? score : null,
+    percentile: Number.isFinite(percentile) ? percentile : null,
+    date: typeof row.date === 'string' ? row.date : null,
+  };
+}
+
+async function validateCve(cveId, localEntry) {
+  if (!cveId || typeof cveId !== 'string') {
+    throw new TypeError('validateCve: cveId must be a string');
+  }
+
+  const local = {
+    cvss_score: localEntry?.cvss_score ?? null,
+    cvss_vector: localEntry?.cvss_vector ?? null,
+    cisa_kev: localEntry?.cisa_kev ?? null,
+    cisa_kev_date: localEntry?.cisa_kev_date ?? null,
+    epss_score: localEntry?.epss_score ?? null,
+    epss_percentile: localEntry?.epss_percentile ?? null,
+    epss_date: localEntry?.epss_date ?? null,
+  };
+
+  const fetched = {
+    cvss_score: null,
+    cvss_vector: null,
+    in_kev: null,
+    kev_date: null,
+    epss: null,
+    sources: { nvd: null, kev: null, epss: null },
+  };
+  const discrepancies = [];
+  let drift = null;
+
+  // Run NVD + KEV + EPSS in parallel.
+  const [nvdResult, kevMap, epssResult] = await Promise.all([
+    timedFetch(NVD_API + encodeURIComponent(cveId)),
+    loadKevCache(),
+    timedFetch(EPSS_API + encodeURIComponent(cveId)),
+  ]);
+
+  // --- NVD branch ---
+  let nvdReachable = false;
+  let cveFoundInNvd = false;
+  if (nvdResult.ok) {
+    nvdReachable = true;
+    const totalResults = nvdResult.json?.totalResults ?? nvdResult.json?.vulnerabilities?.length ?? 0;
+    if (totalResults === 0) {
+      fetched.sources.nvd = { reachable: true, found: false };
+    } else {
+      cveFoundInNvd = true;
+      const cvss = extractNvdCvss(nvdResult.json);
+      if (cvss) {
+        fetched.cvss_score = cvss.score;
+        fetched.cvss_vector = cvss.vector;
+        fetched.sources.nvd = { reachable: true, found: true, source: cvss.source };
+      } else {
+        fetched.sources.nvd = { reachable: true, found: true, source: null, note: 'no cvss metrics in NVD response' };
+      }
+    }
+  } else {
+    fetched.sources.nvd = { reachable: false, error: nvdResult.error };
+  }
+
+  // --- KEV branch ---
+  if (kevMap === null) {
+    fetched.sources.kev = { reachable: false, error: kevCacheError?.message || 'unknown' };
+  } else {
+    const hit = kevMap.get(cveId);
+    fetched.in_kev = !!hit;
+    fetched.kev_date = hit?.dateAdded || null;
+    fetched.sources.kev = { reachable: true, total_entries: kevMap.size };
+  }
+
+  // --- EPSS branch ---
+  let epssReachable = false;
+  if (epssResult.ok) {
+    epssReachable = true;
+    const epss = extractEpss(epssResult.json, cveId);
+    if (epss) {
+      fetched.epss = epss;
+      fetched.sources.epss = { reachable: true, found: true, date: epss.date };
+    } else {
+      fetched.sources.epss = { reachable: true, found: false };
+    }
+  } else {
+    fetched.sources.epss = { reachable: false, error: epssResult.error };
+  }
+
+  // --- Status decision ---
+  // Only declare 'unreachable' if every source failed. EPSS being down alone
+  // should not block NVD/KEV drift detection.
+  if (!nvdReachable && (kevMap === null) && !epssReachable) {
+    return { cve_id: cveId, status: 'unreachable', discrepancies, fetched, local, drift };
+  }
+
+  if (nvdReachable && !cveFoundInNvd) {
+    return { cve_id: cveId, status: 'missing', discrepancies, fetched, local, drift };
+  }
+
+  // --- Compare CVSS (only if NVD reachable & has data) ---
+  if (cveFoundInNvd && fetched.cvss_score !== null && local.cvss_score !== null) {
+    if (Math.abs(fetched.cvss_score - local.cvss_score) > 0.05) {
+      pushDiscrepancy(discrepancies, 'cvss_score', local.cvss_score, fetched.cvss_score, 'high');
+    }
+  }
+  if (cveFoundInNvd && fetched.cvss_vector && local.cvss_vector) {
+    if (fetched.cvss_vector !== local.cvss_vector) {
+      pushDiscrepancy(discrepancies, 'cvss_vector', local.cvss_vector, fetched.cvss_vector, 'medium');
+    }
+  }
+
+  // --- Compare KEV (only if KEV reachable) ---
+  if (kevMap !== null) {
+    if (typeof local.cisa_kev === 'boolean' && local.cisa_kev !== fetched.in_kev) {
+      pushDiscrepancy(discrepancies, 'cisa_kev', local.cisa_kev, fetched.in_kev, 'high');
+    }
+    if (local.cisa_kev_date && fetched.kev_date && local.cisa_kev_date !== fetched.kev_date) {
+      pushDiscrepancy(discrepancies, 'cisa_kev_date', local.cisa_kev_date, fetched.kev_date, 'low');
+    }
+  }
+
+  // --- Compare EPSS (only if EPSS reachable + both sides have data) ---
+  if (epssReachable && fetched.epss) {
+    const fScore = fetched.epss.score;
+    const fPct = fetched.epss.percentile;
+    const lScore = typeof local.epss_score === 'number' ? local.epss_score : null;
+    const lPct = typeof local.epss_percentile === 'number' ? local.epss_percentile : null;
+
+    let epssDrift = false;
+    if (lScore !== null && fScore !== null && Math.abs(fScore - lScore) > EPSS_DRIFT_THRESHOLD) {
+      pushDiscrepancy(discrepancies, 'epss_score', lScore, fScore, 'medium');
+      epssDrift = true;
+    }
+    if (lPct !== null && fPct !== null && Math.abs(fPct - lPct) > EPSS_DRIFT_THRESHOLD) {
+      pushDiscrepancy(discrepancies, 'epss_percentile', lPct, fPct, 'medium');
+      epssDrift = true;
+    }
+    if (epssDrift) {
+      drift = {
+        local_epss: { score: lScore, percentile: lPct, date: local.epss_date },
+        fetched_epss: { score: fScore, percentile: fPct, date: fetched.epss.date },
+      };
+    }
+  }
+
+  const status = discrepancies.length === 0 ? 'match' : 'drift';
+  return { cve_id: cveId, status, discrepancies, fetched, local, drift };
+}
+
+module.exports = { validateCve, getKevCache, resetKevCache };

package/sources/validators/index.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * sources/validators/index.js — barrel export.
+ *
+ * Re-exports:
+ *   - validateCve(cveId, localEntry)         — NVD + CISA KEV cross-check (per CVE)
+ *   - validateAtlasVersion()                 — Confirm pinned ATLAS version matches upstream
+ *   - validateAllCves(catalog, opts?)        — Aggregate CVE validation across the local catalog
+ *
+ * Aggregate report shape:
+ *   {
+ *     generated_at: ISO timestamp,
+ *     total: number,
+ *     by_status: { match, drift, unreachable, missing },
+ *     drift_count: number,
+ *     results: ValidationResult[]  // see cve-validator.js
+ *   }
+ */
+
+const { validateCve, getKevCache, resetKevCache } = require('./cve-validator');
+const { validateAtlasVersion } = require('./atlas-validator');
+const { validateRfc, validateAllRfcs } = require('./rfc-validator');
+
+/**
+ * @param {object} catalog - parsed data/cve-catalog.json (the whole object incl. _meta)
+ * @param {object} [opts]
+ * @param {number} [opts.concurrency=4] - parallel NVD lookups (NVD allows 5 rps anonymously)
+ * @returns {Promise<object>} aggregate report
+ */
+async function validateAllCves(catalog, opts = {}) {
+  const concurrency = Math.max(1, Math.min(8, opts.concurrency || 4));
+  if (!catalog || typeof catalog !== 'object') {
+    throw new TypeError('validateAllCves: catalog must be an object');
+  }
+
+  const ids = Object.keys(catalog).filter(k => /^CVE-\d{4}-\d{4,7}$/.test(k));
+  const results = [];
+  const by_status = { match: 0, drift: 0, unreachable: 0, missing: 0 };
+
+  // Simple windowed concurrency — no extra deps.
+  let cursor = 0;
+  async function worker() {
+    while (cursor < ids.length) {
+      const idx = cursor++;
+      const id = ids[idx];
+      try {
+        const res = await validateCve(id, catalog[id]);
+        results[idx] = res;
+        by_status[res.status] = (by_status[res.status] || 0) + 1;
+      } catch (err) {
+        // Defensive: validateCve already swallows network errors; this is a logic error.
+        results[idx] = {
+          cve_id: id,
+          status: 'unreachable',
+          discrepancies: [],
+          fetched: { sources: { nvd: null, kev: null } },
+          local: catalog[id] || null,
+          error: err.message,
+        };
+        by_status.unreachable++;
+      }
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(concurrency, ids.length) }, () => worker());
+  await Promise.all(workers);
+
+  return {
+    generated_at: new Date().toISOString(),
+    total: ids.length,
+    by_status,
+    drift_count: by_status.drift,
+    results,
+  };
+}
+
+module.exports = {
+  validateCve,
+  validateAtlasVersion,
+  validateAllCves,
+  validateRfc,
+  validateAllRfcs,
+  getKevCache,
+  resetKevCache,
+};

package/sources/validators/rfc-validator.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * sources/validators/rfc-validator.js
+ *
+ * Cross-checks a single entry from data/rfc-references.json against the
+ * IETF Datatracker. Mirrors the shape of cve-validator.js:
+ *
+ *   validateRfc(id, entry) → { id, status, discrepancies, fetched, local }
+ *
+ * status is one of:
+ *   match        — Datatracker view agrees with the local entry on status,
+ *                  errata count, and replaces/replaced-by relationships.
+ *   drift        — at least one of those fields disagrees.
+ *   missing      — Datatracker does not have this RFC / draft.
+ *   unreachable  — network failed or the request timed out.
+ *
+ * Zero external dependencies. Node 24 stdlib (fetch + AbortController).
+ *
+ * The Datatracker API is generous about rate limits for read-only queries,
+ * but every fetch wraps an AbortController with a 10-second timeout so an
+ * airgapped CI runner never hangs.
+ */
+
+const TIMEOUT_MS = 10_000;
+
+const DATATRACKER_RFC_BASE = 'https://datatracker.ietf.org/api/v1/doc/document/';
+const DATATRACKER_DRAFT_BASE = 'https://datatracker.ietf.org/api/v1/doc/document/';
+
+async function fetchWithTimeout(url, opts = {}) {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { ...opts, signal: ac.signal });
+    return res;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+function rfcNumberFromKey(id) {
+  // Catalog keys look like "RFC-8446". The Datatracker doc name is "rfc8446".
+  const m = id.match(/^RFC-(\d+)$/);
+  return m ? `rfc${m[1]}` : null;
+}
+
+function draftSlugFromKey(id) {
+  // Catalog keys look like "DRAFT-IETF-TLS-ECDHE-MLKEM". The Datatracker doc
+  // name is "draft-ietf-tls-ecdhe-mlkem" — lowercased, hyphenated.
+  const m = id.match(/^DRAFT-(.+)$/);
+  return m ? `draft-${m[1].toLowerCase()}` : null;
+}
+
+async function fetchRfcDocument(name) {
+  // Datatracker API: /api/v1/doc/document/?name=rfc8446 returns a list with
+  // one entry. The fields we care about are `std_level` (status), the
+  // related "replaces" and "replaced-by" relationships, and the abstract.
+  try {
+    const url = `${DATATRACKER_RFC_BASE}?name=${encodeURIComponent(name)}&format=json`;
+    const res = await fetchWithTimeout(url, { headers: { 'Accept': 'application/json' } });
+    if (!res.ok) {
+      if (res.status === 404) return { status: 'missing' };
+      return { status: 'unreachable', reason: `HTTP ${res.status}` };
+    }
+    const body = await res.json();
+    const obj = body.objects && body.objects[0];
+    if (!obj) return { status: 'missing' };
+    return { status: 'found', obj };
+  } catch (err) {
+    return { status: 'unreachable', reason: err.message };
+  }
+}
+
+function compareEntry(local, upstream) {
+  const discrepancies = [];
+
+  // Datatracker exposes the standards-track level as `std_level`. Map between
+  // its short codes and the longer human strings the catalog uses.
+  const DATATRACKER_TO_LOCAL = {
+    'std': 'Internet Standard',
+    'ps':  'Proposed Standard',
+    'ds':  'Draft Standard',
+    'bcp': 'Best Current Practice',
+    'inf': 'Informational',
+    'exp': 'Experimental',
+    'his': 'Historic',
+    'unkn': 'Unknown',
+  };
+  const upstreamStatusCode = upstream.obj && upstream.obj.std_level;
+  const upstreamStatusHuman = upstreamStatusCode && DATATRACKER_TO_LOCAL[upstreamStatusCode];
+  if (local.status && upstreamStatusHuman && local.status !== upstreamStatusHuman) {
+    discrepancies.push(
+      `status drift: local "${local.status}" vs Datatracker "${upstreamStatusHuman}"`
+    );
+  }
+
+  // Datatracker doesn't expose errata count directly on this endpoint; we
+  // capture it as informational only and don't fail on it. A future
+  // enhancement could hit https://www.rfc-editor.org/errata/<rfcN>.json
+  // for the canonical count.
+
+  // If the upstream record indicates obsoletion (replaced-by populated), the
+  // local entry must reflect it.
+  // Datatracker exposes related docs through a separate `related_documents`
+  // endpoint — keep this simple for now and just surface the abstract URL so
+  // the operator can verify by hand. Anything more requires a second fetch.
+
+  return discrepancies;
+}
+
+async function validateRfc(id, entry) {
+  let docName;
+  if (id.startsWith('RFC-')) docName = rfcNumberFromKey(id);
+  else if (id.startsWith('DRAFT-')) docName = draftSlugFromKey(id);
+  else {
+    return {
+      id,
+      status: 'drift',
+      discrepancies: [`unrecognized catalog key shape: ${id}`],
+      local: entry,
+      fetched: null,
+    };
+  }
+
+  if (!docName) {
+    return {
+      id,
+      status: 'drift',
+      discrepancies: [`could not derive Datatracker doc name from ${id}`],
+      local: entry,
+      fetched: null,
+    };
+  }
+
+  const fetched = await fetchRfcDocument(docName);
+  if (fetched.status === 'unreachable') {
+    return { id, status: 'unreachable', reason: fetched.reason, local: entry, fetched: null };
+  }
+  if (fetched.status === 'missing') {
+    return { id, status: 'missing', local: entry, fetched: null };
+  }
+
+  const discrepancies = compareEntry(entry, fetched);
+  return {
+    id,
+    status: discrepancies.length === 0 ? 'match' : 'drift',
+    discrepancies,
+    local: entry,
+    fetched: fetched.obj,
+  };
+}
+
+async function validateAllRfcs(refs, { concurrency = 4 } = {}) {
+  const ids = Object.keys(refs).filter(k => !k.startsWith('_'));
+  const results = [];
+  for (let i = 0; i < ids.length; i += concurrency) {
+    const batch = ids.slice(i, i + concurrency);
+    const batchResults = await Promise.all(
+      batch.map(id => validateRfc(id, refs[id]))
+    );
+    results.push(...batchResults);
+  }
+  return results;
+}
+
+module.exports = { validateRfc, validateAllRfcs };

package/sources/validators/version-pin-validator.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * sources/validators/version-pin-validator.js
+ *
+ * Checks pinned upstream catalog versions against their canonical release
+ * channels:
+ *
+ *   - MITRE ATLAS:     GitHub releases (mitre-atlas/atlas-data)
+ *   - MITRE ATT&CK:    GitHub releases (mitre-attack/attack-stix-data)
+ *   - MITRE D3FEND:    GitHub releases (mitre-d3fend/d3fend-data)
+ *   - MITRE CWE:       GitHub releases (mitre/cwe)
+ *
+ * Each check returns:
+ *   { pin_name, local_version, latest_version, drift: bool, source_url, error? }
+ *
+ * Network resilience: 10s AbortController timeout per call. A failure is
+ * `{ error: ... }` — never throws. Version-pin drift is REPORT-ONLY: the
+ * upgrade requires audit per AGENTS.md Hard Rule #12, so refresh-external
+ * surfaces these as separate findings (GitHub issue, not an auto-apply PR).
+ *
+ * Zero npm deps. Node 24 stdlib only.
+ */
+
+const TIMEOUT_MS = 10_000;
+
+const PINS = [
+  {
+    pin_name: "atlas_version",
+    repo: "mitre-atlas/atlas-data",
+    local_path_hint: "manifest.json — atlas_version",
+    strip_v_prefix: true,
+  },
+  {
+    pin_name: "attack_version",
+    repo: "mitre-attack/attack-stix-data",
+    local_path_hint: "manifest.json — attack_version",
+    strip_v_prefix: true,
+  },
+  {
+    pin_name: "d3fend_version",
+    repo: "d3fend/d3fend-data",
+    local_path_hint: "data/d3fend-catalog.json _meta.version",
+    strip_v_prefix: true,
+  },
+  {
+    pin_name: "cwe_version",
+    repo: "mitre/cwe",
+    local_path_hint: "data/cwe-catalog.json _meta.version",
+    strip_v_prefix: true,
+  },
+];
+
+async function fetchWithTimeout(url, opts = {}) {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), TIMEOUT_MS);
+  try {
+    return await fetch(url, { ...opts, signal: ac.signal });
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+async function latestGithubRelease(repo) {
+  // Use the un-authenticated /releases endpoint and pick the most recent
+  // non-draft, non-prerelease entry. Limits: 60 anonymous requests/hour, more
+  // than enough for a weekly refresh job.
+  const url = `https://api.github.com/repos/${repo}/releases?per_page=5`;
+  try {
+    const res = await fetchWithTimeout(url, {
+      headers: { Accept: "application/vnd.github+json", "User-Agent": "exceptd-security/version-pin-validator" },
+    });
+    if (!res.ok) {
+      return { error: `HTTP ${res.status}`, source_url: url };
+    }
+    const arr = await res.json();
+    if (!Array.isArray(arr)) return { error: "unexpected payload", source_url: url };
+    const stable = arr.find((r) => !r.draft && !r.prerelease);
+    if (!stable) return { error: "no stable release found", source_url: url };
+    return { tag: stable.tag_name, name: stable.name, published_at: stable.published_at, source_url: stable.html_url };
+  } catch (err) {
+    return { error: err.message || "fetch failed", source_url: url };
+  }
+}
+
+function normalize(version, stripV) {
+  if (version == null) return null;
+  let v = String(version).trim();
+  if (stripV && v.startsWith("v")) v = v.slice(1);
+  return v;
+}
+
+/**
+ * Resolve the local pinned version for a given pin name.
+ * @param {string} pin_name
+ * @param {object} ctx - { manifest, cweCatalog, d3fendCatalog }
+ */
+function resolveLocalVersion(pin_name, ctx) {
+  switch (pin_name) {
+    case "atlas_version":
+      return ctx.manifest.atlas_version;
+    case "attack_version":
+      return ctx.manifest.attack_version;
+    case "cwe_version":
+      return ctx.cweCatalog?._meta?.version || ctx.cweCatalog?._meta?.cwe_version || null;
+    case "d3fend_version":
+      return ctx.d3fendCatalog?._meta?.version || ctx.d3fendCatalog?._meta?.d3fend_version || null;
+    default:
+      return null;
+  }
+}
+
+async function checkAllPins(ctx) {
+  const out = [];
+  for (const pin of PINS) {
+    const local = normalize(resolveLocalVersion(pin.pin_name, ctx), pin.strip_v_prefix);
+    const release = await latestGithubRelease(pin.repo);
+    if (release.error) {
+      out.push({
+        pin_name: pin.pin_name,
+        local_version: local,
+        latest_version: null,
+        drift: null,
+        unreachable: true,
+        error: release.error,
+        source_url: release.source_url,
+      });
+      continue;
+    }
+    const latest = normalize(release.tag, pin.strip_v_prefix);
+    out.push({
+      pin_name: pin.pin_name,
+      local_version: local,
+      latest_version: latest,
+      latest_release_name: release.name,
+      latest_published_at: release.published_at,
+      drift: local != null && latest != null && local !== latest,
+      source_url: release.source_url,
+      local_path_hint: pin.local_path_hint,
+    });
+  }
+  return out;
+}
+
+module.exports = { checkAllPins, PINS };