@blamejs/exceptd-skills 0.10.2 → 0.10.3

package/sources/README.md

@@ -0,0 +1,170 @@
+# Sources
+
+The sources directory is the data quality gate for exceptd Security. Every claim in every skill must trace to a primary source. Bad data in produces bad analysis out — this directory makes source integrity a first-class concern.
+
+## The Problem: Data Corruption in Security Intelligence
+
+Security intelligence has several common failure modes:
+- **Stale data**: A CVE is marked as "no public PoC" when a PoC went public six months ago
+- **Misattribution**: A CVSS score copied from a secondary source that applied the wrong vector
+- **Fabricated details**: AI-summarized threat intel that introduced plausible-but-wrong specifics
+- **Framework version drift**: A control ID that changed in a framework revision but wasn't updated in skills
+- **Dead links**: Source URLs that return 404 — removing the ability to verify
+
+The sources system prevents these failures by:
+1. Maintaining a registry of authoritative primary sources per data type
+2. Providing validators that check data against primary sources
+3. Tracking source verification dates and flagging stale verifications
+4. Making multi-agent research verifiable and auditable
+
+---
+
+## Directory Structure
+
+```
+sources/
+├── README.md                  # This file
+├── index.json                 # Source registry — authoritative sources per data type
+├── SOURCES.md                 # Guide for adding and verifying sources
+├── validators/
+│   ├── cve-validator.js       # Cross-check CVE data against NVD API
+│   ├── kev-validator.js       # Verify CISA KEV status against official feed
+│   ├── atlas-validator.js     # Verify ATLAS TTP IDs against mitre.org
+│   └── framework-validator.js # Verify framework control IDs
+└── feeds/
+    ├── cisa-kev-snapshot.json # Snapshot of CISA KEV at last verification
+    ├── atlas-version.json     # Current ATLAS version metadata
+    └── nvd-recent.json        # Recent NVD entries (last 30 days)
+```
+
+---
+
+## Primary Sources by Data Type
+
+### CVE Data
+
+| Field | Authoritative Source | Update Frequency |
+|---|---|---|
+| CVSS score + vector | NVD (nvd.nist.gov/vuln/detail/CVE-XXXX) | On NVD analysis |
+| CISA KEV status | CISA KEV catalog (cisa.gov/known-exploited-vulnerabilities-catalog) | Real-time feed |
+| PoC availability | NVD references + researcher advisories | Monitor CVE references |
+| Active exploitation | CISA KEV, threat intelligence, incident reports | Monitor |
+| Affected versions | Vendor advisory (Red Hat, Ubuntu, etc.) | On vendor advisory |
+| Patch availability | Vendor advisory | On vendor advisory |
+| Live patch support | kpatch.com, ubuntu.com/security/livepatch, suse.com/products/live-patching | On vendor announcement |
+
+**Never use as primary source:** Wikipedia, news articles, blog posts, AI-generated summaries, secondary aggregators without NVD cross-reference.
+
+### ATLAS TTPs
+
+| Field | Authoritative Source |
+|---|---|
+| TTP ID | atlas.mitre.org (canonical IDs may change between versions) |
+| TTP name | atlas.mitre.org/techniques/ |
+| TTP version | atlas.mitre.org/resources/changelog |
+
+**ATLAS version pinning:** All skills reference a specific ATLAS version. When ATLAS updates, TTP IDs must be re-verified. The `atlas-validator.js` checks all skill `atlas_refs` against the current published ATLAS.
+
+### Framework Controls
+
+| Framework | Authoritative Source |
+|---|---|
+| NIST 800-53 Rev 5 | csrc.nist.gov/publications/detail/sp/800-53/rev-5/final |
+| ISO 27001:2022 | iso.org/standard/27001 (requires purchase for full text) |
+| SOC 2 | aicpa.org (TSC 2017) |
+| PCI DSS 4.0 | pcisecuritystandards.org/document_library |
+| NIS2 | eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32022L2555 |
+| DORA | eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32022R2554 |
+| EU AI Act | eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1689 |
+| EU CRA | Official Journal of EU |
+| NCSC CAF | ncsc.gov.uk/collection/cyber-assessment-framework |
+| ASD ISM | cyber.gov.au/resources-business-and-government/essential-cyber-security/ism |
+| ASD Essential 8 | cyber.gov.au/resources-business-and-government/essential-cyber-security/essential-eight |
+| MAS TRM | mas.gov.sg/regulation/guidelines/technology-risk-management-guidelines |
+| CIS Controls v8 | cisecurity.org/controls/v8 |
+| CSA CCM v4 | cloudsecurityalliance.org/research/cloud-controls-matrix |
+
+### PQC Standards
+
+| Standard | Authoritative Source |
+|---|---|
+| FIPS 203 (ML-KEM) | csrc.nist.gov/pubs/fips/203/final |
+| FIPS 204 (ML-DSA) | csrc.nist.gov/pubs/fips/204/final |
+| FIPS 205 (SLH-DSA) | csrc.nist.gov/pubs/fips/205/final |
+| FIPS 206 (HQC, pending) | csrc.nist.gov/projects/post-quantum-cryptography |
+| OpenSSL 3.5 release notes | github.com/openssl/openssl/blob/master/CHANGES.md |
+| CNSA 2.0 | cnss.gov |
+
+---
+
+## Source Verification Requirement
+
+Every entry in `data/cve-catalog.json` must have a `source_verified` field:
+```json
+{
+  "source_verified": "2026-05-01",
+  "verification_sources": [
+    "https://nvd.nist.gov/vuln/detail/CVE-2026-31431",
+    "https://www.cisa.gov/known-exploited-vulnerabilities-catalog"
+  ]
+}
+```
+
+A `source_verified` date older than 90 days triggers a reverification requirement in the skill-update-loop.
+
+---
+
+## Multi-Agent Research Protocol
+
+When agents research new threat intelligence, they must:
+1. Identify primary sources (from the registry above)
+2. Record what was found at each source and when
+3. Cross-reference across at least 2 independent sources for critical claims
+4. Flag any claim that could only be verified from a single source
+5. Record the agent ID and timestamp in the `source_verified` audit trail
+
+See `agents/threat-researcher.md` for the research agent protocol.
+
+---
+
+## Bad Data Prevention
+
+These categories of sources are **rejected** for skill data:
+
+| Source Type | Why Rejected |
+|---|---|
+| AI-generated summaries without primary source citation | Plausible hallucination risk |
+| News articles | Often inaccurate on technical details, not updated when details change |
+| Blog posts | No editorial standard, often repost errors from other blogs |
+| Wikipedia | Community-edited, not authoritative for CVE details or framework text |
+| Secondary aggregators without NVD cross-reference | May lag or misquote NVD |
+| Social media / X posts | Not citable, not stable |
+| Forum posts | Not authoritative |
+
+The only exception: researcher/discoverer announcements about their own research (e.g., Hyunwoo Kim's Dirty Frag disclosure) may be used as a source alongside NVD, since the researcher is the primary source for their own findings.
+
+---
+
+## Validators
+
+Real validation against primary sources lives in `sources/validators/`. These are
+zero-dependency Node 24 modules (stdlib `fetch`, `AbortController`, `fs/promises`
+only). Every network call has a 10s timeout and degrades to an `unreachable`
+status rather than throwing — the validators are safe to run in airgapped CI.
+
+| Module | Purpose | Upstream |
+|---|---|---|
+| [`validators/cve-validator.js`](validators/cve-validator.js) | Cross-check one CVE's CVSS score, vector, and KEV status against NVD and the CISA KEV feed. Caches the KEV feed once per process. | NVD `services.nvd.nist.gov` + CISA KEV JSON |
+| [`validators/atlas-validator.js`](validators/atlas-validator.js) | Confirm the pinned MITRE ATLAS version (in `manifest.json` and `sources/index.json`) matches the latest upstream release. | GitHub releases for `mitre-atlas/atlas-data`, raw `ATLAS.yaml` fallback |
+| [`validators/index.js`](validators/index.js) | Barrel export plus `validateAllCves(catalog)` for catalog-wide aggregation with bounded concurrency. | — |
+
+The orchestrator wires the CVE validator into the CLI:
+
+```
+node orchestrator/index.js validate-cves            # live cross-check, non-zero exit on drift
+node orchestrator/index.js validate-cves --offline  # local view only, no network
+node orchestrator/index.js validate-cves --no-fail  # report drift but always exit 0
+```
+
+Feed snapshots are written under `sources/feeds/`; see `sources/feeds/README.md`
+for the cache contract and freshness thresholds.

package/sources/validators/atlas-validator.js

@@ -0,0 +1,158 @@
+'use strict';
+
+/**
+ * atlas-validator.js — Confirm pinned MITRE ATLAS version against upstream.
+ *
+ * Zero npm dependencies. Node 24 stdlib only.
+ *
+ * MITRE ATLAS does not (as of v5.x) publish a stable machine-readable changelog JSON.
+ * The canonical source-of-truth for releases is the public GitHub repo:
+ *   https://raw.githubusercontent.com/mitre-atlas/atlas-data/main/dist/ATLAS.yaml
+ * which carries an `id: ATLAS` / `version: x.y.z` header. The GitHub releases API
+ * also lists tagged versions:
+ *   https://api.github.com/repos/mitre-atlas/atlas-data/releases/latest
+ *
+ * We prefer the releases API (lightweight JSON, no YAML parsing), fall back to the
+ * raw YAML version line, and finally report unreachable if both fail. Both are
+ * read-only public endpoints; no auth is required.
+ *
+ * Exported:
+ *   validateAtlasVersion(opts?) -> Promise<{
+ *     pinned: string|null,
+ *     pinned_sources: { manifest: string|null, index: string|null },
+ *     latest: string|null,
+ *     drift: boolean,
+ *     status: 'match'|'drift'|'unreachable'|'unknown',
+ *     fetched_from: string|null,
+ *     error: string|null
+ *   }>
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const REQUEST_TIMEOUT_MS = 10_000;
+const USER_AGENT = 'exceptd-security/atlas-validator (+https://exceptd.com)';
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const MANIFEST_PATH = path.join(REPO_ROOT, 'manifest.json');
+const SOURCES_INDEX_PATH = path.join(REPO_ROOT, 'sources', 'index.json');
+
+const GH_RELEASE_URL = 'https://api.github.com/repos/mitre-atlas/atlas-data/releases/latest';
+const RAW_ATLAS_YAML = 'https://raw.githubusercontent.com/mitre-atlas/atlas-data/main/dist/ATLAS.yaml';
+
+async function timedFetch(url, accept = 'application/json') {
+  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: accept },
+    });
+    if (!res.ok) return { ok: false, error: `HTTP ${res.status}` };
+    const body = accept.includes('json') ? await res.json() : await res.text();
+    return { ok: true, body };
+  } catch (err) {
+    const code = err.name === 'AbortError' ? 'timeout' : (err.code || 'network_error');
+    return { ok: false, error: `${code}: ${err.message}` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function normalizeVersion(v) {
+  if (!v || typeof v !== 'string') return null;
+  // Strip leading "v" / "ATLAS-v" prefixes; trim.
+  return v.trim().replace(/^ATLAS[-_ ]?/i, '').replace(/^v/i, '');
+}
+
+async function readPinnedVersions() {
+  const out = { manifest: null, index: null };
+  try {
+    const manifest = JSON.parse(await fs.readFile(MANIFEST_PATH, 'utf8'));
+    out.manifest = normalizeVersion(
+      manifest?._meta?.atlas_version || manifest?.atlas_version || null
+    );
+  } catch { /* leave null */ }
+  try {
+    const idx = JSON.parse(await fs.readFile(SOURCES_INDEX_PATH, 'utf8'));
+    out.index = normalizeVersion(idx?.sources?.atlas?.current_version || null);
+  } catch { /* leave null */ }
+  return out;
+}
+
+async function fetchLatestFromGithubReleases() {
+  const res = await timedFetch(GH_RELEASE_URL);
+  if (!res.ok) return { ok: false, error: res.error };
+  const tag = res.body?.tag_name || res.body?.name || null;
+  const version = normalizeVersion(tag);
+  if (!version) return { ok: false, error: 'no tag_name in response' };
+  return { ok: true, version, source: 'github-releases' };
+}
+
+async function fetchLatestFromRawYaml() {
+  const res = await timedFetch(RAW_ATLAS_YAML, 'text/yaml');
+  if (!res.ok) return { ok: false, error: res.error };
+  // Naive YAML scrape: look for a top-level `version:` line within the first 200 lines.
+  const text = String(res.body).split(/\r?\n/).slice(0, 200).join('\n');
+  const match = text.match(/^version:\s*['"]?([0-9]+(?:\.[0-9]+){1,2})['"]?\s*$/m);
+  if (!match) return { ok: false, error: 'version line not found in ATLAS.yaml' };
+  return { ok: true, version: normalizeVersion(match[1]), source: 'raw-yaml' };
+}
+
+async function validateAtlasVersion(_opts = {}) {
+  const pinned_sources = await readPinnedVersions();
+  // Canonical pinned value: prefer manifest._meta or top-level, then sources/index.json.
+  const pinned = pinned_sources.manifest || pinned_sources.index || null;
+
+  // Cross-check that the two pinned locations agree.
+  const pinnedDisagree =
+    pinned_sources.manifest &&
+    pinned_sources.index &&
+    pinned_sources.manifest !== pinned_sources.index;
+
+  // Try GitHub releases first, fall back to raw YAML.
+  let upstream = await fetchLatestFromGithubReleases();
+  if (!upstream.ok) {
+    const fallback = await fetchLatestFromRawYaml();
+    if (fallback.ok) upstream = fallback;
+  }
+
+  if (!upstream.ok) {
+    return {
+      pinned,
+      pinned_sources,
+      latest: null,
+      drift: pinnedDisagree === true, // internal drift is still reportable offline
+      status: 'unreachable',
+      fetched_from: null,
+      error: upstream.error,
+    };
+  }
+
+  const latest = upstream.version;
+  if (!pinned) {
+    return {
+      pinned: null,
+      pinned_sources,
+      latest,
+      drift: true,
+      status: 'unknown',
+      fetched_from: upstream.source,
+      error: 'no pinned ATLAS version found in manifest.json or sources/index.json',
+    };
+  }
+
+  const drift = pinned !== latest || pinnedDisagree === true;
+  return {
+    pinned,
+    pinned_sources,
+    latest,
+    drift,
+    status: drift ? 'drift' : 'match',
+    fetched_from: upstream.source,
+    error: null,
+  };
+}
+
+module.exports = { validateAtlasVersion };

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,
+};