bun-scan 1.0.1

package/src/processor.ts

@@ -0,0 +1,195 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { OSVVulnerability } from "./schema.js"
+import { isPackageAffected } from "./semver.js"
+import { mapSeverityToLevel } from "./severity.js"
+import { SECURITY } from "./constants.js"
+import { logger } from "./logger.js"
+import { type IgnoreConfig, shouldIgnoreVulnerability } from "./config.js"
+
+/**
+ * Process OSV vulnerabilities into Bun security advisories
+ * Handles vulnerability-to-package matching and advisory generation
+ */
+export class VulnerabilityProcessor {
+  private ignoreConfig: IgnoreConfig
+  private ignoredCount = 0
+
+  constructor(ignoreConfig: IgnoreConfig = {}) {
+    this.ignoreConfig = ignoreConfig
+  }
+
+  /**
+   * Convert OSV vulnerabilities to Bun security advisories
+   * Matches vulnerabilities against input packages and generates appropriate advisories
+   */
+  processVulnerabilities(
+    vulnerabilities: OSVVulnerability[],
+    packages: Bun.Security.Package[],
+  ): Bun.Security.Advisory[] {
+    if (vulnerabilities.length === 0 || packages.length === 0) {
+      return []
+    }
+
+    logger.info(
+      `Processing ${vulnerabilities.length} vulnerabilities against ${packages.length} packages`,
+    )
+
+    const advisories: Bun.Security.Advisory[] = []
+    const processedPairs = new Set<string>() // Track processed vuln+package pairs
+    this.ignoredCount = 0
+
+    for (const vuln of vulnerabilities) {
+      const vulnAdvisories = this.processVulnerability(vuln, packages, processedPairs)
+      advisories.push(...vulnAdvisories)
+    }
+
+    if (this.ignoredCount > 0) {
+      logger.info(`Ignored ${this.ignoredCount} vulnerabilities based on config`)
+    }
+
+    logger.info(`Generated ${advisories.length} security advisories`)
+    return advisories
+  }
+
+  /**
+   * Process a single vulnerability against all packages
+   */
+  private processVulnerability(
+    vuln: OSVVulnerability,
+    packages: Bun.Security.Package[],
+    processedPairs: Set<string>,
+  ): Bun.Security.Advisory[] {
+    const advisories: Bun.Security.Advisory[] = []
+
+    if (!vuln.affected) {
+      logger.debug(`Vulnerability ${vuln.id} has no affected packages`)
+      return advisories
+    }
+
+    for (const affected of vuln.affected) {
+      for (const pkg of packages) {
+        const pairKey = `${vuln.id}:${pkg.name}@${pkg.version}`
+
+        // Avoid duplicate advisories for same vulnerability+package
+        if (processedPairs.has(pairKey)) {
+          continue
+        }
+
+        if (isPackageAffected(pkg, affected)) {
+          // Check if this vulnerability should be ignored
+          const ignoreResult = shouldIgnoreVulnerability(
+            vuln.id,
+            vuln.aliases,
+            pkg.name,
+            this.ignoreConfig,
+          )
+
+          if (ignoreResult.ignored) {
+            logger.debug(`Ignoring ${vuln.id} for ${pkg.name}: ${ignoreResult.reason}`)
+            this.ignoredCount++
+            processedPairs.add(pairKey)
+            continue
+          }
+
+          const advisory = this.createAdvisory(vuln, pkg)
+          advisories.push(advisory)
+          processedPairs.add(pairKey)
+
+          logger.debug(`Created advisory for ${pkg.name}@${pkg.version}`, {
+            vulnerability: vuln.id,
+            level: advisory.level,
+          })
+
+          // Only create one advisory per package per vulnerability
+          break
+        }
+      }
+    }
+
+    return advisories
+  }
+
+  /**
+   * Create a Bun security advisory from an OSV vulnerability and affected package
+   */
+  private createAdvisory(vuln: OSVVulnerability, pkg: Bun.Security.Package): Bun.Security.Advisory {
+    const level = mapSeverityToLevel(vuln)
+    const url = this.getVulnerabilityUrl(vuln)
+    const description = this.getVulnerabilityDescription(vuln)
+
+    return {
+      id: vuln.id,
+      message: vuln.summary || vuln.details || vuln.id,
+      level,
+      package: pkg.name,
+      url,
+      description,
+    }
+  }
+
+  /**
+   * Get the best URL to reference for this vulnerability
+   * Prioritizes official references and known vulnerability databases
+   */
+  private getVulnerabilityUrl(vuln: OSVVulnerability): string | null {
+    if (!vuln.references || vuln.references.length === 0) {
+      return null
+    }
+
+    // Prioritize official advisory URLs
+    const advisoryRef = vuln.references.find(
+      (ref) => ref.type === "ADVISORY" || ref.url.includes("github.com/advisories"),
+    )
+    if (advisoryRef) {
+      return advisoryRef.url
+    }
+
+    // Then CVE URLs
+    const cveRef = vuln.references.find((ref) => {
+      try {
+        const url = new URL(ref.url)
+        return url.hostname === "cve.mitre.org" || url.hostname === "nvd.nist.gov"
+      } catch {
+        return false
+      }
+    })
+    if (cveRef) {
+      return cveRef.url
+    }
+
+    // Fall back to first reference
+    return vuln.references[0]?.url || null
+  }
+
+  /**
+   * Get a descriptive summary of the vulnerability
+   * Uses summary, details, or fallback description
+   */
+  private getVulnerabilityDescription(vuln: OSVVulnerability): string | null {
+    // Prefer concise summary
+    if (vuln.summary?.trim()) {
+      return vuln.summary.trim()
+    }
+
+    // Fall back to details (truncated if too long)
+    if (vuln.details?.trim()) {
+      const details = vuln.details.trim()
+      if (details.length <= SECURITY.MAX_DESCRIPTION_LENGTH) {
+        return details
+      }
+      // Truncate long details to first sentence or max length
+      const firstSentence = details.match(/^[^.!?]*[.!?]/)?.[0]
+      if (firstSentence && firstSentence.length <= SECURITY.MAX_DESCRIPTION_LENGTH) {
+        return firstSentence
+      }
+      return `${details.substring(0, SECURITY.MAX_DESCRIPTION_LENGTH - 3)}...`
+    }
+
+    // No description available
+    return null
+  }
+}

