@lincoln504/pi-research 0.1.12 → 1.0.0

package/src/security/cisa-kev.ts

@@ -7,10 +7,20 @@
  */
 
 import type { Vulnerability, CisaKevResult } from './types.ts';
-import { createTimeoutSignal } from '../web-research/retry-utils.ts';
+import { createTimeoutSignal, retryWithBackoff, isTransientError } from '../web-research/retry-utils.ts';
+import { CircuitBreaker } from '../utils/circuit-breaker.ts';
+import { metrics } from '../utils/metrics.ts';
 
 const CISA_KEV_URL = 'https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json';
 
+// Circuit breaker to prevent cascading failures
+const cisaCircuitBreaker = new CircuitBreaker({
+  failureThreshold: 5,
+  resetTimeoutMs: 10000,
+  name: 'CISA KEV API',
+  isTransientError: isTransientError
+});
+
 // ============================================================================
 // Type Definitions for CISA KEV API
 // ============================================================================
@@ -102,6 +112,42 @@ function extractCisaKevItems(data: unknown): readonly CisaKevItem[] {
 // Main API Functions
 // ============================================================================
 
+/**
+ * Fetch with retry and circuit breaker for resilience
+ */
+async function fetchWithRetryImpl(url: string, options: RequestInit, signal?: AbortSignal): Promise<Response> {
+  const endpoint = 'cisa_kev_feed';
+  return cisaCircuitBreaker.execute(async () => {
+    return retryWithBackoff(
+      async () => {
+        const response = await fetch(url, options);
+        if (!response.ok) {
+          const error = new Error(`HTTP ${response.status}: ${response.statusText}`) as Error & { status?: number };
+          error.status = response.status;
+          metrics.increment('cisa_kev_errors_total', 1, { endpoint, status_code: response.status.toString() });
+          throw error;
+        }
+        metrics.increment('cisa_kev_requests_total', 1, { endpoint, status: 'success' });
+        return response;
+      },
+      {
+        maxRetries: 3,
+        initialDelay: 1000,
+        maxDelay: 10000,
+        label: 'CISA KEV API',
+        signal,
+        isTransientError: (error) => {
+          const status = (error as Error & { status?: number })?.status;
+          if (typeof status === 'number') {
+            return status === 429 || status === 403 || status >= 500;
+          }
+          return isTransientError(error);
+        },
+      },
+    );
+  });
+}
+
 /**
  * Fetch and search CISA KEV catalog
  *
@@ -115,29 +161,36 @@ export async function searchCisaKev(
     readonly vendor?: string;
     readonly product?: string;
     readonly maxResults?: number;
+    readonly signal?: AbortSignal;
   },
 ): Promise<CisaKevResult> {
+  const startTime = Date.now();
   const maxResults = options?.maxResults ?? 100;
   const vulnerabilities: Vulnerability[] = [];
   let error: string | undefined = undefined;
 
   try {
-    const response: Response = await fetch(CISA_KEV_URL, {
+    const response: Response = await fetchWithRetryImpl(CISA_KEV_URL, {
       headers: {
         'User-Agent': 'pi-research/2.0',
         'Accept': 'application/json',
       },
-      signal: createTimeoutSignal(30000), // 30s timeout
-    });
+      signal: createTimeoutSignal(30000, options?.signal), // 30s timeout, composed with caller cancel
+    }, options?.signal);
 
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    let data: unknown;
+    try {
+      data = await response.json();
+    } catch {
+      metrics.increment('cisa_kev_errors_total', 1, { error_type: 'malformed_json' });
+      throw new Error('CISA KEV feed returned a malformed JSON response.');
     }
 
-    const data: unknown = await response.json();
-
     // CISA KEV format is an array of vulnerability objects or nested in a response object
     const cisaData = extractCisaKevItems(data);
+    
+    // Track cache metrics
+    metrics.increment(cisaData.length > 0 ? 'cisa_kev_cache_hits_total' : 'cisa_kev_cache_misses_total', 1);
 
     // Map CISA format to our Vulnerability interface
     for (const item of cisaData) {
@@ -170,6 +223,7 @@ export async function searchCisaKev(
     }
 
     // Sort by due date (most urgent first)
+    // FIX (#24): Guard against NaN from invalid dates to ensure stable sort
     vulnerabilities.sort((a: Vulnerability, b: Vulnerability): number => {
       if (a.dueDate === undefined) {
         return 1;
@@ -177,11 +231,20 @@ export async function searchCisaKev(
       if (b.dueDate === undefined) {
         return -1;
       }
-      return new Date(a.dueDate).getTime() - new Date(b.dueDate).getTime();
+      const aTime = new Date(a.dueDate).getTime();
+      const bTime = new Date(b.dueDate).getTime();
+      // Treat invalid dates as Infinity (sorted to the end)
+      const aSafe = Number.isFinite(aTime) ? aTime : Infinity;
+      const bSafe = Number.isFinite(bTime) ? bTime : Infinity;
+      return aSafe - bSafe;
     });
 
   } catch (err: unknown) {
     error = err instanceof Error ? err.message : String(err);
+    metrics.increment('cisa_kev_search_errors_total', 1, { error_type: err instanceof Error ? err.name : 'unknown' });
+  } finally {
+    const duration = Date.now() - startTime;
+    metrics.observe('cisa_kev_fetch_duration_ms', duration, { has_error: error ? 'true' : 'false' });
   }
 
   return {

package/src/security/cvss.ts

@@ -0,0 +1,92 @@
+/**
+ * Minimal CVSS v3.0/v3.1 base-score calculator.
+ *
+ * Used to derive a qualitative severity + numeric base score from a CVSS vector STRING (OSV
+ * `severity[]` entries carry a vector, not a number). Implements the official base-score equations,
+ * which are IDENTICAL across v3.0 and v3.1 — there is no version branch in Base scoring. (The
+ * `× 0.9731`/exponent-13 changed-scope variant belongs only to the v3.1 Environmental metric group,
+ * not to Base; applying it here would mis-band high-impact changed-scope vectors, e.g. reporting
+ * the changed-scope vector AV:P/AC:H/PR:H/UI:N/S:C/C:H/I:H/A:H as 7.0/HIGH instead of 6.9/MEDIUM.)
+ * Returns null for a vector it
+ * cannot parse, a non-v3 vector, or an incomplete base vector — callers then fall back to UNKNOWN
+ * rather than guess.
+ *
+ * Only the BASE metric group is computed (temporal/environmental are ignored), which is what a
+ * severity label reflects. Verified against the CVSS v3.1 specification examples (9.8, 7.8, 6.1, 5.9)
+ * and the changed-scope case AV:P/AC:H/PR:H/UI:N/S:C/C:H/I:H/A:H → 6.9/MEDIUM (the shorthand
+ * S:C/C:H/I:H/A:H alone, with default AV:N/AC:L/PR:N/UI:N, actually scores 10.0/CRITICAL).
+ */
+
+const AV: Readonly<Record<string, number>> = { N: 0.85, A: 0.62, L: 0.55, P: 0.2 };
+const AC: Readonly<Record<string, number>> = { L: 0.77, H: 0.44 };
+const UI: Readonly<Record<string, number>> = { N: 0.85, R: 0.62 };
+// Privileges Required weight depends on Scope (higher when the attack crosses a scope boundary).
+const PR_UNCHANGED: Readonly<Record<string, number>> = { N: 0.85, L: 0.62, H: 0.27 };
+const PR_CHANGED: Readonly<Record<string, number>> = { N: 0.85, L: 0.68, H: 0.5 };
+const IMPACT: Readonly<Record<string, number>> = { H: 0.56, L: 0.22, N: 0 };
+
+/** CVSS v3.1 Roundup: the smallest number to one decimal place that is >= input (float-safe). */
+function roundUp1(input: number): number {
+  const intInput = Math.round(input * 100000);
+  if (intInput % 10000 === 0) return intInput / 100000;
+  return (Math.floor(intInput / 10000) + 1) / 10;
+}
+
+/** Map a CVSS base score (0.0–10.0) to its qualitative severity rating (CVSS v3 bands). */
+export function severityFromScore(score: number): string {
+  if (score <= 0) return 'NONE';
+  if (score < 4.0) return 'LOW';
+  if (score < 7.0) return 'MEDIUM';
+  if (score < 9.0) return 'HIGH';
+  return 'CRITICAL';
+}
+
+/**
+ * Compute the CVSS v3.0/v3.1 base score + severity from a vector string, or null if it is not a
+ * parseable, complete v3 base vector.
+ */
+export function scoreCvss3(vector: string): { score: number; severity: string } | null {
+  // Accept only complete v3.0 / v3.1 base vectors. The Base formula is identical across both.
+  if (typeof vector !== 'string' || !/^CVSS:3\.[01]\//i.test(vector)) return null;
+
+  const metrics: Record<string, string> = {};
+  for (const part of vector.split('/').slice(1)) {
+    const [k, v] = part.split(':');
+    if (k && v) metrics[k.toUpperCase()] = v.toUpperCase();
+  }
+
+  const scope = metrics['S'];
+  const av = AV[metrics['AV'] ?? ''];
+  const ac = AC[metrics['AC'] ?? ''];
+  const ui = UI[metrics['UI'] ?? ''];
+  const pr = (scope === 'C' ? PR_CHANGED : PR_UNCHANGED)[metrics['PR'] ?? ''];
+  const c = IMPACT[metrics['C'] ?? ''];
+  const i = IMPACT[metrics['I'] ?? ''];
+  const a = IMPACT[metrics['A'] ?? ''];
+
+  if ((scope !== 'U' && scope !== 'C') || [av, ac, ui, pr, c, i, a].some(x => x === undefined)) {
+    return null; // incomplete / invalid base vector
+  }
+
+  const iss = 1 - (1 - c!) * (1 - i!) * (1 - a!);
+  // The CVSS v3.0 and v3.1 BASE impact formulas are identical for both scopes — the `× 0.9731`
+  // multiplier / exponent-13 variant belongs ONLY to the v3.1 Environmental (ModifiedImpact)
+  // metric group, never to Base scoring. Applying it here mis-scored high-impact changed-scope
+  // vectors across a severity band (e.g. S:C/C:H/I:H/A:H → 7.0/HIGH instead of the correct
+  // 6.9/MEDIUM). There is no version branch in Base scoring.
+  const impact = scope === 'U'
+    ? 6.42 * iss
+    : 7.52 * (iss - 0.029) - 3.25 * Math.pow(iss - 0.02, 15);
+  const exploitability = 8.22 * av! * ac! * pr! * ui!;
+
+  let score: number;
+  if (impact <= 0) {
+    score = 0;
+  } else if (scope === 'U') {
+    score = roundUp1(Math.min(impact + exploitability, 10));
+  } else {
+    score = roundUp1(Math.min(1.08 * (impact + exploitability), 10));
+  }
+
+  return { score, severity: severityFromScore(score) };
+}

package/src/security/ecosystem.ts

@@ -0,0 +1,45 @@
+/**
+ * Ecosystem-name normalization for the vulnerability databases.
+ *
+ * GitHub's Advisory Database and OSV use DIFFERENT identifiers for the same package ecosystem
+ * (e.g. GitHub wants `pip`/`rust`/`go`, OSV wants `PyPI`/`crates.io`/`Go`). The security tool
+ * accepts one user-facing `ecosystem` value, so a name that works for one database would be
+ * rejected outright by the other (GitHub 422 / OSV 400) — a guaranteed, silent lookup failure
+ * for common ecosystems like Python and Rust. This maps a user-friendly value onto the exact
+ * identifier each database expects. Unknown values pass through unchanged (prior behavior), so
+ * this can only fix a mismatch, never introduce one.
+ */
+
+/** Canonical ecosystem key → per-database identifier. Keys are matched case-insensitively. */
+const ECOSYSTEM_ALIASES: Record<string, { github: string; osv: string }> = {
+  npm: { github: 'npm', osv: 'npm' },
+  node: { github: 'npm', osv: 'npm' },
+  pip: { github: 'pip', osv: 'PyPI' },
+  pypi: { github: 'pip', osv: 'PyPI' },
+  python: { github: 'pip', osv: 'PyPI' },
+  maven: { github: 'maven', osv: 'Maven' },
+  go: { github: 'go', osv: 'Go' },
+  golang: { github: 'go', osv: 'Go' },
+  cargo: { github: 'rust', osv: 'crates.io' },
+  rust: { github: 'rust', osv: 'crates.io' },
+  'crates.io': { github: 'rust', osv: 'crates.io' },
+  nuget: { github: 'nuget', osv: 'NuGet' },
+  rubygems: { github: 'rubygems', osv: 'RubyGems' },
+  gem: { github: 'rubygems', osv: 'RubyGems' },
+  gems: { github: 'rubygems', osv: 'RubyGems' },
+  composer: { github: 'composer', osv: 'Packagist' },
+  packagist: { github: 'composer', osv: 'Packagist' },
+  php: { github: 'composer', osv: 'Packagist' },
+  pub: { github: 'pub', osv: 'Pub' },
+  dart: { github: 'pub', osv: 'Pub' },
+};
+
+/**
+ * Map a user-supplied ecosystem name to the identifier the given database expects.
+ * Returns the input verbatim (trimmed) when it isn't a known alias.
+ */
+export function normalizeEcosystem(value: string, target: 'github' | 'osv'): string {
+  const key = value.trim().toLowerCase();
+  const entry = ECOSYSTEM_ALIASES[key];
+  return entry ? entry[target] : value.trim();
+}