@nexus_js/audit 0.6.0 → 0.7.1

package/src/engine.ts

@@ -1,322 +0,0 @@
-/**
- * Nexus Audit Engine — CVE Database via OSV (Open Source Vulnerabilities).
- *
- * Uses the free, open Google OSV API (https://osv.dev) — no API key required.
- * Responses are cached locally in ~/.nexus/cache/ for offline operation.
- *
- * API reference: https://google.github.io/osv.dev/api/
- *
- * Cache strategy:
- *  - Queries are cached per package@version for 24h (TTL configurable)
- *  - On offline: stale cache is used transparently (no error)
- *  - Cache location: ~/.nexus/cache/osv/{pkg-name}.json
- *
- * OSV severity mapping to Nexus levels:
- *   CRITICAL → critical  (CVSS ≥ 9.0 or explicit CRITICAL)
- *   HIGH     → high      (CVSS 7.0–8.9)
- *   MEDIUM   → medium    (CVSS 4.0–6.9)
- *   LOW      → low       (CVSS < 4.0)
- */
-
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
-
-const OSV_API      = 'https://api.osv.dev/v1/query';
-const CACHE_DIR    = join(homedir(), '.nexus', 'cache', 'osv');
-const CACHE_TTL_MS = 24 * 60 * 60 * 1_000; // 24h
-
-// ── Types ─────────────────────────────────────────────────────────────────────
-
-export type VulnSeverity = 'critical' | 'high' | 'medium' | 'low' | 'unknown';
-
-export interface Vulnerability {
-  id:               string;        // e.g. 'GHSA-29mw-wpgm-hmr9' or 'CVE-2024-1234'
-  summary:          string;
-  severity:         VulnSeverity;
-  cvss?:            number | undefined;   // CVSS v3 base score
-  aliases:          string[];             // CVE IDs and other aliases
-  affectedVersions: string;              // human-readable range
-  fixedIn?:         string | undefined;   // first patched version
-  references:       string[];            // advisory URLs
-  published:        string;              // ISO date
-}
-
-export interface AuditResult {
-  package:     string;
-  version:     string;
-  status:      'safe' | 'vulnerable' | 'unknown';
-  vulns:       Vulnerability[];
-  /** True if result came from local cache */
-  cached:      boolean;
-  /** True if result is stale (TTL expired) but used because offline */
-  stale:       boolean;
-  checkedAt:   number;
-}
-
-interface CacheEntry {
-  result:    AuditResult;
-  expiresAt: number;
-  version:   string;
-}
-
-interface OsvResponse {
-  vulns?: OsvVuln[];
-}
-
-interface OsvVuln {
-  id:         string;
-  summary?:   string;
-  aliases?:   string[];
-  published:  string;
-  references?: Array<{ url: string }>;
-  severity?:  Array<{ type: string; score: string }>;
-  affected?:  Array<{
-    package?:  { name: string; ecosystem: string };
-    ranges?:   Array<{ type: string; events: Array<{ introduced?: string; fixed?: string }> }>;
-    versions?: string[];
-  }>;
-}
-
-// ── Cache helpers ─────────────────────────────────────────────────────────────
-
-async function ensureCacheDir(): Promise<void> {
-  try {
-    await mkdir(CACHE_DIR, { recursive: true });
-  } catch { /* already exists */ }
-}
-
-function cacheKey(pkg: string): string {
-  return pkg.replace(/\//g, '__').replace(/@/g, '_at_');
-}
-
-async function readCache(pkg: string): Promise<CacheEntry | null> {
-  try {
-    const raw = await readFile(join(CACHE_DIR, `${cacheKey(pkg)}.json`), 'utf-8');
-    return JSON.parse(raw) as CacheEntry;
-  } catch { return null; }
-}
-
-async function writeCache(pkg: string, entry: CacheEntry): Promise<void> {
-  await ensureCacheDir();
-  try {
-    await writeFile(join(CACHE_DIR, `${cacheKey(pkg)}.json`), JSON.stringify(entry, null, 2));
-  } catch { /* cache write failure is non-fatal */ }
-}
-
-// ── OSV API ───────────────────────────────────────────────────────────────────
-
-function parseSeverity(vuln: OsvVuln): { severity: VulnSeverity; cvss?: number } {
-  const severityBlock = vuln.severity ?? [];
-
-  // Look for CVSS v3 score first
-  for (const s of severityBlock) {
-    if (s.type === 'CVSS_V3' || s.type === 'CVSS_V4') {
-      // Extract numeric score from vector string (e.g. "CVSS:3.1/AV:N/AC:L/...")
-      // OSV also sometimes provides the numeric score directly
-      const scoreMatch = s.score.match(/^(\d+\.\d+)$/) ??
-                         s.score.match(/\/(\d+\.\d+)$/);
-      const score = scoreMatch ? parseFloat(scoreMatch[1] ?? '0') : 0;
-      let sev: VulnSeverity = 'unknown';
-      if (score >= 9.0) sev = 'critical';
-      else if (score >= 7.0) sev = 'high';
-      else if (score >= 4.0) sev = 'medium';
-      else if (score > 0)    sev = 'low';
-      return { severity: sev, cvss: score };
-    }
-  }
-
-  // Fall back to explicit severity labels in the ID
-  const id = vuln.id.toUpperCase();
-  if (id.includes('CRITICAL')) return { severity: 'critical' };
-  if (id.includes('HIGH'))     return { severity: 'high' };
-  if (id.includes('MEDIUM'))   return { severity: 'medium' };
-  if (id.includes('LOW'))      return { severity: 'low' };
-  return { severity: 'unknown' };
-}
-
-function parseFixedVersion(vuln: OsvVuln): string | undefined {
-  for (const affected of vuln.affected ?? []) {
-    for (const range of affected.ranges ?? []) {
-      for (const event of range.events ?? []) {
-        if (event.fixed) return event.fixed;
-      }
-    }
-  }
-  return undefined;
-}
-
-function parseAffectedVersions(vuln: OsvVuln): string {
-  const parts: string[] = [];
-  for (const affected of vuln.affected ?? []) {
-    for (const range of affected.ranges ?? []) {
-      let intro: string | undefined;
-      let fixed: string | undefined;
-      for (const event of range.events ?? []) {
-        if (event.introduced) intro = event.introduced;
-        if (event.fixed)      fixed = event.fixed;
-      }
-      if (intro && fixed)   parts.push(`>=${intro} <${fixed}`);
-      else if (intro)       parts.push(`>=${intro}`);
-      else if (fixed)       parts.push(`<${fixed}`);
-    }
-    // Direct version list
-    if (affected.versions?.length) {
-      parts.push(affected.versions.slice(0, 5).join(', ') + (affected.versions.length > 5 ? '...' : ''));
-    }
-  }
-  return parts.join('; ') || 'all versions';
-}
-
-async function fetchFromOSV(pkg: string, version?: string): Promise<OsvResponse | null> {
-  const body: Record<string, unknown> = {
-    package: { name: pkg, ecosystem: 'npm' },
-  };
-  if (version) body['version'] = version;
-
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 8_000);
-
-  try {
-    const res = await fetch(OSV_API, {
-      method:  'POST',
-      headers: { 'content-type': 'application/json' },
-      body:    JSON.stringify(body),
-      signal:  controller.signal,
-    });
-    if (!res.ok) return null;
-    return await res.json() as OsvResponse;
-  } catch {
-    return null; // network error — caller falls back to cache
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-// ── Public API ────────────────────────────────────────────────────────────────
-
-/**
- * Audits a single package for known CVEs using the OSV database.
- * Results are cached locally for 24h.
- *
- * @param pkg      Package name (e.g. 'lodash' or '@angular/core')
- * @param version  Specific version to check (e.g. '4.17.20'). If omitted, checks all versions.
- */
-export async function auditPackage(pkg: string, version?: string): Promise<AuditResult> {
-  const cached = await readCache(pkg);
-  const now    = Date.now();
-
-  // Fresh cache hit
-  if (cached && now < cached.expiresAt) {
-    return { ...cached.result, cached: true, stale: false };
-  }
-
-  // Try to fetch from OSV
-  const osvData = await fetchFromOSV(pkg, version);
-
-  if (!osvData) {
-    // Offline or API error — use stale cache if available
-    if (cached) {
-      return { ...cached.result, cached: true, stale: true };
-    }
-    // No cache at all
-    return {
-      package: pkg, version: version ?? '*',
-      status: 'unknown', vulns: [],
-      cached: false, stale: false,
-      checkedAt: now,
-    };
-  }
-
-  // Parse OSV response
-  const vulns: Vulnerability[] = (osvData.vulns ?? []).map((v) => {
-    const { severity, cvss } = parseSeverity(v);
-    return {
-      id:               v.id,
-      summary:          v.summary ?? 'No summary available',
-      severity,
-      cvss,
-      aliases:          v.aliases ?? [],
-      affectedVersions: parseAffectedVersions(v),
-      fixedIn:          parseFixedVersion(v),
-      references:       (v.references ?? []).map((r) => r.url),
-      published:        v.published,
-    };
-  });
-
-  // Sort by severity
-  const SORDER: Record<VulnSeverity, number> = { critical: 0, high: 1, medium: 2, low: 3, unknown: 4 };
-  vulns.sort((a, b) => SORDER[a.severity] - SORDER[b.severity]);
-
-  const result: AuditResult = {
-    package:   pkg,
-    version:   version ?? '*',
-    status:    vulns.length > 0 ? 'vulnerable' : 'safe',
-    vulns,
-    cached:    false,
-    stale:     false,
-    checkedAt: now,
-  };
-
-  await writeCache(pkg, { result, expiresAt: now + CACHE_TTL_MS, version: version ?? '*' });
-  return result;
-}
-
-/**
- * Audits all dependencies in a package.json.
- * Runs queries in parallel (max 6 concurrent) to avoid rate limiting.
- */
-export async function auditDependencies(
-  deps: Record<string, string>,
-): Promise<Map<string, AuditResult>> {
-  const results = new Map<string, AuditResult>();
-  const entries = Object.entries(deps);
-  const BATCH   = 6;
-
-  for (let i = 0; i < entries.length; i += BATCH) {
-    const batch = entries.slice(i, i + BATCH);
-    const settled = await Promise.allSettled(
-      batch.map(async ([name, versionRange]) => {
-        // Strip semver range prefix for OSV query
-        const version = versionRange.replace(/^[\^~>=<]/, '').split(' ')[0];
-        const result  = await auditPackage(name, version);
-        return [name, result] as [string, AuditResult];
-      }),
-    );
-    for (const s of settled) {
-      if (s.status === 'fulfilled') {
-        results.set(s.value[0], s.value[1]);
-      }
-    }
-  }
-
-  return results;
-}
-
-/** Returns only vulnerable packages, sorted by severity. */
-export function filterVulnerable(results: Map<string, AuditResult>): AuditResult[] {
-  const SORDER: Record<VulnSeverity, number> = { critical: 0, high: 1, medium: 2, low: 3, unknown: 4 };
-  return [...results.values()]
-    .filter((r) => r.status === 'vulnerable')
-    .sort((a, b) => {
-      const as = a.vulns[0]?.severity ?? 'unknown';
-      const bs = b.vulns[0]?.severity ?? 'unknown';
-      return SORDER[as] - SORDER[bs];
-    });
-}
-
-/** Invalidates the local cache for a specific package (forces re-fetch). */
-export async function invalidateCache(pkg: string): Promise<void> {
-  const { unlink } = await import('node:fs/promises');
-  try {
-    await unlink(join(CACHE_DIR, `${cacheKey(pkg)}.json`));
-  } catch { /* file may not exist */ }
-}
-
-/** Clears the entire OSV cache (all packages). */
-export async function clearCache(): Promise<void> {
-  const { rm } = await import('node:fs/promises');
-  try {
-    await rm(CACHE_DIR, { recursive: true, force: true });
-  } catch { /* ignore */ }
-}

package/src/override.ts

@@ -1,168 +0,0 @@
-/**
- * Nexus Security Override Policy — "Ghost Wall" exceptions.
- *
- * Sometimes a library is vulnerable but:
- *  - The patch isn't yet on a stable release
- *  - You only use the affected function in a build-time context (never in production)
- *  - Your organization has an accepted risk decision documented elsewhere
- *
- * Overrides are explicit, time-limited exceptions that:
- *  1. Require a documented reason
- *  2. Expire automatically — the build fails again after the date
- *  3. Are logged in every audit report
- *  4. Do NOT suppress warnings (only prevent build failure)
- *
- * Usage in nexus.config.ts:
- *
- * ```ts
- * import { defineNexusConfig } from '@nexus_js/core';
- *
- * export default defineNexusConfig({
- *   security: {
- *     hardened: true,
- *     allowVulnerable: {
- *       'pdfkit': {
- *         cve: 'CVE-2024-29415',
- *         reason: 'Used in build-time PDF generation only. Not in the client bundle. ' +
- *                 'Patched version releases 2026-05-15 according to maintainer.',
- *         expires: '2026-06-01',
- *       },
- *     },
- *   },
- * });
- * ```
- *
- * After `expires`, the build fails again, forcing re-evaluation.
- * If the patch is available, update the dependency. If not, extend the override with a new reason.
- */
-
-export interface VulnerabilityOverride {
-  /** CVE ID or OSV ID being overridden */
-  cve:     string;
-  /** REQUIRED: human-readable business justification */
-  reason:  string;
-  /**
-   * ISO date string (YYYY-MM-DD). After this date, the override expires
-   * and the build will fail again. Maximum: 180 days from today.
-   */
-  expires: string;
-}
-
-export type AllowVulnerableConfig = Record<string, VulnerabilityOverride>;
-
-export interface OverrideValidation {
-  valid:     boolean;
-  expired:   boolean;
-  daysLeft:  number;
-  message:   string;
-}
-
-/**
- * Validates an override at build time.
- * Returns { valid: false } if expired or malformed.
- */
-export function validateOverride(
-  pkg:      string,
-  override: VulnerabilityOverride,
-): OverrideValidation {
-  const expiry = new Date(override.expires);
-
-  if (isNaN(expiry.getTime())) {
-    return {
-      valid:    false,
-      expired:  false,
-      daysLeft: 0,
-      message:  `[Nexus Security] Override for "${pkg}" has an invalid expiry date: "${override.expires}". Use YYYY-MM-DD format.`,
-    };
-  }
-
-  const now      = new Date();
-  const daysLeft = Math.ceil((expiry.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
-  const expired  = daysLeft <= 0;
-
-  if (expired) {
-    return {
-      valid:    false,
-      expired:  true,
-      daysLeft: 0,
-      message:
-        `[Nexus Security] ⛔ Override for "${pkg}" (${override.cve}) EXPIRED on ${override.expires}.\n` +
-        `  Original reason: "${override.reason}"\n` +
-        `  The vulnerability must now be addressed. Options:\n` +
-        `    1. Update "${pkg}" to a patched version\n` +
-        `    2. Replace "${pkg}" with a safe alternative\n` +
-        `    3. Extend the override with a new expiry date (requires fresh justification)`,
-    };
-  }
-
-  // Warn when approaching expiry
-  const warningDays = 14;
-  const warning     = daysLeft <= warningDays
-    ? `\n  ⚠️  Override for "${pkg}" expires in ${daysLeft} day${daysLeft === 1 ? '' : 's'} (${override.expires}).`
-    : '';
-
-  return {
-    valid:    true,
-    expired:  false,
-    daysLeft,
-    message: `[Nexus Security] ⚠️  OVERRIDE ACTIVE for "${pkg}" (${override.cve}).${warning}\n  Reason: "${override.reason}"`,
-  };
-}
-
-/**
- * Checks if a package+CVE combination is covered by an active override.
- * Returns null if no override applies (build should fail on critical CVE).
- */
-export function findOverride(
-  pkg:      string,
-  cveId:    string,
-  overrides: AllowVulnerableConfig,
-): OverrideValidation | null {
-  const override = overrides[pkg];
-  if (!override) return null;
-
-  // Check if the CVE matches (direct or alias)
-  const configCve  = override.cve.toUpperCase().trim();
-  const queryCve   = cveId.toUpperCase().trim();
-
-  if (configCve !== queryCve && !queryCve.includes(configCve) && !configCve.includes(queryCve)) {
-    return null;
-  }
-
-  return validateOverride(pkg, override);
-}
-
-/**
- * Formats all active overrides for display in audit output.
- * Groups by status: active, expiring soon, expired.
- */
-export function formatOverrides(
-  overrides: AllowVulnerableConfig,
-): { active: string[]; expiringSoon: string[]; expired: string[] } {
-  const active:       string[] = [];
-  const expiringSoon: string[] = [];
-  const expired:      string[] = [];
-
-  for (const [pkg, override] of Object.entries(overrides)) {
-    const v = validateOverride(pkg, override);
-    if (v.expired) {
-      expired.push(`${pkg} (${override.cve}) — expired ${override.expires}`);
-    } else if (v.daysLeft <= 14) {
-      expiringSoon.push(`${pkg} (${override.cve}) — expires in ${v.daysLeft} days`);
-    } else {
-      active.push(`${pkg} (${override.cve}) — ${v.daysLeft} days left`);
-    }
-  }
-
-  return { active, expiringSoon, expired };
-}
-
-/**
- * Returns the maximum safe override duration (180 days from now).
- * Overrides beyond this are rejected to prevent permanent exceptions.
- */
-export function maxOverrideDate(): string {
-  const d = new Date();
-  d.setDate(d.getDate() + 180);
-  return d.toISOString().split('T')[0] as string;
-}

package/src/scanner.ts

@@ -1,169 +0,0 @@
-/**
- * Nexus Package Scanner — reads package.json and coordinates audits.
- *
- * Combines:
- *  - CVE scanning via OSV (engine.ts)
- *  - Supply chain risk via npm registry (supply-chain.ts)
- *  - Override policy validation (override.ts)
- *
- * Entry point for both the CLI and the Vite plugin.
- */
-
-import { readFile } from 'node:fs/promises';
-import { join }     from 'node:path';
-
-import { auditDependencies, filterVulnerable, type AuditResult, type VulnSeverity } from './engine.js';
-import { auditSupplyChain,  type SupplyChainResult }                                  from './supply-chain.js';
-import { findOverride, validateOverride, formatOverrides, type AllowVulnerableConfig } from './override.js';
-
-export type { AuditResult, VulnSeverity, SupplyChainResult, AllowVulnerableConfig };
-export { filterVulnerable };
-
-// ── Types ─────────────────────────────────────────────────────────────────────
-
-export interface ScanOptions {
-  root:                 string;
-  /** Include devDependencies in the scan (default: false) */
-  includeDev?:          boolean;
-  /** Supply chain guard (default: true) */
-  supplyChain?:         boolean;
-  /** Override exceptions from nexus.config.ts security.allowVulnerable */
-  allowVulnerable?:     AllowVulnerableConfig;
-  /**
-   * If true, critical CVEs that are not overridden will throw (for build-time blocking).
-   * If false, they are reported but don't throw.
-   */
-  failOnCritical?:      boolean;
-  /** Minimum severity to report (default: 'low') */
-  minSeverity?:         VulnSeverity;
-}
-
-export interface ScanResult {
-  scannedPackages:    number;
-  vulnerable:         AuditResult[];
-  supplyChain:        Map<string, SupplyChainResult>;
-  overrideStatus:     ReturnType<typeof formatOverrides>;
-  blockedPackages:    string[];   // packages that would block a build
-  durationMs:         number;
-}
-
-// ── Main scanner ──────────────────────────────────────────────────────────────
-
-/**
- * Full dependency scan: CVE + supply chain + override validation.
- * This is the core function called by both `nexus audit` and the Vite plugin.
- */
-export async function scanProject(opts: ScanOptions): Promise<ScanResult> {
-  const t0 = Date.now();
-
-  // Read package.json
-  const pkgPath = join(opts.root, 'package.json');
-  let pkgJson: { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
-  try {
-    pkgJson = JSON.parse(await readFile(pkgPath, 'utf-8')) as typeof pkgJson;
-  } catch {
-    throw new Error(`[Nexus Audit] Cannot read package.json at ${pkgPath}`);
-  }
-
-  // Collect deps
-  const deps: Record<string, string> = {
-    ...pkgJson.dependencies,
-    ...(opts.includeDev ? pkgJson.devDependencies : {}),
-  };
-
-  const scannedPackages = Object.keys(deps).length;
-
-  // Parallel: CVE scan + supply chain scan
-  const [cveResults, scResults] = await Promise.all([
-    auditDependencies(deps),
-    opts.supplyChain !== false ? auditSupplyChain(deps) : Promise.resolve(new Map<string, SupplyChainResult>()),
-  ]);
-
-  const vulnerable = filterVulnerable(cveResults);
-
-  // Override policy validation
-  const overrides     = opts.allowVulnerable ?? {};
-  const overrideStats = formatOverrides(overrides);
-  const blockedPackages: string[] = [];
-
-  const SORDER: Record<VulnSeverity, number> = { critical: 0, high: 1, medium: 2, low: 3, unknown: 4 };
-  const minSev = opts.minSeverity ?? 'low';
-
-  for (const result of vulnerable) {
-    for (const vuln of result.vulns) {
-      if (SORDER[vuln.severity] > SORDER[minSev]) continue;
-
-      if (vuln.severity !== 'critical' && vuln.severity !== 'high') continue;
-
-      // Check if there's a valid override
-      const overrideResult = findOverride(result.package, vuln.id, overrides)
-        ?? findOverride(result.package, vuln.aliases[0] ?? '', overrides);
-
-      if (overrideResult?.valid) {
-        // Override is active — report but don't block
-        continue;
-      }
-
-      if (!overrideResult || overrideResult.expired) {
-        // No override or expired → block
-        if (!blockedPackages.includes(result.package)) {
-          blockedPackages.push(result.package);
-        }
-      }
-    }
-  }
-
-  const scanResult: ScanResult = {
-    scannedPackages,
-    vulnerable,
-    supplyChain: scResults,
-    overrideStatus: overrideStats,
-    blockedPackages,
-    durationMs: Date.now() - t0,
-  };
-
-  // Throw for build-time blocking
-  if (opts.failOnCritical && blockedPackages.length > 0) {
-    const details = blockedPackages
-      .map((pkg) => {
-        const r = cveResults.get(pkg);
-        const topVuln = r?.vulns[0];
-        return topVuln
-          ? `  "${pkg}" — ${topVuln.id} (${topVuln.severity.toUpperCase()}): ${topVuln.summary}`
-          : `  "${pkg}"`;
-      })
-      .join('\n');
-
-    throw new NexusSecurityError(
-      `[Nexus Security] 🛑 BUILD BLOCKED — ${blockedPackages.length} critical/high CVE${blockedPackages.length > 1 ? 's' : ''} detected:\n\n` +
-      `${details}\n\n` +
-      `Options:\n` +
-      `  1. Run \`nexus fix\` to automatically update to patched versions\n` +
-      `  2. Add a time-limited override in nexus.config.ts (security.allowVulnerable)\n` +
-      `  3. Run \`nexus audit\` for full details and suggested fixes`,
-      blockedPackages,
-      vulnerable,
-    );
-  }
-
-  return scanResult;
-}
-
-// ── Error class ───────────────────────────────────────────────────────────────
-
-export class NexusSecurityError extends Error {
-  constructor(
-    message: string,
-    public readonly blockedPackages: string[],
-    public readonly vulnerable: AuditResult[],
-  ) {
-    super(message);
-    this.name = 'NexusSecurityError';
-  }
-}
-
-// ── Single-package audit (for Vite plugin import hook) ───────────────────────
-
-export { auditPackage } from './engine.js';
-export { checkSupplyChain } from './supply-chain.js';
-export { validateOverride, findOverride } from './override.js';