package/src/retry.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import { OSV_API } from "./constants.js"
+import { logger } from "./logger.js"
+
+/**
+ * Retry configuration for network operations
+ */
+export interface RetryConfig {
+  maxAttempts: number
+  delayMs: number
+  shouldRetry?: (error: Error) => boolean
+}
+
+/**
+ * Default retry configuration
+ */
+export const DEFAULT_RETRY_CONFIG: RetryConfig = {
+  maxAttempts: OSV_API.MAX_RETRY_ATTEMPTS + 1,
+  delayMs: OSV_API.RETRY_DELAY_MS,
+  shouldRetry: (error: Error) => {
+    // Don't retry on 4xx client errors (except rate limiting)
+    if (
+      error.message.includes("400") ||
+      error.message.includes("401") ||
+      error.message.includes("403")
+    ) {
+      return false
+    }
+    if (error.message.includes("404")) {
+      return false
+    }
+    // Retry on 5xx server errors and network issues
+    return true
+  },
+}
+
+/**
+ * Execute an operation with retry logic
+ * Provides exponential backoff and configurable retry conditions
+ */
+export async function withRetry<T>(
+  operation: () => Promise<T>,
+  operationName: string,
+  config: RetryConfig = DEFAULT_RETRY_CONFIG,
+): Promise<T> {
+  let lastError: Error = new Error("Unknown error")
+
+  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+    try {
+      const result = await operation()
+
+      if (attempt > 1) {
+        logger.info(`${operationName} succeeded on attempt ${attempt}`)
+      }
+
+      return result
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error))
+
+      const isLastAttempt = attempt === config.maxAttempts
+      const shouldRetry = config.shouldRetry?.(lastError) ?? true
+
+      if (isLastAttempt || !shouldRetry) {
+        logger.error(`${operationName} failed after ${attempt} attempts`, {
+          error: lastError.message,
+          attempts: attempt,
+        })
+        break
+      }
+
+      const delay = config.delayMs * 1.5 ** (attempt - 1) // Exponential backoff
+      logger.warn(`${operationName} attempt ${attempt} failed, retrying in ${delay}ms`, {
+        error: lastError.message,
+        nextDelay: delay,
+      })
+
+      await new Promise((resolve) => setTimeout(resolve, delay))
+    }
+  }
+
+  throw lastError
+}

