kirograph 0.17.0 → 0.20.0

package/dist/security/types.js

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);
+//# sourceMappingURL=types.js.map

package/dist/security/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/security/types.ts"],
+  "sourcesContent": ["/**\n * KiroGraph-Sec Type Definitions\n *\n * Interfaces for the security analysis module including manifest parsing,\n * vulnerability detection, reachability analysis, and CycloneDX export.\n */\n\n// \u2500\u2500 Manifest Parsing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface ParsedDependency {\n  name: string;\n  declaredConstraint: string;\n  resolvedVersion?: string; // from lock file\n  scope: 'production' | 'development' | 'optional';\n  ecosystem: string;\n  sourceManifest: string; // relative path to declaring manifest\n  license?: string; // SPDX expression or license name, if available in the manifest\n}\n\nexport interface ManifestParseResult {\n  dependenciesCreated: number;\n  manifestsParsed: number;\n  warnings: Array<{ file: string; line?: number; message: string }>;\n  errors: Array<{ file: string; message: string }>;\n}\n\n// \u2500\u2500 Dependency Graph Integration \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface IntegrationResult {\n  importsEdgesCreated: number;\n  referencesEdgesCreated: number;\n}\n\nexport interface TransitiveResult {\n  dependsOnEdgesCreated: number;\n  incompleteNodes: string[]; // nodes marked with transitive_status=incomplete\n}\n\nexport interface CleanupResult {\n  nodesRemoved: number;\n  edgesRemoved: number;\n}\n\n// \u2500\u2500 Vulnerability Database \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface CVERecord {\n  id: string; // e.g. \"CVE-2023-12345\"\n  severity: number; // CVSS v3.1 base score\n  affectedVersionRanges: VersionRange[];\n  fixedVersion?: string;\n  summary: string;\n}\n\nexport interface VersionRange {\n  introduced?: string;\n  fixed?: string;\n  lastAffected?: string;\n}\n\nexport interface EnrichmentResult {\n  vulnerabilitiesFound: number;\n  dependenciesChecked: number;\n  errors: Array<{ dependency: string; database: string; error: string }>;\n  staleNodes: string[]; // nodes where vulnDataStale was set\n}\n\n// \u2500\u2500 Reachability Analysis \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport type ReachabilityVerdict = 'affected' | 'not_affected' | 'under_investigation';\n\nexport interface ReachabilityPath {\n  entryPoint: string; // node ID of the entry point\n  path: string[]; // ordered list of node IDs from entry to dependency\n}\n\nexport interface ReachabilityResult {\n  verdict: ReachabilityVerdict;\n  paths: ReachabilityPath[];\n  unresolvedSymbols: string[]; // up to 50, for under_investigation\n  reachingEntryPointCount: number;\n}\n\nexport interface ImpactSummary {\n  affectedLayers: string[]; // e.g. ['api', 'service']\n  affectedEntryPoints: string[]; // node IDs of reaching entry points\n  distinctPathCount: number; // capped at 100\n}\n\n// \u2500\u2500 Security Pipeline \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface SecurityResult {\n  manifestsDiscovered: number;\n  dependenciesCreated: number;\n  vulnerabilitiesFound: number;\n  affectedCount: number;\n  notAffectedCount: number;\n  underInvestigationCount: number;\n  duration: number;\n}\n\n// \u2500\u2500 CycloneDX SBOM Export \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface SBOMMetadata {\n  toolName: string;\n  toolVersion: string;\n  timestamp: string; // ISO 8601 UTC\n  projectName: string;\n}\n\nexport interface CycloneDXSBOM {\n  bomFormat: 'CycloneDX';\n  specVersion: '1.5';\n  version: number;\n  metadata: Record<string, unknown>;\n  components: CycloneDXComponent[];\n  dependencies: CycloneDXDependencyEntry[];\n}\n\nexport interface CycloneDXComponent {\n  type: 'library';\n  name: string;\n  version: string;\n  purl: string;\n  scope?: 'required' | 'optional';\n  properties?: Array<{ name: string; value: string }>;\n}\n\nexport interface CycloneDXDependencyEntry {\n  ref: string;\n  dependsOn?: string[];\n}\n\n// \u2500\u2500 CycloneDX VEX Export \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface CycloneDXVEX {\n  bomFormat: 'CycloneDX';\n  specVersion: '1.5';\n  version: number;\n  metadata: Record<string, unknown>;\n  vulnerabilities: CycloneDXVulnerability[];\n}\n\nexport interface CycloneDXVulnerability {\n  id: string;\n  source?: { name: string; url?: string };\n  ratings?: Array<{ score: number; severity?: string; method?: string }>;\n  analysis?: {\n    state: 'affected' | 'not_affected' | 'under_investigation';\n    justification?: string;\n    detail?: string;\n  };\n  affects?: Array<{ ref: string }>;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;AAAA;AAAA;",
+  "names": []
+}

package/dist/security/vuln/client.d.ts

