bun-scan 1.0.1

package/src/client.ts

@@ -0,0 +1,284 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { OSVQuery, OSVVulnerability } from "./schema.js"
+import { OSVResponseSchema, OSVBatchResponseSchema, OSVVulnerabilitySchema } from "./schema.js"
+import { OSV_API, HTTP, PERFORMANCE, getConfig, ENV } from "./constants.js"
+import { withRetry } from "./retry.js"
+import { logger } from "./logger.js"
+
+/**
+ * OSV API Client
+ * Handles all communication with OSV.dev API including batch queries and individual lookups
+ */
+export class OSVClient {
+  private readonly baseUrl: string
+  private readonly timeout: number
+  private readonly useBatch: boolean
+
+  constructor() {
+    this.baseUrl = getConfig(ENV.API_BASE_URL, OSV_API.BASE_URL)
+    this.timeout = getConfig(ENV.TIMEOUT_MS, OSV_API.TIMEOUT_MS)
+    this.useBatch = !getConfig(ENV.DISABLE_BATCH, false)
+  }
+
+  /**
+   * Query vulnerabilities for multiple packages
+   * Uses batch API when possible for better performance
+   */
+  async queryVulnerabilities(packages: Bun.Security.Package[]): Promise<OSVVulnerability[]> {
+    if (packages.length === 0) {
+      return []
+    }
+
+    // Deduplicate packages by name@version
+    const uniquePackages = this.deduplicatePackages(packages)
+    logger.info(`Scanning ${uniquePackages.length} unique packages (${packages.length} total)`)
+
+    // Create OSV queries
+    const queries = uniquePackages.map((pkg) => ({
+      package: {
+        name: pkg.name,
+        ecosystem: OSV_API.DEFAULT_ECOSYSTEM,
+      },
+      version: pkg.version,
+    }))
+
+    if (this.useBatch && queries.length > 1) {
+      return await this.queryWithBatch(queries)
+    } else {
+      return await this.queryIndividually(queries)
+    }
+  }
+
+  /**
+   * Deduplicate packages by name@version to avoid redundant queries
+   */
+  private deduplicatePackages(packages: Bun.Security.Package[]): Bun.Security.Package[] {
+    const packageMap = new Map<string, Bun.Security.Package>()
+
+    for (const pkg of packages) {
+      const key = `${pkg.name}@${pkg.version}`
+      if (!packageMap.has(key)) {
+        packageMap.set(key, pkg)
+      }
+    }
+
+    const uniquePackages = Array.from(packageMap.values())
+
+    if (uniquePackages.length < packages.length) {
+      logger.debug(
+        `Deduplicated ${packages.length} packages to ${uniquePackages.length} unique packages`,
+      )
+    }
+
+    return uniquePackages
+  }
+
+  /**
+   * Use batch API for efficient querying
+   * Follows OSV.dev recommended pattern: batch query → individual details
+   */
+  private async queryWithBatch(queries: OSVQuery[]): Promise<OSVVulnerability[]> {
+    const vulnerabilityIds: string[] = []
+
+    // Process queries in batches
+    for (let i = 0; i < queries.length; i += OSV_API.MAX_BATCH_SIZE) {
+      const batchQueries = queries.slice(i, i + OSV_API.MAX_BATCH_SIZE)
+
+      try {
+        const batchIds = await this.executeBatchQuery(batchQueries)
+        vulnerabilityIds.push(...batchIds)
+      } catch (error) {
+        logger.error(`Batch query failed for ${batchQueries.length} packages`, {
+          error: error instanceof Error ? error.message : String(error),
+          startIndex: i,
+        })
+        // Continue with next batch rather than failing completely
+      }
+    }
+
+    // Fetch detailed vulnerability information
+    return await this.fetchVulnerabilityDetails(vulnerabilityIds)
+  }
+
+  /**
+   * Execute a single batch query
+   */
+  private async executeBatchQuery(queries: OSVQuery[]): Promise<string[]> {
+    const vulnerabilityIds: string[] = []
+
+    const response = await withRetry(async () => {
+      const res = await fetch(`${this.baseUrl}/querybatch`, {
+        method: "POST",
+        headers: {
+          "Content-Type": HTTP.CONTENT_TYPE,
+          "User-Agent": HTTP.USER_AGENT,
+        },
+        body: JSON.stringify({ queries }),
+        signal: AbortSignal.timeout(this.timeout),
+      })
+
+      if (!res.ok) {
+        throw new Error(`OSV API returned ${res.status}: ${res.statusText}`)
+      }
+
+      return res
+    }, `OSV batch query (${queries.length} packages)`)
+
+    const data = await response.json()
+    const parsed = OSVBatchResponseSchema.parse(data)
+
+    // Extract vulnerability IDs from batch response
+    for (const result of parsed.results) {
+      if (result.vulns) {
+        vulnerabilityIds.push(...result.vulns.map((v) => v.id))
+      }
+    }
+
+    const vulnCount = parsed.results.reduce((sum, r) => sum + (r.vulns?.length || 0), 0)
+    logger.info(`Batch query found ${vulnCount} vulnerabilities across ${queries.length} packages`)
+
+    return [...new Set(vulnerabilityIds)] // Deduplicate IDs
+  }
+
+  /**
+   * Query packages individually (fallback method)
+   */
+  private async queryIndividually(queries: OSVQuery[]): Promise<OSVVulnerability[]> {
+    const responses = await Promise.allSettled(
+      queries.map((query) => this.querySinglePackage(query)),
+    )
+
+    const vulnerabilities: OSVVulnerability[] = []
+    let successCount = 0
+
+    for (const response of responses) {
+      if (response.status === "fulfilled") {
+        vulnerabilities.push(...response.value)
+        successCount++
+      }
+    }
+
+    logger.info(`Individual queries completed: ${successCount}/${queries.length} successful`)
+    return vulnerabilities
+  }
+
+  /**
+   * Query a single package with pagination support
+   */
+  private async querySinglePackage(query: OSVQuery): Promise<OSVVulnerability[]> {
+    const allVulns: OSVVulnerability[] = []
+    let currentQuery = { ...query }
+
+    while (true) {
+      try {
+        const response = await withRetry(
+          async () => {
+            const res = await fetch(`${this.baseUrl}/query`, {
+              method: "POST",
+              headers: {
+                "Content-Type": HTTP.CONTENT_TYPE,
+                "User-Agent": HTTP.USER_AGENT,
+              },
+              body: JSON.stringify(currentQuery),
+              signal: AbortSignal.timeout(this.timeout),
+            })
+
+            if (!res.ok) {
+              throw new Error(`HTTP ${res.status}: ${res.statusText}`)
+            }
+
+            return res
+          },
+          `OSV query for ${query.package?.name || "unknown"}@${query.version || "unknown"}`,
+        )
+
+        const data = await response.json()
+        const parsed = OSVResponseSchema.parse(data)
+
+        // Add vulnerabilities from this page
+        if (parsed.vulns) {
+          allVulns.push(...parsed.vulns)
+        }
+
+        // Check for pagination
+        if (parsed.next_page_token) {
+          currentQuery = { ...query, page_token: parsed.next_page_token }
+        } else {
+          break // No more pages
+        }
+      } catch (error) {
+        logger.warn(
+          `Query failed for ${query.package?.name || "unknown"}@${query.version || "unknown"}`,
+          {
+            error: error instanceof Error ? error.message : String(error),
+          },
+        )
+        break // Exit pagination loop on error
+      }
+    }
+
+    return allVulns
+  }
+
+  /**
+   * Fetch detailed vulnerability information by IDs
+   */
+  private async fetchVulnerabilityDetails(ids: string[]): Promise<OSVVulnerability[]> {
+    if (ids.length === 0) return []
+
+    const uniqueIds = [...new Set(ids)] // Deduplicate requests
+    logger.info(`Fetching details for ${uniqueIds.length} vulnerabilities`)
+
+    // Process in smaller chunks to avoid overwhelming the API
+    const chunkSize = PERFORMANCE.MAX_CONCURRENT_DETAILS
+    const vulnerabilities: OSVVulnerability[] = []
+
+    for (let i = 0; i < uniqueIds.length; i += chunkSize) {
+      const chunk = uniqueIds.slice(i, i + chunkSize)
+      const chunkResults = await Promise.allSettled(
+        chunk.map((id) => this.fetchSingleVulnerability(id)),
+      )
+
+      for (const result of chunkResults) {
+        if (result.status === "fulfilled" && result.value) {
+          vulnerabilities.push(result.value)
+        }
+      }
+    }
+
+    logger.info(`Retrieved ${vulnerabilities.length}/${uniqueIds.length} vulnerability details`)
+    return vulnerabilities
+  }
+
+  /**
+   * Fetch a single vulnerability by ID
+   */
+  private async fetchSingleVulnerability(id: string): Promise<OSVVulnerability | null> {
+    try {
+      return await withRetry(async () => {
+        const response = await fetch(`${this.baseUrl}/vulns/${id}`, {
+          headers: {
+            "User-Agent": HTTP.USER_AGENT,
+          },
+          signal: AbortSignal.timeout(this.timeout),
+        })
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+        }
+
+        const data = await response.json()
+        return OSVVulnerabilitySchema.parse(data)
+      }, `Get vulnerability ${id}`)
+    } catch (error) {
+      logger.warn(`Failed to fetch vulnerability ${id}`, {
+        error: error instanceof Error ? error.message : String(error),
+      })
+      return null
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,151 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import { z } from "zod"
+import { logger } from "./logger.js"
+
+/**
+ * Schema for package-specific ignore rules
+ */
+const IgnorePackageRuleSchema = z.object({
+  /** Vulnerability IDs to ignore for this package (CVE-*, GHSA-*) */
+  vulnerabilities: z.array(z.string()).optional(),
+  /** Ignore until this date (ISO 8601 format) - for temporary ignores */
+  until: z.string().optional(),
+  /** Reason for ignoring (for documentation) */
+  reason: z.string().optional(),
+})
+
+/**
+ * Schema for the ignore configuration file
+ */
+export const IgnoreConfigSchema = z.object({
+  /** Vulnerability IDs to ignore globally (CVE-*, GHSA-*) */
+  ignore: z.array(z.string()).optional(),
+  /** Package-specific ignore rules */
+  packages: z.record(z.string(), IgnorePackageRuleSchema).optional(),
+})
+
+export type IgnoreConfig = z.infer<typeof IgnoreConfigSchema>
+export type IgnorePackageRule = z.infer<typeof IgnorePackageRuleSchema>
+
+/**
+ * Default config file names to search for (in order of priority)
+ */
+const CONFIG_FILES = [".bun-scan.json", ".bun-scan.config.json"] as const
+
+/**
+ * Load ignore configuration from the current working directory
+ */
+export async function loadIgnoreConfig(): Promise<IgnoreConfig> {
+  for (const filename of CONFIG_FILES) {
+    const config = await tryLoadConfigFile(filename)
+    if (config) {
+      return config
+    }
+  }
+
+  // No config file found - return empty config
+  return {}
+}
+
+/**
+ * Try to load and parse a config file
+ */
+async function tryLoadConfigFile(filename: string): Promise<IgnoreConfig | null> {
+  try {
+    const file = Bun.file(filename)
+    const exists = await file.exists()
+
+    if (!exists) {
+      return null
+    }
+
+    const content = await file.json()
+    const parsed = IgnoreConfigSchema.parse(content)
+
+    logger.info(`Loaded ignore configuration from ${filename}`)
+    logIgnoreStats(parsed)
+
+    return parsed
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      logger.warn(`Invalid ignore config in ${filename}`, {
+        errors: error.issues.map((e) => `${e.path.join(".")}: ${e.message}`),
+      })
+    } else if (error instanceof SyntaxError) {
+      logger.warn(`Failed to parse ${filename} as JSON`, {
+        error: error.message,
+      })
+    }
+    // For other errors (file not found, etc.), silently continue
+    return null
+  }
+}
+
+/**
+ * Log statistics about the loaded ignore configuration
+ */
+function logIgnoreStats(config: IgnoreConfig): void {
+  const globalIgnores = config.ignore?.length ?? 0
+  const packageRules = Object.keys(config.packages ?? {}).length
+
+  if (globalIgnores > 0 || packageRules > 0) {
+    logger.info(`Ignore rules loaded`, {
+      globalIgnores,
+      packageRules,
+    })
+  }
+}
+
+/**
+ * Check if a vulnerability should be ignored based on the config
+ */
+export function shouldIgnoreVulnerability(
+  vulnId: string,
+  vulnAliases: string[] | undefined,
+  packageName: string | undefined,
+  config: IgnoreConfig,
+): { ignored: boolean; reason?: string } {
+  // Get all IDs to check (primary ID + aliases)
+  const idsToCheck = [vulnId, ...(vulnAliases ?? [])]
+
+  // Check global ignores
+  if (config.ignore) {
+    for (const id of idsToCheck) {
+      if (config.ignore.includes(id)) {
+        return { ignored: true, reason: `globally ignored (${id})` }
+      }
+    }
+  }
+
+  // Check package-specific ignores
+  if (packageName && config.packages?.[packageName]) {
+    const rule = config.packages[packageName]
+
+    // Check if the ignore has expired
+    if (rule.until) {
+      const untilDate = new Date(rule.until)
+      if (untilDate < new Date()) {
+        logger.debug(`Ignore rule for ${packageName} expired on ${rule.until}`)
+        return { ignored: false }
+      }
+    }
+
+    // Check package-specific vulnerability ignores
+    if (rule.vulnerabilities) {
+      for (const id of idsToCheck) {
+        if (rule.vulnerabilities.includes(id)) {
+          const reason = rule.reason
+            ? `package rule: ${rule.reason}`
+            : `ignored for ${packageName} (${id})`
+          return { ignored: true, reason }
+        }
+      }
+    }
+  }
+
+  return { ignored: false }
+}

package/src/constants.ts

@@ -0,0 +1,121 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Centralized configuration constants for OSV Scanner
+ * All magic numbers and configuration values consolidated here
+ */
+
+import type { FatalSeverity } from "./types.js"
+
+/**
+ * OSV API Configuration
+ */
+export const OSV_API = {
+  /** Base URL for OSV API */
+  BASE_URL: "https://api.osv.dev/v1",
+
+  /** Request timeout in milliseconds */
+  TIMEOUT_MS: 30_000,
+
+  /** Maximum packages per batch query */
+  MAX_BATCH_SIZE: 1_000,
+
+  /** Maximum retry attempts for failed requests */
+  MAX_RETRY_ATTEMPTS: 2,
+
+  /** Delay between retry attempts in milliseconds */
+  RETRY_DELAY_MS: 1_000,
+
+  /** Default ecosystem for npm packages */
+  DEFAULT_ECOSYSTEM: "npm",
+} as const
+
+/**
+ * HTTP Configuration
+ */
+export const HTTP = {
+  /** Content type for API requests */
+  CONTENT_TYPE: "application/json",
+
+  /** User agent for requests */
+  USER_AGENT: "bun-osv-scanner/1.0.0",
+} as const
+
+/**
+ * Security Configuration
+ */
+export const SECURITY = {
+  /** CVSS score threshold for fatal advisories */
+  CVSS_FATAL_THRESHOLD: 7.0,
+
+  /** Database severities that map to fatal level */
+  FATAL_SEVERITIES: ["CRITICAL", "HIGH"] as const satisfies readonly FatalSeverity[],
+
+  /** Maximum vulnerabilities to process per package */
+  MAX_VULNERABILITIES_PER_PACKAGE: 100,
+
+  /** Maximum length for vulnerability descriptions */
+  MAX_DESCRIPTION_LENGTH: 200,
+} as const
+
+/**
+ * Performance Configuration
+ */
+export const PERFORMANCE = {
+  /** Enable batch queries for better performance */
+  USE_BATCH_QUERIES: true,
+
+  /** Maximum concurrent vulnerability detail requests */
+  MAX_CONCURRENT_DETAILS: 10,
+
+  /** Maximum response size in bytes (32MB) */
+  MAX_RESPONSE_SIZE: 32 * 1024 * 1024,
+} as const
+
+/**
+ * Environment variable configuration
+ */
+export const ENV = {
+  /** Log level environment variable */
+  LOG_LEVEL: "OSV_LOG_LEVEL",
+
+  /** Custom API base URL override */
+  API_BASE_URL: "OSV_API_BASE_URL",
+
+  /** Custom timeout override */
+  TIMEOUT_MS: "OSV_TIMEOUT_MS",
+
+  /** Disable batch queries */
+  DISABLE_BATCH: "OSV_DISABLE_BATCH",
+} as const
+
+/**
+ * Get configuration value with environment variable override
+ */
+export function getConfig<T>(envVar: string, defaultValue: T, parser?: (value: string) => T): T {
+  const envValue = Bun.env[envVar]
+  if (!envValue) return defaultValue
+
+  if (parser) {
+    try {
+      return parser(envValue)
+    } catch {
+      return defaultValue
+    }
+  }
+
+  // Type-safe parsing for common types
+  if (typeof defaultValue === "number") {
+    const parsed = Number(envValue)
+    return (Number.isNaN(parsed) ? defaultValue : parsed) as T
+  }
+
+  if (typeof defaultValue === "boolean") {
+    return (envValue.toLowerCase() === "true") as T
+  }
+
+  return envValue as T
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+/// <reference types="bun-types" />
+import "./types.js"
+import { OSVClient } from "./client.js"
+import { VulnerabilityProcessor } from "./processor.js"
+import { logger } from "./logger.js"
+import { loadIgnoreConfig } from "./config.js"
+
+/**
+ * Bun Security Scanner for OSV.dev vulnerability detection
+ * Integrates with Google's OSV database to detect vulnerabilities in npm packages
+ */
+export const scanner: Bun.Security.Scanner = {
+  version: "1", // This is the version of Bun security scanner implementation. You should keep this set as '1'
+
+  async scan({ packages }) {
+    try {
+      logger.info(`Starting OSV scan for ${packages.length} packages`)
+
+      // Load ignore configuration
+      const ignoreConfig = await loadIgnoreConfig()
+
+      // Initialize components
+      const client = new OSVClient()
+      const processor = new VulnerabilityProcessor(ignoreConfig)
+
+      // Fetch vulnerabilities from OSV.dev
+      const vulnerabilities = await client.queryVulnerabilities(packages)
+
+      // Process vulnerabilities into security advisories
+      const advisories = processor.processVulnerabilities(vulnerabilities, packages)
+
+      logger.info(
+        `OSV scan completed: ${advisories.length} advisories found for ${packages.length} packages`,
+      )
+
+      return advisories
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      logger.error("OSV scanner encountered an unexpected error", {
+        error: message,
+      })
+
+      // Fail-safe: allow installation to proceed on scanner errors
+      return []
+    }
+  },
+}
+
+// CLI entry point
+if (import.meta.main) {
+  const { runCli } = await import("./cli.js")
+  await runCli()
+}

package/src/logger.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) 2025 maloma7. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Structured logging utilities for OSV Scanner
+ * Provides consistent, configurable logging with proper levels and context
+ */
+
+import { ENV } from "./constants.js"
+
+export type LogLevel = "debug" | "info" | "warn" | "error"
+export type LogContext = Record<string, unknown>
+
+interface Logger {
+  debug(message: string, context?: LogContext): void
+  info(message: string, context?: LogContext): void
+  warn(message: string, context?: LogContext): void
+  error(message: string, context?: LogContext): void
+}
+
+class OSVLogger implements Logger {
+  private readonly levels = { debug: 0, info: 1, warn: 2, error: 3 }
+
+  private parseLogLevel(level?: string): LogLevel | null {
+    if (!level) return null
+    const normalized = level.toLowerCase()
+    return ["debug", "info", "warn", "error"].includes(normalized) ? (normalized as LogLevel) : null
+  }
+
+  private get minLevel(): LogLevel {
+    return this.parseLogLevel(process.env[ENV.LOG_LEVEL]) || "info"
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return this.levels[level] >= this.levels[this.minLevel]
+  }
+
+  private safeStringify(obj: unknown): string {
+    try {
+      return JSON.stringify(obj)
+    } catch {
+      return "[Circular]"
+    }
+  }
+
+  private formatMessage(level: LogLevel, message: string, context?: LogContext): string {
+    const timestamp = new Date().toISOString()
+    const prefix = `[${timestamp}] OSV-${level.toUpperCase()}:`
+    const contextStr = context ? ` ${this.safeStringify(context)}` : ""
+    return `${prefix} ${message}${contextStr}`
+  }
+
+  debug(message: string, context?: LogContext): void {
+    if (this.shouldLog("debug")) {
+      console.debug(this.formatMessage("debug", message, context))
+    }
+  }
+
+  info(message: string, context?: LogContext): void {
+    if (this.shouldLog("info")) {
+      console.info(this.formatMessage("info", message, context))
+    }
+  }
+
+  warn(message: string, context?: LogContext): void {
+    if (this.shouldLog("warn")) {
+      console.warn(this.formatMessage("warn", message, context))
+    }
+  }
+
+  error(message: string, context?: LogContext): void {
+    if (this.shouldLog("error")) {
+      console.error(this.formatMessage("error", message, context))
+    }
+  }
+}
+
+export const logger = new OSVLogger()