package/src/schema.ts

@@ -0,0 +1,124 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import { z } from "zod"
+
+// OSV API request schema
+export const OSVQuerySchema = z.object({
+  commit: z.string().optional(),
+  version: z.string().optional(),
+  package: z
+    .object({
+      name: z.string(),
+      ecosystem: z.string(),
+      purl: z.string().optional(),
+    })
+    .optional(),
+  page_token: z.string().optional(),
+})
+
+// OSV affected package schema
+export const OSVAffectedSchema = z.object({
+  package: z.object({
+    name: z.string(),
+    ecosystem: z.string(),
+    purl: z.string().optional(),
+  }),
+  ranges: z
+    .array(
+      z.object({
+        type: z.string(),
+        repo: z.string().optional(),
+        events: z.array(
+          z.object({
+            introduced: z.string().optional(),
+            fixed: z.string().optional(),
+            last_affected: z.string().optional(),
+          }),
+        ),
+      }),
+    )
+    .optional(),
+  versions: z.array(z.string()).optional(),
+  ecosystem_specific: z.record(z.string(), z.any()).optional(),
+  database_specific: z.record(z.string(), z.any()).optional(),
+})
+
+// OSV vulnerability schema
+export const OSVVulnerabilitySchema = z.object({
+  id: z.string(),
+  summary: z.string().optional(),
+  details: z.string().optional(),
+  modified: z.string().optional(),
+  published: z.string().optional(),
+  withdrawn: z.string().optional(),
+  aliases: z.array(z.string()).optional(),
+  related: z.array(z.string()).optional(),
+  schema_version: z.string().optional(),
+  affected: z.array(OSVAffectedSchema).optional(),
+  references: z
+    .array(
+      z.object({
+        type: z.string().optional(),
+        url: z.string(),
+      }),
+    )
+    .optional(),
+  database_specific: z.record(z.string(), z.any()).optional(),
+  severity: z
+    .array(
+      z.object({
+        type: z.string(),
+        score: z.string(),
+      }),
+    )
+    .optional(),
+  ecosystem_specific: z.record(z.string(), z.any()).optional(),
+  credits: z
+    .array(
+      z.object({
+        name: z.string(),
+        contact: z.array(z.string()).optional(),
+        type: z.string().optional(),
+      }),
+    )
+    .optional(),
+})
+
+// OSV API response schema
+export const OSVResponseSchema = z.object({
+  vulns: z.array(OSVVulnerabilitySchema).optional(),
+  next_page_token: z.string().optional(),
+})
+
+// OSV batch query schemas
+export const OSVBatchQuerySchema = z.object({
+  queries: z.array(OSVQuerySchema),
+})
+
+export const OSVBatchResponseSchema = z.object({
+  results: z.array(
+    z.object({
+      vulns: z
+        .array(
+          z.object({
+            id: z.string(),
+            modified: z.string(),
+          }),
+        )
+        .optional(),
+      next_page_token: z.string().optional(),
+    }),
+  ),
+})
+
+// Exported types
+export type OSVQuery = z.infer<typeof OSVQuerySchema>
+export type OSVAffected = z.infer<typeof OSVAffectedSchema>
+export type OSVVulnerability = z.infer<typeof OSVVulnerabilitySchema>
+export type OSVResponse = z.infer<typeof OSVResponseSchema>
+export type OSVBatchQuery = z.infer<typeof OSVBatchQuerySchema>
+export type OSVBatchResponse = z.infer<typeof OSVBatchResponseSchema>
+export type OSVSeverity = NonNullable<OSVVulnerability["severity"]>[0]