@@ -0,0 +1,90 @@
+/**
+ * VulnerabilityDatabaseClient
+ *
+ * Orchestrates vulnerability enrichment by querying configured databases,
+ * merging and deduplicating results by CVE identifier, creating Vulnerability_Nodes
+ * linked to affected Dependency_Nodes, and handling unreachable databases gracefully.
+ *
+ * Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.7
+ */
+import type { GraphDatabase } from '../../db/database';
+import type { CVERecord, EnrichmentResult } from '../types';
+import type { VulnDatabaseAdapter } from './types';
+/**
+ * Compute a combined risk score (0.0–10.0) for a vulnerability.
+ *
+ * Formula:
+ *   risk = reachability_factor × (0.4 × cvss_normalized + 0.6 × epss) × staleness_bonus
+ *   scaled to 0–10: min(risk × 10, 10.0)
+ *
+ * @param cvss        - CVSS base score (0.0–10.0), null treated as 5.0
+ * @param epss        - EPSS exploitation probability (0.0–1.0), null treated as 0.0
+ * @param verdict     - Reachability verdict or null/undefined
+ * @param staleness   - Dependency staleness score (0.0–1.0), null treated as 0.0
+ */
+export declare function computeRiskScore(cvss: number | null | undefined, epss: number | null | undefined, verdict: string | null | undefined, staleness: number | null | undefined): number;
+export declare class VulnerabilityDatabaseClient {
+    private readonly adapters;
+    private readonly db;
+    private readonly timeoutMs;
+    constructor(adapters: VulnDatabaseAdapter[], db: GraphDatabase, timeoutMs?: number);
+    /**
+     * Enrich all Dependency_Nodes with vulnerability data.
+     *
+     * Uses batch queries (up to 1000 per HTTP request) when the adapter supports
+     * `queryBatch`. Falls back to sequential single queries per dependency if batch
+     * is unavailable or fails. Results are deduplicated by CVE ID across adapters.
+     */
+    enrichAll(): Promise<EnrichmentResult>;
+    /**
+     * Fetch EPSS scores for all stored vulnerabilities and update the database.
+     */
+    private enrichEpss;
+    /**
+     * Compute and persist combined risk scores for all stored vulnerabilities.
+     * Called after EPSS enrichment so epss_score values are up to date.
+     */
+    private computeRiskScores;
+    /**
+     * Batch enrichment path: groups deps into chunks of BATCH_CHUNK_SIZE and sends
+     * one HTTP request per chunk. Falls back to sequential on batch failure.
+     */
+    private enrichAllBatch;
+    /**
+     * Sequential enrichment path: queries one dependency at a time.
+     * Used when the adapter does not support queryBatch, or as a fallback.
+     */
+    private enrichAllSequential;
+    /**
+     * Enrich a single Dependency_Node with vulnerability data.
+     *
+     * @param dependencyNodeId - The node ID of the dependency to enrich
+     * @returns Array of CVE records found for this dependency
+     */
+    enrichOne(dependencyNodeId: string): Promise<CVERecord[]>;
+    /**
+     * Query a set of adapters for a single dependency.
+     * Handles timeouts and unreachable databases gracefully.
+     * Defaults to all configured adapters when adapterList is omitted.
+     */
+    private queryAdaptersForDependency;
+    /**
+     * Mark a dependency node as having stale vulnerability data.
+     * Retains cached data but sets the stale flag with timestamp.
+     */
+    private markDependencyStale;
+    /**
+     * Deduplicate CVE records by their ID.
+     * When the same CVE is reported by multiple databases, keep the first occurrence.
+     */
+    private deduplicateByCveId;
+    /**
+     * Create or update a Vulnerability_Node and link it to the affected dependency.
+     *
+     * - Creates a node in `nodes` table with kind='vulnerability', ID format `vuln:<cve_id>`
+     * - Inserts a row in `sec_vulnerabilities` with CVE metadata
+     * - Creates a `has_vulnerability` edge from the Dependency_Node to the Vulnerability_Node
+     */
+    private upsertVulnerabilityNode;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/security/vuln/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/security/vuln/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAc,MAAM,SAAS,CAAC;AAM/D;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACnC,MAAM,CAoBR;AAaD,qBAAa,2BAA2B;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGjC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,EAAE,EAAE,aAAa,EACjB,SAAS,GAAE,MAAc;IAO3B;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC;IA4C5C;;OAEG;YACW,UAAU;IA+BxB;;;OAGG;YACW,iBAAiB;IAsB/B;;;OAGG;YACW,cAAc;IA4C5B;;;OAGG;YACW,mBAAmB;IAkBjC;;;;;OAKG;IACG,SAAS,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAiD/D;;;;OAIG;YACW,0BAA0B;IA6CxC;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;CAuDhC"}

package/dist/security/vuln/client.js

@@ -0,0 +1,355 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var client_exports = {};
+__export(client_exports, {
+  VulnerabilityDatabaseClient: () => VulnerabilityDatabaseClient,
+  computeRiskScore: () => computeRiskScore
+});
+module.exports = __toCommonJS(client_exports);
+var import_errors = require("../../errors");
+var import_epss_client = require("./epss-client");
+const BATCH_CHUNK_SIZE = 1e3;
+function computeRiskScore(cvss, epss, verdict, staleness) {
+  const cvssNormalized = (cvss ?? 5) / 10;
+  const epssValue = epss ?? 0;
+  let reachabilityFactor;
+  if (verdict === "affected") {
+    reachabilityFactor = 1;
+  } else if (verdict === "under_investigation") {
+    reachabilityFactor = 0.5;
+  } else if (verdict === "not_affected") {
+    reachabilityFactor = 0.1;
+  } else {
+    reachabilityFactor = 0.3;
+  }
+  const stalenessBonus = 1 + (staleness ?? 0) * 0.2;
+  const raw = reachabilityFactor * (0.4 * cvssNormalized + 0.6 * epssValue) * stalenessBonus;
+  return Math.min(raw * 10, 10);
+}
+class VulnerabilityDatabaseClient {
+  constructor(adapters, db, timeoutMs = 3e4) {
+    this.adapters = adapters;
+    this.db = db;
+    this.timeoutMs = timeoutMs;
+  }
+  /**
+   * Enrich all Dependency_Nodes with vulnerability data.
+   *
+   * Uses batch queries (up to 1000 per HTTP request) when the adapter supports
+   * `queryBatch`. Falls back to sequential single queries per dependency if batch
+   * is unavailable or fails. Results are deduplicated by CVE ID across adapters.
+   */
+  async enrichAll() {
+    const rawDb = this.db.getRawDb();
+    const result = {
+      vulnerabilitiesFound: 0,
+      dependenciesChecked: 0,
+      errors: [],
+      staleNodes: []
+    };
+    const depRows = rawDb.all(
+      `SELECT node_id, ecosystem, package_name, resolved_version, declared_constraint
+       FROM sec_dependencies`
+    );
+    const queryableDeps = depRows.filter((d) => d.resolved_version || d.declared_constraint);
+    for (const adapter of this.adapters) {
+      if (adapter.queryBatch) {
+        await this.enrichAllBatch(adapter, queryableDeps, result);
+      } else {
+        await this.enrichAllSequential(adapter, queryableDeps, result);
+      }
+    }
+    const now = Date.now();
+    for (const dep of queryableDeps) {
+      rawDb.run(
+        `UPDATE sec_dependencies SET last_vuln_check = ? WHERE node_id = ?`,
+        [now, dep.node_id]
+      );
+    }
+    result.dependenciesChecked = queryableDeps.length;
+    await this.enrichEpss(rawDb);
+    await this.computeRiskScores(rawDb);
+    return result;
+  }
+  /**
+   * Fetch EPSS scores for all stored vulnerabilities and update the database.
+   */
+  async enrichEpss(rawDb) {
+    try {
+      const cveRows = rawDb.all(
+        `SELECT cve_id FROM sec_vulnerabilities`
+      );
+      if (cveRows.length === 0) {
+        return;
+      }
+      const cveIds = cveRows.map((r) => r.cve_id);
+      const epssClient = new import_epss_client.EpssClient();
+      const scores = await epssClient.fetchScores(cveIds);
+      if (scores.size === 0) {
+        return;
+      }
+      const fetchedAt = Date.now();
+      for (const [cveId, { score, percentile }] of scores) {
+        rawDb.run(
+          `UPDATE sec_vulnerabilities SET epss_score = ?, epss_percentile = ?, epss_fetched_at = ? WHERE cve_id = ?`,
+          [score, percentile, fetchedAt, cveId]
+        );
+      }
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      (0, import_errors.logWarn)(`[sec:epss] EPSS enrichment failed (non-critical): ${msg}`);
+    }
+  }
+  /**
+   * Compute and persist combined risk scores for all stored vulnerabilities.
+   * Called after EPSS enrichment so epss_score values are up to date.
+   */
+  async computeRiskScores(rawDb) {
+    const rows = rawDb.all(`
+      SELECT v.node_id, v.severity_score, v.epss_score,
+             r.verdict,
+             d.staleness_score
+      FROM sec_vulnerabilities v
+      LEFT JOIN edges e ON e.target = v.node_id AND e.kind = 'has_vulnerability'
+      LEFT JOIN sec_dependencies d ON d.node_id = e.source
+      LEFT JOIN sec_reachability r ON r.vulnerability_node_id = v.node_id
+    `);
+    for (const row of rows) {
+      const score = computeRiskScore(row.severity_score, row.epss_score, row.verdict, row.staleness_score);
+      rawDb.run(`UPDATE sec_vulnerabilities SET risk_score = ? WHERE node_id = ?`, [score, row.node_id]);
+    }
+  }
+  /**
+   * Batch enrichment path: groups deps into chunks of BATCH_CHUNK_SIZE and sends
+   * one HTTP request per chunk. Falls back to sequential on batch failure.
+   */
+  async enrichAllBatch(adapter, deps, result) {
+    const rawDb = this.db.getRawDb();
+    for (let i = 0; i < deps.length; i += BATCH_CHUNK_SIZE) {
+      const chunk = deps.slice(i, i + BATCH_CHUNK_SIZE);
+      const queries = chunk.map((dep) => ({
+        ecosystem: dep.ecosystem,
+        packageName: dep.package_name,
+        version: dep.resolved_version || dep.declared_constraint
+      }));
+      let batchResults;
+      try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+          batchResults = await adapter.queryBatch(queries, controller.signal);
+        } finally {
+          clearTimeout(timeout);
+        }
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        (0, import_errors.logWarn)(`[sec:vuln] ${adapter.name} batch query failed (${msg}), falling back to sequential for chunk of ${chunk.length}`);
+        await this.enrichAllSequential(adapter, chunk, result);
+        continue;
+      }
+      for (let j = 0; j < chunk.length; j++) {
+        const dep = chunk[j];
+        const cveRecords = batchResults[j] ?? [];
+        const uniqueCves = this.deduplicateByCveId(cveRecords);
+        for (const cve of uniqueCves) {
+          this.upsertVulnerabilityNode(rawDb, cve, dep.node_id);
+          result.vulnerabilitiesFound++;
+        }
+      }
+    }
+  }
+  /**
+   * Sequential enrichment path: queries one dependency at a time.
+   * Used when the adapter does not support queryBatch, or as a fallback.
+   */
+  async enrichAllSequential(adapter, deps, result) {
+    const rawDb = this.db.getRawDb();
+    for (const dep of deps) {
+      const version = dep.resolved_version || dep.declared_constraint;
+      const cveRecords = await this.queryAdaptersForDependency(dep, version, result, [adapter]);
+      const uniqueCves = this.deduplicateByCveId(cveRecords);
+      for (const cve of uniqueCves) {
+        this.upsertVulnerabilityNode(rawDb, cve, dep.node_id);
+        result.vulnerabilitiesFound++;
+      }
+    }
+  }
+  /**
+   * Enrich a single Dependency_Node with vulnerability data.
+   *
+   * @param dependencyNodeId - The node ID of the dependency to enrich
+   * @returns Array of CVE records found for this dependency
+   */
+  async enrichOne(dependencyNodeId) {
+    const rawDb = this.db.getRawDb();
+    const dep = rawDb.get(
+      `SELECT node_id, ecosystem, package_name, resolved_version, declared_constraint
+       FROM sec_dependencies WHERE node_id = ?`,
+      [dependencyNodeId]
+    );
+    if (!dep) {
+      return [];
+    }
+    const version = dep.resolved_version || dep.declared_constraint;
+    if (!version) {
+      return [];
+    }
+    const enrichResult = {
+      vulnerabilitiesFound: 0,
+      dependenciesChecked: 0,
+      errors: [],
+      staleNodes: []
+    };
+    const cveRecords = await this.queryAdaptersForDependency(
+      dep,
+      version,
+      enrichResult
+    );
+    const uniqueCves = this.deduplicateByCveId(cveRecords);
+    for (const cve of uniqueCves) {
+      this.upsertVulnerabilityNode(rawDb, cve, dep.node_id);
+    }
+    const now = Date.now();
+    rawDb.run(
+      `UPDATE sec_dependencies SET last_vuln_check = ? WHERE node_id = ?`,
+      [now, dep.node_id]
+    );
+    return uniqueCves;
+  }
+  /**
+   * Query a set of adapters for a single dependency.
+   * Handles timeouts and unreachable databases gracefully.
+   * Defaults to all configured adapters when adapterList is omitted.
+   */
+  async queryAdaptersForDependency(dep, version, result, adapterList = this.adapters) {
+    const allRecords = [];
+    for (const adapter of adapterList) {
+      try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+          const records = await adapter.query(
+            dep.ecosystem,
+            dep.package_name,
+            version,
+            controller.signal
+          );
+          allRecords.push(...records);
+        } finally {
+          clearTimeout(timeout);
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        (0, import_errors.logError)(
+          `[sec:vuln] Failed to query ${adapter.name} for ${dep.package_name}@${version}: ${errorMessage}`
+        );
+        result.errors.push({
+          dependency: dep.package_name,
+          database: adapter.name,
+          error: errorMessage
+        });
+        this.markDependencyStale(dep.node_id, result);
+      }
+    }
+    return allRecords;
+  }
+  /**
+   * Mark a dependency node as having stale vulnerability data.
+   * Retains cached data but sets the stale flag with timestamp.
+   */
+  markDependencyStale(nodeId, result) {
+    const rawDb = this.db.getRawDb();
+    const now = Date.now();
+    rawDb.run(
+      `UPDATE sec_dependencies
+       SET vuln_data_stale = 1, vuln_data_stale_since = ?
+       WHERE node_id = ?`,
+      [now, nodeId]
+    );
+    if (!result.staleNodes.includes(nodeId)) {
+      result.staleNodes.push(nodeId);
+    }
+    (0, import_errors.logWarn)(
+      `[sec:vuln] Vulnerability data marked stale for dependency node ${nodeId}`
+    );
+  }
+  /**
+   * Deduplicate CVE records by their ID.
+   * When the same CVE is reported by multiple databases, keep the first occurrence.
+   */
+  deduplicateByCveId(records) {
+    const seen = /* @__PURE__ */ new Map();
+    for (const record of records) {
+      if (!seen.has(record.id)) {
+        seen.set(record.id, record);
+      }
+    }
+    return [...seen.values()];
+  }
+  /**
+   * Create or update a Vulnerability_Node and link it to the affected dependency.
+   *
+   * - Creates a node in `nodes` table with kind='vulnerability', ID format `vuln:<cve_id>`
+   * - Inserts a row in `sec_vulnerabilities` with CVE metadata
+   * - Creates a `has_vulnerability` edge from the Dependency_Node to the Vulnerability_Node
+   */
+  upsertVulnerabilityNode(rawDb, cve, dependencyNodeId) {
+    const vulnNodeId = `vuln:${cve.id}`;
+    const now = Date.now();
+    const summary = cve.summary.length > 500 ? cve.summary.slice(0, 500) : cve.summary;
+    const sourceDatabase = this.adapters.length > 0 ? this.adapters[0].name : "unknown";
+    rawDb.run(
+      `INSERT OR REPLACE INTO nodes
+        (id, kind, name, qualified_name, file_path, language,
+         start_line, end_line, start_column, end_column,
+         is_exported, is_async, is_static, is_abstract, updated_at)
+       VALUES (?, 'vulnerability', ?, ?, '', 'unknown', 0, 0, 0, 0, 0, 0, 0, 0, ?)`,
+      [vulnNodeId, cve.id, cve.id, now]
+    );
+    const affectedRangesJson = JSON.stringify(cve.affectedVersionRanges);
+    rawDb.run(
+      `INSERT OR REPLACE INTO sec_vulnerabilities
+        (node_id, cve_id, severity_score, affected_ranges, fixed_version, summary, source_database)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      [
+        vulnNodeId,
+        cve.id,
+        cve.severity,
+        affectedRangesJson,
+        cve.fixedVersion ?? null,
+        summary,
+        sourceDatabase
+      ]
+    );
+    const edge = {
+      source: dependencyNodeId,
+      target: vulnNodeId,
+      kind: "has_vulnerability",
+      confidence: "extracted",
+      confidenceScore: 1
+    };
+    this.db.insertEdge(edge);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VulnerabilityDatabaseClient,
+  computeRiskScore
+});
+//# sourceMappingURL=client.js.map

package/dist/security/vuln/client.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/security/vuln/client.ts"],
+  "sourcesContent": ["/**\n * VulnerabilityDatabaseClient\n *\n * Orchestrates vulnerability enrichment by querying configured databases,\n * merging and deduplicating results by CVE identifier, creating Vulnerability_Nodes\n * linked to affected Dependency_Nodes, and handling unreachable databases gracefully.\n *\n * Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.7\n */\n\nimport type { GraphDatabase } from '../../db/database';\nimport type { Edge } from '../../types';\nimport type { CVERecord, EnrichmentResult } from '../types';\nimport type { VulnDatabaseAdapter, BatchQuery } from './types';\nimport { logError, logWarn } from '../../errors';\nimport { EpssClient } from './epss-client';\n\nconst BATCH_CHUNK_SIZE = 1000;\n\n/**\n * Compute a combined risk score (0.0\u201310.0) for a vulnerability.\n *\n * Formula:\n *   risk = reachability_factor \u00D7 (0.4 \u00D7 cvss_normalized + 0.6 \u00D7 epss) \u00D7 staleness_bonus\n *   scaled to 0\u201310: min(risk \u00D7 10, 10.0)\n *\n * @param cvss        - CVSS base score (0.0\u201310.0), null treated as 5.0\n * @param epss        - EPSS exploitation probability (0.0\u20131.0), null treated as 0.0\n * @param verdict     - Reachability verdict or null/undefined\n * @param staleness   - Dependency staleness score (0.0\u20131.0), null treated as 0.0\n */\nexport function computeRiskScore(\n  cvss: number | null | undefined,\n  epss: number | null | undefined,\n  verdict: string | null | undefined,\n  staleness: number | null | undefined,\n): number {\n  const cvssNormalized = (cvss ?? 5.0) / 10.0;\n  const epssValue = epss ?? 0.0;\n\n  let reachabilityFactor: number;\n  if (verdict === 'affected') {\n    reachabilityFactor = 1.0;\n  } else if (verdict === 'under_investigation') {\n    reachabilityFactor = 0.5;\n  } else if (verdict === 'not_affected') {\n    reachabilityFactor = 0.1;\n  } else {\n    // no verdict\n    reachabilityFactor = 0.3;\n  }\n\n  const stalenessBonus = 1.0 + ((staleness ?? 0) * 0.2);\n\n  const raw = reachabilityFactor * (0.4 * cvssNormalized + 0.6 * epssValue) * stalenessBonus;\n  return Math.min(raw * 10, 10.0);\n}\n\n/**\n * Dependency row from sec_dependencies table.\n */\ninterface DependencyRow {\n  node_id: string;\n  ecosystem: string;\n  package_name: string;\n  resolved_version: string | null;\n  declared_constraint: string;\n}\n\nexport class VulnerabilityDatabaseClient {\n  private readonly adapters: VulnDatabaseAdapter[];\n  private readonly db: GraphDatabase;\n  private readonly timeoutMs: number;\n\n  constructor(\n    adapters: VulnDatabaseAdapter[],\n    db: GraphDatabase,\n    timeoutMs: number = 30000,\n  ) {\n    this.adapters = adapters;\n    this.db = db;\n    this.timeoutMs = timeoutMs;\n  }\n\n  /**\n   * Enrich all Dependency_Nodes with vulnerability data.\n   *\n   * Uses batch queries (up to 1000 per HTTP request) when the adapter supports\n   * `queryBatch`. Falls back to sequential single queries per dependency if batch\n   * is unavailable or fails. Results are deduplicated by CVE ID across adapters.\n   */\n  async enrichAll(): Promise<EnrichmentResult> {\n    const rawDb = this.db.getRawDb();\n    const result: EnrichmentResult = {\n      vulnerabilitiesFound: 0,\n      dependenciesChecked: 0,\n      errors: [],\n      staleNodes: [],\n    };\n\n    const depRows: DependencyRow[] = rawDb.all(\n      `SELECT node_id, ecosystem, package_name, resolved_version, declared_constraint\n       FROM sec_dependencies`,\n    );\n\n    // Filter out deps with no usable version\n    const queryableDeps = depRows.filter(d => d.resolved_version || d.declared_constraint);\n\n    for (const adapter of this.adapters) {\n      if (adapter.queryBatch) {\n        await this.enrichAllBatch(adapter as typeof adapter & Required<Pick<typeof adapter, 'queryBatch'>>, queryableDeps, result);\n      } else {\n        await this.enrichAllSequential(adapter, queryableDeps, result);\n      }\n    }\n\n    // Record lastVulnCheck for all queried deps (do once, after all adapters)\n    const now = Date.now();\n    for (const dep of queryableDeps) {\n      rawDb.run(\n        `UPDATE sec_dependencies SET last_vuln_check = ? WHERE node_id = ?`,\n        [now, dep.node_id],\n      );\n    }\n    result.dependenciesChecked = queryableDeps.length;\n\n    // Enrich stored vulnerabilities with EPSS scores\n    await this.enrichEpss(rawDb);\n\n    // Compute combined risk scores after all enrichment is done\n    await this.computeRiskScores(rawDb);\n\n    return result;\n  }\n\n  /**\n   * Fetch EPSS scores for all stored vulnerabilities and update the database.\n   */\n  private async enrichEpss(rawDb: any): Promise<void> {\n    try {\n      const cveRows: Array<{ cve_id: string }> = rawDb.all(\n        `SELECT cve_id FROM sec_vulnerabilities`,\n      );\n\n      if (cveRows.length === 0) {\n        return;\n      }\n\n      const cveIds = cveRows.map(r => r.cve_id);\n      const epssClient = new EpssClient();\n      const scores = await epssClient.fetchScores(cveIds);\n\n      if (scores.size === 0) {\n        return;\n      }\n\n      const fetchedAt = Date.now();\n      for (const [cveId, { score, percentile }] of scores) {\n        rawDb.run(\n          `UPDATE sec_vulnerabilities SET epss_score = ?, epss_percentile = ?, epss_fetched_at = ? WHERE cve_id = ?`,\n          [score, percentile, fetchedAt, cveId],\n        );\n      }\n    } catch (error: unknown) {\n      const msg = error instanceof Error ? error.message : String(error);\n      logWarn(`[sec:epss] EPSS enrichment failed (non-critical): ${msg}`);\n    }\n  }\n\n  /**\n   * Compute and persist combined risk scores for all stored vulnerabilities.\n   * Called after EPSS enrichment so epss_score values are up to date.\n   */\n  private async computeRiskScores(rawDb: any): Promise<void> {\n    const rows: Array<{\n      node_id: string;\n      severity_score: number | null;\n      epss_score: number | null;\n      verdict: string | null;\n      staleness_score: number | null;\n    }> = rawDb.all(`\n      SELECT v.node_id, v.severity_score, v.epss_score,\n             r.verdict,\n             d.staleness_score\n      FROM sec_vulnerabilities v\n      LEFT JOIN edges e ON e.target = v.node_id AND e.kind = 'has_vulnerability'\n      LEFT JOIN sec_dependencies d ON d.node_id = e.source\n      LEFT JOIN sec_reachability r ON r.vulnerability_node_id = v.node_id\n    `);\n    for (const row of rows) {\n      const score = computeRiskScore(row.severity_score, row.epss_score, row.verdict, row.staleness_score);\n      rawDb.run(`UPDATE sec_vulnerabilities SET risk_score = ? WHERE node_id = ?`, [score, row.node_id]);\n    }\n  }\n\n  /**\n   * Batch enrichment path: groups deps into chunks of BATCH_CHUNK_SIZE and sends\n   * one HTTP request per chunk. Falls back to sequential on batch failure.\n   */\n  private async enrichAllBatch(\n    adapter: VulnDatabaseAdapter & Required<Pick<VulnDatabaseAdapter, 'queryBatch'>>,\n    deps: DependencyRow[],\n    result: EnrichmentResult,\n  ): Promise<void> {\n    const rawDb = this.db.getRawDb();\n\n    for (let i = 0; i < deps.length; i += BATCH_CHUNK_SIZE) {\n      const chunk = deps.slice(i, i + BATCH_CHUNK_SIZE);\n      const queries: BatchQuery[] = chunk.map(dep => ({\n        ecosystem: dep.ecosystem,\n        packageName: dep.package_name,\n        version: dep.resolved_version || dep.declared_constraint,\n      }));\n\n      let batchResults: Array<CVERecord[]>;\n      try {\n        const controller = new AbortController();\n        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);\n        try {\n          batchResults = await adapter.queryBatch(queries, controller.signal);\n        } finally {\n          clearTimeout(timeout);\n        }\n      } catch (error: unknown) {\n        // Batch failed \u2014 fall back to sequential for this chunk\n        const msg = error instanceof Error ? error.message : String(error);\n        logWarn(`[sec:vuln] ${adapter.name} batch query failed (${msg}), falling back to sequential for chunk of ${chunk.length}`);\n        await this.enrichAllSequential(adapter, chunk, result);\n        continue;\n      }\n\n      for (let j = 0; j < chunk.length; j++) {\n        const dep = chunk[j]!;\n        const cveRecords = batchResults[j] ?? [];\n        const uniqueCves = this.deduplicateByCveId(cveRecords);\n        for (const cve of uniqueCves) {\n          this.upsertVulnerabilityNode(rawDb, cve, dep.node_id);\n          result.vulnerabilitiesFound++;\n        }\n      }\n    }\n  }\n\n  /**\n   * Sequential enrichment path: queries one dependency at a time.\n   * Used when the adapter does not support queryBatch, or as a fallback.\n   */\n  private async enrichAllSequential(\n    adapter: VulnDatabaseAdapter,\n    deps: DependencyRow[],\n    result: EnrichmentResult,\n  ): Promise<void> {\n    const rawDb = this.db.getRawDb();\n\n    for (const dep of deps) {\n      const version = dep.resolved_version || dep.declared_constraint;\n      const cveRecords = await this.queryAdaptersForDependency(dep, version, result, [adapter]);\n      const uniqueCves = this.deduplicateByCveId(cveRecords);\n      for (const cve of uniqueCves) {\n        this.upsertVulnerabilityNode(rawDb, cve, dep.node_id);\n        result.vulnerabilitiesFound++;\n      }\n    }\n  }\n\n  /**\n   * Enrich a single Dependency_Node with vulnerability data.\n   *\n   * @param dependencyNodeId - The node ID of the dependency to enrich\n   * @returns Array of CVE records found for this dependency\n   */\n  async enrichOne(dependencyNodeId: string): Promise<CVERecord[]> {\n    const rawDb = this.db.getRawDb();\n\n    const dep: DependencyRow | undefined = rawDb.get(\n      `SELECT node_id, ecosystem, package_name, resolved_version, declared_constraint\n       FROM sec_dependencies WHERE node_id = ?`,\n      [dependencyNodeId],\n    );\n\n    if (!dep) {\n      return [];\n    }\n\n    const version = dep.resolved_version || dep.declared_constraint;\n    if (!version) {\n      return [];\n    }\n\n    const enrichResult: EnrichmentResult = {\n      vulnerabilitiesFound: 0,\n      dependenciesChecked: 0,\n      errors: [],\n      staleNodes: [],\n    };\n\n    const cveRecords = await this.queryAdaptersForDependency(\n      dep,\n      version,\n      enrichResult,\n    );\n\n    // Deduplicate by CVE ID\n    const uniqueCves = this.deduplicateByCveId(cveRecords);\n\n    // Create Vulnerability_Nodes and edges\n    for (const cve of uniqueCves) {\n      this.upsertVulnerabilityNode(rawDb, cve, dep.node_id);\n    }\n\n    // Record lastVulnCheck timestamp\n    const now = Date.now();\n    rawDb.run(\n      `UPDATE sec_dependencies SET last_vuln_check = ? WHERE node_id = ?`,\n      [now, dep.node_id],\n    );\n\n    return uniqueCves;\n  }\n\n  /**\n   * Query a set of adapters for a single dependency.\n   * Handles timeouts and unreachable databases gracefully.\n   * Defaults to all configured adapters when adapterList is omitted.\n   */\n  private async queryAdaptersForDependency(\n    dep: DependencyRow,\n    version: string,\n    result: EnrichmentResult,\n    adapterList: VulnDatabaseAdapter[] = this.adapters,\n  ): Promise<CVERecord[]> {\n    const allRecords: CVERecord[] = [];\n\n    for (const adapter of adapterList) {\n      try {\n        const controller = new AbortController();\n        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);\n\n        try {\n          const records = await adapter.query(\n            dep.ecosystem,\n            dep.package_name,\n            version,\n            controller.signal,\n          );\n          allRecords.push(...records);\n        } finally {\n          clearTimeout(timeout);\n        }\n      } catch (error: unknown) {\n        // Handle unreachable database (Requirement 3.5)\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        logError(\n          `[sec:vuln] Failed to query ${adapter.name} for ${dep.package_name}@${version}: ${errorMessage}`,\n        );\n\n        result.errors.push({\n          dependency: dep.package_name,\n          database: adapter.name,\n          error: errorMessage,\n        });\n\n        // Set vulnDataStale flag on the dependency node\n        this.markDependencyStale(dep.node_id, result);\n      }\n    }\n\n    return allRecords;\n  }\n\n  /**\n   * Mark a dependency node as having stale vulnerability data.\n   * Retains cached data but sets the stale flag with timestamp.\n   */\n  private markDependencyStale(nodeId: string, result: EnrichmentResult): void {\n    const rawDb = this.db.getRawDb();\n    const now = Date.now();\n\n    rawDb.run(\n      `UPDATE sec_dependencies\n       SET vuln_data_stale = 1, vuln_data_stale_since = ?\n       WHERE node_id = ?`,\n      [now, nodeId],\n    );\n\n    if (!result.staleNodes.includes(nodeId)) {\n      result.staleNodes.push(nodeId);\n    }\n\n    logWarn(\n      `[sec:vuln] Vulnerability data marked stale for dependency node ${nodeId}`,\n    );\n  }\n\n  /**\n   * Deduplicate CVE records by their ID.\n   * When the same CVE is reported by multiple databases, keep the first occurrence.\n   */\n  private deduplicateByCveId(records: CVERecord[]): CVERecord[] {\n    const seen = new Map<string, CVERecord>();\n    for (const record of records) {\n      if (!seen.has(record.id)) {\n        seen.set(record.id, record);\n      }\n    }\n    return [...seen.values()];\n  }\n\n  /**\n   * Create or update a Vulnerability_Node and link it to the affected dependency.\n   *\n   * - Creates a node in `nodes` table with kind='vulnerability', ID format `vuln:<cve_id>`\n   * - Inserts a row in `sec_vulnerabilities` with CVE metadata\n   * - Creates a `has_vulnerability` edge from the Dependency_Node to the Vulnerability_Node\n   */\n  private upsertVulnerabilityNode(\n    rawDb: any,\n    cve: CVERecord,\n    dependencyNodeId: string,\n  ): void {\n    const vulnNodeId = `vuln:${cve.id}`;\n    const now = Date.now();\n\n    // Truncate summary to 500 characters (Requirement 3.3)\n    const summary = cve.summary.length > 500\n      ? cve.summary.slice(0, 500)\n      : cve.summary;\n\n    // Determine source database from the first adapter that returned this CVE\n    // (in practice, the adapter name is not stored on CVERecord, so we use\n    // the first configured adapter's name as the source)\n    const sourceDatabase = this.adapters.length > 0 ? this.adapters[0].name : 'unknown';\n\n    // Upsert into nodes table\n    rawDb.run(\n      `INSERT OR REPLACE INTO nodes\n        (id, kind, name, qualified_name, file_path, language,\n         start_line, end_line, start_column, end_column,\n         is_exported, is_async, is_static, is_abstract, updated_at)\n       VALUES (?, 'vulnerability', ?, ?, '', 'unknown', 0, 0, 0, 0, 0, 0, 0, 0, ?)`,\n      [vulnNodeId, cve.id, cve.id, now],\n    );\n\n    // Upsert into sec_vulnerabilities table\n    const affectedRangesJson = JSON.stringify(cve.affectedVersionRanges);\n    rawDb.run(\n      `INSERT OR REPLACE INTO sec_vulnerabilities\n        (node_id, cve_id, severity_score, affected_ranges, fixed_version, summary, source_database)\n       VALUES (?, ?, ?, ?, ?, ?, ?)`,\n      [\n        vulnNodeId,\n        cve.id,\n        cve.severity,\n        affectedRangesJson,\n        cve.fixedVersion ?? null,\n        summary,\n        sourceDatabase,\n      ],\n    );\n\n    // Create has_vulnerability edge from Dependency_Node to Vulnerability_Node\n    const edge: Edge = {\n      source: dependencyNodeId,\n      target: vulnNodeId,\n      kind: 'has_vulnerability',\n      confidence: 'extracted',\n      confidenceScore: 1.0,\n    };\n    this.db.insertEdge(edge);\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/security/vuln/epss-client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * EPSS (Exploit Prediction Scoring System) Client
+ *
+ * Fetches exploit prediction scores from the FIRST.org EPSS API for CVE IDs.
+ * EPSS is non-critical: on error, an empty map is returned so the caller can
+ * continue without scores.
+ *
+ * API: https://api.first.org/data/v1/epss
+ */
+export declare class EpssClient {
+    /**
+     * Fetch EPSS scores for a list of CVE IDs.
+     *
+     * CVEs are batched into chunks of 500 per request. Missing CVEs simply do
+     * not appear in the response and are omitted from the returned map.
+     *
+     * @param cveIds - List of CVE identifiers (e.g. ["CVE-2021-44228", ...])
+     * @returns Map from CVE ID to { score, percentile } (floats in [0, 1])
+     */
+    fetchScores(cveIds: string[]): Promise<Map<string, {
+        score: number;
+        percentile: number;
+    }>>;
+    private fetchChunk;
+}
+//# sourceMappingURL=epss-client.d.ts.map

package/dist/security/vuln/epss-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epss-client.d.ts","sourceRoot":"","sources":["../../../src/security/vuln/epss-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAmBH,qBAAa,UAAU;IACrB;;;;;;;;OAQG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;YAwBlF,UAAU;CA2CzB"}

package/dist/security/vuln/epss-client.js

@@ -0,0 +1,95 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var epss_client_exports = {};
+__export(epss_client_exports, {
+  EpssClient: () => EpssClient
+});
+module.exports = __toCommonJS(epss_client_exports);
+var import_errors = require("../../errors");
+const EPSS_API_URL = "https://api.first.org/data/v1/epss";
+const CHUNK_SIZE = 500;
+const TIMEOUT_MS = 3e4;
+class EpssClient {
+  /**
+   * Fetch EPSS scores for a list of CVE IDs.
+   *
+   * CVEs are batched into chunks of 500 per request. Missing CVEs simply do
+   * not appear in the response and are omitted from the returned map.
+   *
+   * @param cveIds - List of CVE identifiers (e.g. ["CVE-2021-44228", ...])
+   * @returns Map from CVE ID to { score, percentile } (floats in [0, 1])
+   */
+  async fetchScores(cveIds) {
+    const result = /* @__PURE__ */ new Map();
+    if (cveIds.length === 0) {
+      return result;
+    }
+    for (let i = 0; i < cveIds.length; i += CHUNK_SIZE) {
+      const chunk = cveIds.slice(i, i + CHUNK_SIZE);
+      try {
+        const chunkResult = await this.fetchChunk(chunk);
+        for (const [cve, scores] of chunkResult) {
+          result.set(cve, scores);
+        }
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        (0, import_errors.logWarn)(`[sec:epss] Failed to fetch EPSS scores for chunk of ${chunk.length} CVEs: ${msg}`);
+      }
+    }
+    return result;
+  }
+  async fetchChunk(cveIds) {
+    const result = /* @__PURE__ */ new Map();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+      const cveParam = cveIds.join(",");
+      const url = `${EPSS_API_URL}?cve=${encodeURIComponent(cveParam)}`;
+      const response = await fetch(url, { signal: controller.signal });
+      if (!response.ok) {
+        (0, import_errors.logWarn)(`[sec:epss] EPSS API returned HTTP ${response.status}`);
+        return result;
+      }
+      const json = await response.json();
+      if (json.status !== "OK" || !Array.isArray(json.data)) {
+        (0, import_errors.logWarn)(`[sec:epss] Unexpected EPSS API response structure`);
+        return result;
+      }
+      for (const entry of json.data) {
+        const score = parseFloat(entry.epss);
+        const percentile = parseFloat(entry.percentile);
+        if (!isNaN(score) && !isNaN(percentile)) {
+          result.set(entry.cve, { score, percentile });
+        }
+      }
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      (0, import_errors.logError)(`[sec:epss] Error fetching EPSS chunk: ${msg}`);
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+    return result;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EpssClient
+});
+//# sourceMappingURL=epss-client.js.map