package/src/semver.ts

@@ -0,0 +1,109 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { OSVAffected } from "./schema.js"
+import { logger } from "./logger.js"
+
+/**
+ * Check if a package version is affected by an OSV vulnerability
+ * Handles complex OSV range formats including introduced/fixed/last_affected events
+ */
+export function isPackageAffected(pkg: Bun.Security.Package, affected: OSVAffected): boolean {
+  // Package name must match
+  if (affected.package.name !== pkg.name) {
+    return false
+  }
+
+  // Check explicit versions list first (fastest path)
+  if (affected.versions?.includes(pkg.version)) {
+    logger.debug(`Package ${pkg.name}@${pkg.version} found in explicit versions list`)
+    return true
+  }
+
+  // Check version ranges
+  if (affected.ranges) {
+    for (const range of affected.ranges) {
+      if (isVersionInRange(pkg.version, range)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+/**
+ * Check if a version falls within an OSV range
+ * Supports SEMVER and other range types
+ */
+function isVersionInRange(version: string, range: NonNullable<OSVAffected["ranges"]>[0]): boolean {
+  if (!range.events || range.events.length === 0) {
+    return false
+  }
+
+  if (range.type === "SEMVER") {
+    return isVersionInSemverRange(version, range)
+  }
+
+  // For non-SEMVER ranges (GIT, ECOSYSTEM), we can't reliably compare
+  logger.debug(`Unsupported range type: ${range.type}`, { range })
+  return false
+}
+
+/**
+ * Check if version satisfies SEMVER range events
+ * Handles OSV's introduced/fixed/last_affected event model
+ */
+function isVersionInSemverRange(
+  version: string,
+  range: {
+    events: Array<{
+      introduced?: string
+      fixed?: string
+      last_affected?: string
+    }>
+  },
+): boolean {
+  try {
+    // Build semver range string from OSV events
+    const rangeExpressions: string[] = []
+
+    for (const event of range.events) {
+      if (event.introduced) {
+        if (event.introduced === "0") {
+          rangeExpressions.push("*")
+        } else {
+          rangeExpressions.push(`>=${event.introduced}`)
+        }
+      }
+
+      if (event.fixed) {
+        rangeExpressions.push(`<${event.fixed}`)
+      }
+
+      if (event.last_affected) {
+        rangeExpressions.push(`<=${event.last_affected}`)
+      }
+    }
+
+    if (rangeExpressions.length === 0) {
+      return false
+    }
+
+    // Combine range expressions with AND logic
+    const combinedRange = rangeExpressions.join(" ")
+
+    logger.debug(`Checking ${version} against range: ${combinedRange}`)
+
+    return Bun.semver.satisfies(version, combinedRange)
+  } catch (error) {
+    logger.warn(`Failed to parse semver range`, {
+      version,
+      range: range.events,
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return false
+  }
+}

package/src/severity.ts

@@ -0,0 +1,103 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { OSVVulnerability } from "./schema.js"
+import type { FatalSeverity } from "./types.js"
+import { SECURITY } from "./constants.js"
+import { logger } from "./logger.js"
+
+/**
+ * Map OSV vulnerability data to Bun security advisory level
+ * Uses multiple data sources: database_specific.severity, CVSS scores, etc.
+ */
+export function mapSeverityToLevel(vuln: OSVVulnerability): "fatal" | "warn" {
+  // Check database_specific.severity first (most authoritative)
+  const dbSeverity = vuln.database_specific?.severity
+  if (dbSeverity && isFatalSeverity(dbSeverity)) {
+    logger.debug(`Vulnerability ${vuln.id} marked fatal due to database severity: ${dbSeverity}`)
+    return "fatal"
+  }
+
+  // Check CVSS scores if available
+  if (vuln.severity) {
+    const cvssScore = extractHighestCVSSScore(vuln.severity)
+    if (cvssScore !== null && cvssScore >= SECURITY.CVSS_FATAL_THRESHOLD) {
+      logger.debug(`Vulnerability ${vuln.id} marked fatal due to CVSS score: ${cvssScore}`)
+      return "fatal"
+    }
+  }
+
+  // Default to warning level for all other cases
+  logger.debug(`Vulnerability ${vuln.id} marked as warning (default)`)
+  return "warn"
+}
+
+/**
+ * Check if a severity string represents a fatal level
+ */
+function isFatalSeverity(severity: unknown): severity is FatalSeverity {
+  return (
+    typeof severity === "string" && SECURITY.FATAL_SEVERITIES.includes(severity as FatalSeverity)
+  )
+}
+
+/**
+ * Extract the highest CVSS score from severity array
+ * Supports CVSS v2, v3.0, and v3.1 formats
+ */
+function extractHighestCVSSScore(severities: OSVVulnerability["severity"]): number | null {
+  if (!Array.isArray(severities)) return null
+
+  let highestScore: number | null = null
+
+  for (const severity of severities) {
+    if (!severity.type.startsWith("CVSS")) continue
+
+    const score = parseCVSSScore(severity.score, severity.type)
+    if (score !== null && (highestScore === null || score > highestScore)) {
+      highestScore = score
+    }
+  }
+
+  return highestScore
+}
+
+/**
+ * Parse CVSS score from various formats
+ * Handles CVSS:3.1/..., numeric scores, and other formats
+ */
+function parseCVSSScore(scoreString: string, type: string): number | null {
+  try {
+    // Handle CVSS vector strings like "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H/10.0"
+    if (scoreString.includes("CVSS:")) {
+      const vectorMatch = scoreString.match(/CVSS:[\d.]+\/.*?(\d+\.\d+|\d+)$/)
+      if (vectorMatch?.[1]) {
+        return parseFloat(vectorMatch[1])
+      }
+
+      // Some CVSS strings have the score embedded differently
+      const scoreMatch = scoreString.match(/(\d+\.\d+|\d+)$/)
+      if (scoreMatch?.[1]) {
+        return parseFloat(scoreMatch[1])
+      }
+    }
+
+    // Handle plain numeric scores
+    const numericScore = parseFloat(scoreString)
+    if (!Number.isNaN(numericScore) && numericScore >= 0 && numericScore <= 10) {
+      return numericScore
+    }
+
+    logger.debug(`Failed to parse CVSS score`, { type, scoreString })
+    return null
+  } catch (error) {
+    logger.warn(`Error parsing CVSS score`, {
+      type,
+      scoreString,
+      error: error instanceof Error ? error.message : String(error),
+    })
+    return null
+  }
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+// Bun Security Scanner API types
+// These will be moved to @types/bun when officially released
+
+// OSV API related types
+export type FatalSeverity = "CRITICAL" | "HIGH"
+
+// Extend global Bun namespace with missing types
+declare global {
+  namespace Bun {
+    // Bun.semver types (missing from current bun-types)
+    namespace semver {
+      function satisfies(version: string, range: string): boolean
+    }
+
+    // Augment Bun.Security.Advisory with missing properties
+    namespace Security {
+      interface Advisory {
+        id: string
+        message: string
+      }
+    }
+  }
+}