Clawsec Scanner

import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { execCommand, safeJsonParse } from "../../lib/utils.mjs";
import { formatReportText } from "../../lib/report.mjs";
import type { HookEvent, HookContext, ScanReport } from "../../lib/types.ts";

const DEFAULT_SCAN_INTERVAL_SECONDS = 86400; // 24 hours
const DEFAULT_SCANNER_TIMEOUT = 300; // 5 minutes
const DEFAULT_MIN_SEVERITY = "medium";
let unsignedModeWarningShown = false;

interface ScannerState {
  last_hook_scan: string | null;
  last_full_scan: string | null;
  known_vulnerabilities: string[];
}

function parsePositiveInteger(value: string | undefined, fallback: number): number {
  const parsed = Number.parseInt(String(value ?? ""), 10);
  if (!Number.isFinite(parsed) || parsed <= 0) {
    return fallback;
  }
  return parsed;
}

function toEventName(event: HookEvent): string {
  const eventType = String(event.type ?? "").trim();
  const action = String(event.action ?? "").trim();
  if (!eventType || !action) return "";
  return `${eventType}:${action}`;
}

function shouldHandleEvent(event: HookEvent): boolean {
  const eventName = toEventName(event);
  return eventName === "agent:bootstrap" || eventName === "command:new";
}

function epochMs(isoTimestamp: string | null): number {
  if (!isoTimestamp) return 0;
  const parsed = Date.parse(isoTimestamp);
  return Number.isNaN(parsed) ? 0 : parsed;
}

function scannedRecently(lastScan: string | null, minIntervalSeconds: number): boolean {
  const sinceMs = Date.now() - epochMs(lastScan);
  return sinceMs >= 0 && sinceMs < minIntervalSeconds * 1000;
}

function configuredPath(
  explicit: string | undefined,
  fallback: string,
  label: string,
): string {
  if (!explicit) return fallback;

  const resolved = path.resolve(explicit);
  try {
    // Basic validation - check if path is a string
    if (typeof resolved === "string" && resolved.length > 0) {
      return resolved;
    }
  } catch (error) {
    console.warn(
      `[clawsec-scanner-hook] invalid ${label} path "${explicit}", using default "${fallback}": ${String(error)}`,
    );
  }

  return fallback;
}

async function loadState(stateFile: string): Promise<ScannerState> {
  try {
    const content = await fs.readFile(stateFile, "utf8");
    const parsed = safeJsonParse(content, { fallback: {}, label: "scanner state" });
    const parsedState =
      parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};

    return {
      last_hook_scan:
        typeof parsedState.last_hook_scan === "string" ? parsedState.last_hook_scan : null,
      last_full_scan:
        typeof parsedState.last_full_scan === "string" ? parsedState.last_full_scan : null,
      known_vulnerabilities: Array.isArray(parsedState.known_vulnerabilities)
        ? parsedState.known_vulnerabilities.filter((v): v is string => typeof v === "string")
        : [],
    };
  } catch {
    // State file doesn't exist yet - return empty state
    return {
      last_hook_scan: null,
      last_full_scan: null,
      known_vulnerabilities: [],
    };
  }
}

async function persistState(stateFile: string, state: ScannerState): Promise<void> {
  try {
    const dir = path.dirname(stateFile);
    await fs.mkdir(dir, { recursive: true });
    await fs.writeFile(stateFile, JSON.stringify(state, null, 2), "utf8");
  } catch (error) {
    console.warn(`[clawsec-scanner-hook] failed to persist state: ${String(error)}`);
  }
}

async function runScanner(
  targetPath: string,
  options: {
    skipDeps: boolean;
    skipSast: boolean;
    skipDast: boolean;
    skipCve: boolean;
    timeout: number;
  },
): Promise<ScanReport | null> {
  try {
    const scriptPath = path.join(path.dirname(new URL(import.meta.url).pathname), "../../scripts/runner.sh");

    const args = ["--target", targetPath, "--format", "json"];

    if (options.skipDeps) args.push("--skip-deps");
    if (options.skipSast) args.push("--skip-sast");
    if (options.skipDast) args.push("--skip-dast");
    if (options.skipCve) args.push("--skip-cve");

    const { stdout, stderr } = await execCommand("bash", [scriptPath, ...args]);

    if (stderr && !stdout) {
      console.warn(`[clawsec-scanner-hook] scanner warning: ${stderr}`);
    }

    const report = safeJsonParse(stdout, { fallback: null, label: "scanner report" });

    if (!report || typeof report !== "object") {
      console.warn("[clawsec-scanner-hook] scanner produced invalid report");
      return null;
    }

    return report as ScanReport;
  } catch (error) {
    console.warn(`[clawsec-scanner-hook] scanner execution failed: ${String(error)}`);
    return null;
  }
}

function shouldReportSeverity(severity: string, minSeverity: string): boolean {
  const severityOrder = ["info", "low", "medium", "high", "critical"];
  const minIndex = severityOrder.indexOf(minSeverity.toLowerCase());
  const vulnIndex = severityOrder.indexOf(severity.toLowerCase());

  if (minIndex === -1 || vulnIndex === -1) return true;

  return vulnIndex >= minIndex;
}

function deduplicateVulnerabilities(
  report: ScanReport,
  knownVulnIds: string[],
): ScanReport {
  const knownSet = new Set(knownVulnIds);
  const newVulnerabilities = report.vulnerabilities.filter(
    (vuln) => !knownSet.has(vuln.id),
  );

  // Recalculate summary for new vulnerabilities
  const summary = {
    critical: 0,
    high: 0,
    medium: 0,
    low: 0,
    info: 0,
  };

  for (const vuln of newVulnerabilities) {
    const severity = vuln.severity;
    if (severity in summary) {
      summary[severity]++;
    }
  }

  return {
    ...report,
    vulnerabilities: newVulnerabilities,
    summary,
  };
}

function buildAlertMessage(report: ScanReport, format: string): string {
  if (format === "json") {
    return JSON.stringify(report, null, 2);
  }

  return formatReportText(report);
}

const handler = async (event: HookEvent, _context: HookContext): Promise<void> => {
  // Preserve the legacy DAST guard so older scanner harnesses cannot recurse.
  if (process.env.CLAWSEC_DAST_HARNESS === "1" || _context?.dastMode === true) {
    return;
  }

  if (!shouldHandleEvent(event)) return;

  const installRoot = configuredPath(
    process.env.CLAWSEC_INSTALL_ROOT || process.env.INSTALL_ROOT,
    path.join(os.homedir(), ".openclaw", "skills"),
    "CLAWSEC_INSTALL_ROOT",
  );

  const targetPath = configuredPath(
    process.env.CLAWSEC_SCANNER_TARGET,
    installRoot,
    "CLAWSEC_SCANNER_TARGET",
  );

  const stateFile = configuredPath(
    process.env.CLAWSEC_SCANNER_STATE_FILE,
    path.join(os.homedir(), ".openclaw", "clawsec-scanner-state.json"),
    "CLAWSEC_SCANNER_STATE_FILE",
  );

  const scanIntervalSeconds = parsePositiveInteger(
    process.env.CLAWSEC_SCANNER_INTERVAL,
    DEFAULT_SCAN_INTERVAL_SECONDS,
  );

  const scanTimeout = parsePositiveInteger(
    process.env.CLAWSEC_SCANNER_TIMEOUT,
    DEFAULT_SCANNER_TIMEOUT,
  );

  const minSeverity = process.env.CLAWSEC_SCANNER_MIN_SEVERITY || DEFAULT_MIN_SEVERITY;
  const outputFormat = process.env.CLAWSEC_SCANNER_FORMAT || "text";
  const allowUnsigned = process.env.CLAWSEC_ALLOW_UNSIGNED_FEED === "1";

  const skipDeps = process.env.CLAWSEC_SKIP_DEPENDENCY_SCAN === "1";
  const skipSast = process.env.CLAWSEC_SKIP_SAST === "1";
  const skipDast = process.env.CLAWSEC_SKIP_DAST === "1";
  const skipCve = process.env.CLAWSEC_SKIP_CVE_LOOKUP === "1";

  if (allowUnsigned && !unsignedModeWarningShown) {
    unsignedModeWarningShown = true;
    console.warn(
      "[clawsec-scanner-hook] CLAWSEC_ALLOW_UNSIGNED_FEED=1 is enabled. " +
        "This bypass is for development only.",
    );
  }

  const forceScan = toEventName(event) === "command:new";
  const state = await loadState(stateFile);

  if (!forceScan && scannedRecently(state.last_hook_scan, scanIntervalSeconds)) {
    return;
  }

  const report = await runScanner(targetPath, {
    skipDeps,
    skipSast,
    skipDast,
    skipCve,
    timeout: scanTimeout,
  });

  const nowIso = new Date().toISOString();
  state.last_hook_scan = nowIso;
  state.last_full_scan = nowIso;

  if (!report) {
    await persistState(stateFile, state);
    return;
  }

  // Filter by minimum severity
  const filteredVulns = report.vulnerabilities.filter((vuln) =>
    shouldReportSeverity(vuln.severity, minSeverity),
  );

  // Deduplicate against known vulnerabilities
  const dedupedReport = deduplicateVulnerabilities(
    { ...report, vulnerabilities: filteredVulns },
    state.known_vulnerabilities,
  );

  // Update known vulnerabilities list
  const allVulnIds = report.vulnerabilities.map((v) => v.id).filter((id) => id.trim() !== "");
  state.known_vulnerabilities = Array.from(new Set([...state.known_vulnerabilities, ...allVulnIds]));

  await persistState(stateFile, state);

  // Write optional output file
  const outputFile = process.env.CLAWSEC_SCANNER_OUTPUT_FILE;
  if (outputFile) {
    try {
      await fs.writeFile(outputFile, JSON.stringify(report, null, 2), "utf8");
    } catch (error) {
      console.warn(`[clawsec-scanner-hook] failed to write output file: ${String(error)}`);
    }
  }

  // Post findings to conversation if any new vulnerabilities
  if (dedupedReport.vulnerabilities.length > 0) {
    const alertMessage = buildAlertMessage(dedupedReport, outputFormat);

    event.messages?.push({
      role: "system",
      content: `🔍 ClawSec Scanner detected ${dedupedReport.vulnerabilities.length} new vulnerabilities:\n\n${alertMessage}`,
    });
  }
};

export default handler;

import { generateUuid, getTimestamp } from "./utils.mjs";

/**
 * @typedef {import('./types.ts').Vulnerability} Vulnerability
 * @typedef {import('./types.ts').ScanReport} ScanReport
 * @typedef {import('./types.ts').SeverityLevel} SeverityLevel
 */

/**
 * Generate a unified vulnerability report from scan results.
 *
 * @param {Vulnerability[]} vulnerabilities - Array of detected vulnerabilities
 * @param {string} target - Target path that was scanned
 * @returns {ScanReport}
 */
export function generateReport(vulnerabilities, target = ".") {
  const summary = {
    critical: 0,
    high: 0,
    medium: 0,
    low: 0,
    info: 0,
  };

  // Count vulnerabilities by severity
  for (const vuln of vulnerabilities) {
    const severity = vuln.severity;
    if (severity in summary) {
      summary[severity]++;
    }
  }

  return {
    scan_id: generateUuid(),
    timestamp: getTimestamp(),
    target,
    vulnerabilities,
    summary,
  };
}

/**
 * Format a scan report as JSON string.
 *
 * @param {ScanReport} report - Scan report to format
 * @param {boolean} pretty - Whether to pretty-print JSON
 * @returns {string}
 */
export function formatReportJson(report, pretty = true) {
  return pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
}

/**
 * Format a scan report as human-readable text.
 *
 * @param {ScanReport} report - Scan report to format
 * @returns {string}
 */
export function formatReportText(report) {
  const lines = [];

  // Header
  lines.push("═══════════════════════════════════════════════════════════════");
  lines.push("                  VULNERABILITY SCAN REPORT");
  lines.push("═══════════════════════════════════════════════════════════════");
  lines.push("");
  lines.push(`Scan ID:   ${report.scan_id}`);
  lines.push(`Timestamp: ${report.timestamp}`);
  lines.push(`Target:    ${report.target}`);
  lines.push("");

  // Summary
  lines.push("───────────────────────────────────────────────────────────────");
  lines.push("SUMMARY");
  lines.push("───────────────────────────────────────────────────────────────");
  lines.push("");

  const total = report.vulnerabilities.length;
  const { critical, high, medium, low, info } = report.summary;

  lines.push(`Total Vulnerabilities: ${total}`);
  lines.push("");

  if (critical > 0) {
    lines.push(`  🔴 Critical: ${critical}`);
  }
  if (high > 0) {
    lines.push(`  🟠 High:     ${high}`);
  }
  if (medium > 0) {
    lines.push(`  🟡 Medium:   ${medium}`);
  }
  if (low > 0) {
    lines.push(`  🔵 Low:      ${low}`);
  }
  if (info > 0) {
    lines.push(`  ⚪ Info:     ${info}`);
  }

  if (total === 0) {
    lines.push("  ✓ No vulnerabilities detected");
  }

  lines.push("");

  // Detailed findings
  if (report.vulnerabilities.length > 0) {
    lines.push("───────────────────────────────────────────────────────────────");
    lines.push("DETAILED FINDINGS");
    lines.push("───────────────────────────────────────────────────────────────");
    lines.push("");

    // Group vulnerabilities by severity
    const bySeverity = {
      critical: [],
      high: [],
      medium: [],
      low: [],
      info: [],
    };

    for (const vuln of report.vulnerabilities) {
      bySeverity[vuln.severity].push(vuln);
    }

    // Display in order: critical -> high -> medium -> low -> info
    const severityOrder = ["critical", "high", "medium", "low", "info"];

    for (const severity of severityOrder) {
      const vulns = bySeverity[severity];
      if (vulns.length === 0) continue;

      const severityIcon = getSeverityIcon(severity);
      lines.push(`${severityIcon} ${severity.toUpperCase()}`);
      lines.push("");

      for (const vuln of vulns) {
        lines.push(`  ID:      ${vuln.id}`);
        lines.push(`  Package: ${vuln.package} @ ${vuln.version}`);
        if (vuln.fixed_version) {
          lines.push(`  Fix:     ${vuln.fixed_version}`);
        }
        lines.push(`  Source:  ${vuln.source}`);
        lines.push(`  Title:   ${vuln.title}`);

        // Wrap description at 60 chars
        const descLines = wrapText(vuln.description, 60);
        lines.push("  Description:");
        for (const line of descLines) {
          lines.push(`    ${line}`);
        }

        if (vuln.references.length > 0) {
          lines.push("  References:");
          for (const ref of vuln.references.slice(0, 3)) {
            lines.push(`    - ${ref}`);
          }
          if (vuln.references.length > 3) {
            lines.push(`    ... and ${vuln.references.length - 3} more`);
          }
        }

        lines.push("");
      }
    }
  }

  // Recommendations
  lines.push("───────────────────────────────────────────────────────────────");
  lines.push("RECOMMENDATIONS");
  lines.push("───────────────────────────────────────────────────────────────");
  lines.push("");

  if (critical > 0 || high > 0) {
    lines.push("⚠️  URGENT: Critical or high severity vulnerabilities detected!");
    lines.push("");
    lines.push("Recommended actions:");
    lines.push("  1. Review all critical and high severity findings immediately");
    lines.push("  2. Update vulnerable dependencies to fixed versions");
    lines.push("  3. Run scanner again to verify remediation");
    lines.push("");
  } else if (medium > 0) {
    lines.push("⚠️  Medium severity vulnerabilities detected.");
    lines.push("");
    lines.push("Recommended actions:");
    lines.push("  1. Review findings and assess impact on your use case");
    lines.push("  2. Plan updates during next maintenance window");
    lines.push("");
  } else if (low > 0 || info > 0) {
    lines.push("✓ No critical or high severity vulnerabilities detected.");
    lines.push("");
    lines.push("Recommended actions:");
    lines.push("  1. Review low/info findings for awareness");
    lines.push("  2. Consider updates when convenient");
    lines.push("");
  } else {
    lines.push("✓ No vulnerabilities detected. Your code is clean!");
    lines.push("");
  }

  lines.push("═══════════════════════════════════════════════════════════════");

  return lines.join("\n");
}

/**
 * Get emoji icon for severity level.
 *
 * @param {SeverityLevel} severity - Severity level
 * @returns {string}
 */
function getSeverityIcon(severity) {
  const icons = {
    critical: "🔴",
    high: "🟠",
    medium: "🟡",
    low: "🔵",
    info: "⚪",
  };
  return icons[severity] || "⚪";
}

/**
 * Wrap text to specified width.
 *
 * @param {string} text - Text to wrap
 * @param {number} width - Maximum line width
 * @returns {string[]}
 */
function wrapText(text, width) {
  const words = text.split(/\s+/);
  const lines = [];
  let currentLine = "";

  for (const word of words) {
    if (currentLine.length + word.length + 1 <= width) {
      currentLine += (currentLine ? " " : "") + word;
    } else {
      if (currentLine) {
        lines.push(currentLine);
      }
      currentLine = word;
    }
  }

  if (currentLine) {
    lines.push(currentLine);
  }

  return lines.length > 0 ? lines : [""];
}

export type VulnerabilitySource = 'npm-audit' | 'pip-audit' | 'osv' | 'nvd' | 'github' | 'sast' | 'dast';

export type SeverityLevel = 'critical' | 'high' | 'medium' | 'low' | 'info';

export interface Vulnerability {
  id: string;
  source: VulnerabilitySource;
  severity: SeverityLevel;
  package: string;
  version: string;
  fixed_version?: string;
  title: string;
  description: string;
  references: string[];
  discovered_at: string;
}

export interface ScanReport {
  scan_id: string;
  timestamp: string;
  target: string;
  vulnerabilities: Vulnerability[];
  summary: {
    critical: number;
    high: number;
    medium: number;
    low: number;
    info: number;
  };
}

export type HookEvent = {
  type?: string;
  action?: string;
  messages?: Array<{
    role: string;
    content: string;
  }>;
};

export type HookContext = {
  skillPath?: string;
  agentPlatform?: string;
  [key: string]: unknown;
};

import { spawn } from "node:child_process";

/**
 * @param {unknown} value
 * @returns {value is Record<string, unknown>}
 */
export function isObject(value) {
  return typeof value === "object" && value !== null;
}

/**
 * Execute a command as a subprocess and return its output.
 *
 * NOTE: npm audit exits non-zero when vulnerabilities are found.
 * Check stderr for actual errors vs. normal vulnerability reports.
 *
 * @param {string} cmd - Command to execute
 * @param {string[]} args - Command arguments
 * @param {{env?: Record<string, string>, cwd?: string}} [options] - Execution options
 * @returns {Promise<{code: number, stdout: string, stderr: string}>}
 */
export function execCommand(cmd, args, options = {}) {
  return new Promise((resolve, reject) => {
    const proc = spawn(cmd, args, {
      stdio: ["ignore", "pipe", "pipe"],
      env: { ...process.env, ...options.env },
      cwd: options.cwd,
    });

    let stdout = "";
    let stderr = "";

    proc.stdout.on("data", (d) => {
      stdout += d;
    });
    proc.stderr.on("data", (d) => {
      stderr += d;
    });

    proc.on("close", (code) => {
      // npm audit and other security tools exit non-zero when vulnerabilities found
      // Check stderr for actual errors (ERR! pattern) vs. normal findings
      if (code !== 0 && stderr.includes("ERR!")) {
        reject(new Error(stderr));
      } else {
        resolve({ code, stdout, stderr });
      }
    });

    proc.on("error", (error) => {
      reject(error);
    });
  });
}

/**
 * Safely parse JSON string with error handling.
 *
 * @param {string} jsonString - JSON string to parse
 * @param {{fallback?: unknown, label?: string}} [options] - Parse options
 * @returns {unknown}
 */
export function safeJsonParse(jsonString, { fallback = null, label = "JSON" } = {}) {
  const raw = String(jsonString ?? "").trim();
  if (!raw) return fallback;

  try {
    return JSON.parse(raw);
  } catch (error) {
    if (error instanceof Error) {
      console.warn(`Failed to parse ${label}: ${error.message}`);
    }
    return fallback;
  }
}

/**
 * Normalize severity levels from different security tools to standard levels.
 *
 * @param {string} severity - Severity string from security tool
 * @returns {'critical' | 'high' | 'medium' | 'low' | 'info'}
 */
export function normalizeSeverity(severity) {
  const normalized = String(severity ?? "")
    .trim()
    .toLowerCase();

  if (normalized.includes("critical")) return "critical";
  if (normalized.includes("high")) return "high";
  if (normalized.includes("moderate") || normalized.includes("medium")) return "medium";
  if (normalized.includes("low")) return "low";

  return "info";
}

/**
 * @param {string[]} values
 * @returns {string[]}
 */
export function uniqueStrings(values) {
  return Array.from(new Set(values));
}

/**
 * Generate a simple UUID v4.
 *
 * @returns {string}
 */
export function generateUuid() {
  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
    const r = (Math.random() * 16) | 0;
    const v = c === "x" ? r : (r & 0x3) | 0x8;
    return v.toString(16);
  });
}

/**
 * Get current ISO 8601 timestamp.
 *
 * @returns {string}
 */
export function getTimestamp() {
  return new Date().toISOString();
}

/**
 * Check if a command exists in PATH.
 *
 * @param {string} command - Command name to check
 * @returns {Promise<boolean>}
 */
export async function commandExists(command) {
  try {
    const { code } = await execCommand("which", [command]);
    return code === 0;
  } catch {
    return false;
  }
}

#!/usr/bin/env node

import fs from "node:fs/promises";
import path from "node:path";

function parseArgs(argv) {
  const parsed = {
    handler: "",
    exportName: "default",
    eventB64: "",
    contextB64: "",
  };

  for (let i = 0; i < argv.length; i += 1) {
    const token = argv[i];

    if (token === "--handler") {
      parsed.handler = String(argv[i + 1] ?? "").trim();
      i += 1;
      continue;
    }

    if (token === "--export") {
      parsed.exportName = String(argv[i + 1] ?? "default").trim() || "default";
      i += 1;
      continue;
    }

    if (token === "--event") {
      parsed.eventB64 = String(argv[i + 1] ?? "").trim();
      i += 1;
      continue;
    }

    if (token === "--context") {
      parsed.contextB64 = String(argv[i + 1] ?? "").trim();
      i += 1;
      continue;
    }

    throw new Error(`Unknown argument: ${token}`);
  }

  if (!parsed.handler) {
    throw new Error("Missing required --handler");
  }

  return parsed;
}

async function fileExists(filePath) {
  try {
    await fs.access(filePath);
    return true;
  } catch {
    return false;
  }
}

async function readHookSource(handlerPath) {
  const fullPath = path.resolve(handlerPath);
  const exists = await fileExists(fullPath);
  if (!exists) {
    throw new Error(`Hook handler does not exist: ${fullPath}`);
  }

  const ext = path.extname(fullPath).toLowerCase();
  const allowedExtensions = new Set([".cjs", ".js", ".mjs", ".ts"]);
  if (!allowedExtensions.has(ext)) {
    throw new Error(`Unsupported hook handler extension: ${ext || "(none)"}`);
  }

  const source = await fs.readFile(fullPath, "utf8");
  return { fullPath, ext, source };
}

function detectHandlerExport(source, exportName) {
  if (exportName && exportName !== "default") {
    const escaped = exportName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
    return new RegExp(`export\\s+(?:async\\s+)?function\\s+${escaped}\\b|export\\s*\\{[^}]*\\b${escaped}\\b`, "m").test(source);
  }

  return (
    /\bexport\s+default\b/m.test(source) ||
    /\bexport\s+(?:async\s+)?function\s+handler\b/m.test(source) ||
    /\bmodule\.exports\s*=|\bexports\.handler\s*=/m.test(source)
  );
}

function collectRiskSignals(source) {
  const rules = [
    ["child_process", /\bchild_process\b|\bfrom\s+["']node:child_process["']|\brequire\(["']child_process["']\)/m],
    ["dynamic-import", /\bimport\s*\(/m],
    ["eval", /\beval\s*\(|\bnew\s+Function\s*\(/m],
    ["shell-command", /\b(?:exec|spawn|execFile|fork)\s*\(/m],
    ["environment-access", /\bprocess\.env\b/m],
  ];

  const signals = [];
  for (const [name, pattern] of rules) {
    if (pattern.test(source)) {
      signals.push(name);
    }
  }
  return signals;
}

async function main() {
  const args = parseArgs(process.argv.slice(2));
  const startedAt = Date.now();

  try {
    const inspected = await readHookSource(args.handler);

    const payload = {
      ok: true,
      static_only: true,
      duration_ms: Date.now() - startedAt,
      handler_path: inspected.fullPath,
      handler_extension: inspected.ext,
      source_bytes: Buffer.byteLength(inspected.source, "utf8"),
      source_lines: inspected.source.split(/\r?\n/).length,
      handler_export_declared: detectHandlerExport(inspected.source, args.exportName),
      risk_signals: collectRiskSignals(inspected.source),
    };

    process.stdout.write(JSON.stringify(payload));
  } catch (error) {
    const payload = {
      ok: false,
      static_only: true,
      duration_ms: Date.now() - startedAt,
      error: error instanceof Error ? error.message : String(error),
    };

    process.stdout.write(JSON.stringify(payload));
  }
}

main().catch((error) => {
  process.stderr.write(`${error instanceof Error ? error.stack || error.message : String(error)}\n`);
  process.exit(1);
});

#!/usr/bin/env node

/**
 * DAST (Dynamic Application Security Testing) Runner for ClawSec Scanner.
 *
 * Scope:
 * - Discover OpenClaw hooks from target directories
 * - Execute real hook handlers in an isolated harness process
 * - Validate malicious-input resilience, timeout behavior, output bounds,
 *   and event mutation safety
 */

import fs from "node:fs/promises";
import path from "node:path";
import { spawn } from "node:child_process";
import { fileURLToPath } from "node:url";

import { generateReport, formatReportJson, formatReportText } from "../lib/report.mjs";
import { getTimestamp } from "../lib/utils.mjs";

/**
 * @typedef {import('../lib/types.ts').Vulnerability} Vulnerability
 * @typedef {import('../lib/types.ts').ScanReport} ScanReport
 */

const DEFAULT_TIMEOUT_MS = 30000;
const SKIP_DIR_NAMES = new Set([
  ".git",
  ".github",
  ".idea",
  ".vscode",
  "node_modules",
  "dist",
  "build",
  "coverage",
  ".openclaw",
]);

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const HOOK_EXECUTOR_PATH = path.join(__dirname, "dast_hook_executor.mjs");

/**
 * @typedef {Object} HookDescriptor
 * @property {string} name
 * @property {string} hookDir
 * @property {string} hookFile
 * @property {string} handlerPath
 * @property {string[]} events
 * @property {string} exportName
 */

/**
 * Parse CLI arguments.
 *
 * @param {string[]} argv
 * @returns {{target: string, format: 'json' | 'text', timeout: number}}
 */
function parseArgs(argv) {
  const parsed = {
    target: ".",
    format: "json",
    timeout: DEFAULT_TIMEOUT_MS,
  };

  for (let i = 0; i < argv.length; i += 1) {
    const token = argv[i];

    if (token === "--target") {
      parsed.target = String(argv[i + 1] ?? "").trim();
      i += 1;
      continue;
    }

    if (token === "--format") {
      const value = String(argv[i + 1] ?? "json").trim();
      if (value !== "json" && value !== "text") {
        throw new Error("Invalid --format value. Use 'json' or 'text'.");
      }
      parsed.format = value;
      i += 1;
      continue;
    }

    if (token === "--timeout") {
      const value = Number.parseInt(String(argv[i + 1] ?? ""), 10);
      if (!Number.isFinite(value) || value <= 0) {
        throw new Error("Invalid --timeout value. Must be a positive integer (milliseconds).");
      }
      parsed.timeout = value;
      i += 1;
      continue;
    }

    if (token === "--help" || token === "-h") {
      printUsage();
      process.exit(0);
    }

    throw new Error(`Unknown argument: ${token}`);
  }

  if (!parsed.target) {
    throw new Error("Missing required argument: --target");
  }

  return parsed;
}

function printUsage() {
  process.stderr.write(
    [
      "Usage:",
      "  node scripts/dast_runner.mjs --target <path> [--format json|text] [--timeout ms]",
      "",
      "Examples:",
      "  node scripts/dast_runner.mjs --target ./skills/",
      "  node scripts/dast_runner.mjs --target ./skills/ --format text",
      "  node scripts/dast_runner.mjs --target ./skills/ --timeout 60000",
      "",
      "Flags:",
      "  --target   Target skill/hook directory to test (required)",
      "  --format   Output format: json or text (default: json)",
      `  --timeout  Per-hook invocation timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS})`,
      "",
    ].join("\n"),
  );
}

/**
 * @param {string} filePath
 * @returns {Promise<boolean>}
 */
async function fileExists(filePath) {
  try {
    await fs.access(filePath);
    return true;
  } catch {
    return false;
  }
}

/**
 * @param {string} markdown
 * @returns {string}
 */
function extractFrontmatter(markdown) {
  const match = markdown.match(/^---\n([\s\S]*?)\n---/);
  return match ? match[1] : "";
}

/**
 * @param {string} frontmatter
 * @returns {string[]}
 */
function parseEvents(frontmatter) {
  const defaultEvents = ["command:new"];
  if (!frontmatter) return defaultEvents;

  const jsonStyle = frontmatter.match(/"events"\s*:\s*\[([^\]]*)\]/m);
  const yamlStyle = frontmatter.match(/events\s*:\s*\[([^\]]*)\]/m);
  const raw = jsonStyle?.[1] ?? yamlStyle?.[1];

  if (!raw) return defaultEvents;

  const events = [];
  const quotedRegex = /"([^"]+)"|'([^']+)'/g;

  let quotedMatch = quotedRegex.exec(raw);
  while (quotedMatch) {
    const value = quotedMatch[1] || quotedMatch[2];
    if (value && value.includes(":")) {
      events.push(value.trim());
    }
    quotedMatch = quotedRegex.exec(raw);
  }

  if (events.length === 0) {
    const fallback = raw
      .split(",")
      .map((part) => part.trim())
      .map((part) => part.replace(/^['"]|['"]$/g, ""))
      .filter((part) => part.includes(":"));
    events.push(...fallback);
  }

  return events.length > 0 ? Array.from(new Set(events)) : defaultEvents;
}

/**
 * @param {string} frontmatter
 * @param {string} fallback
 * @returns {string}
 */
function parseHookName(frontmatter, fallback) {
  if (!frontmatter) return fallback;

  const match = frontmatter.match(/^name\s*:\s*(.+)$/m);
  if (!match) return fallback;

  return match[1].trim().replace(/^['"]|['"]$/g, "") || fallback;
}

/**
 * @param {string} frontmatter
 * @returns {string}
 */
function parseExportName(frontmatter) {
  if (!frontmatter) return "default";

  const jsonStyle = frontmatter.match(/"export"\s*:\s*"([^"]+)"/m);
  if (jsonStyle?.[1]) return jsonStyle[1].trim();

  const yamlStyle = frontmatter.match(/^export\s*:\s*(.+)$/m);
  if (yamlStyle?.[1]) {
    const value = yamlStyle[1].trim().replace(/^['"]|['"]$/g, "");
    return value || "default";
  }

  return "default";
}

/**
 * @param {string} hookDir
 * @returns {Promise<string | null>}
 */
async function resolveHandlerPath(hookDir) {
  const candidates = [
    "handler.mjs",
    "handler.js",
    "handler.cjs",
    "handler.ts",
    "index.mjs",
    "index.js",
    "index.cjs",
    "index.ts",
  ];

  for (const candidate of candidates) {
    const fullPath = path.join(hookDir, candidate);
    if (await fileExists(fullPath)) {
      return fullPath;
    }
  }

  return null;
}

/**
 * @param {string} targetPath
 * @returns {Promise<HookDescriptor[]>}
 */
export async function discoverHooks(targetPath) {
  const hooks = [];
  const absoluteTarget = path.resolve(targetPath);

  /**
   * @param {string} dir
   * @returns {Promise<void>}
   */
  async function walk(dir) {
    let entries;
    try {
      entries = await fs.readdir(dir, { withFileTypes: true });
    } catch {
      return;
    }

    for (const entry of entries) {
      const fullPath = path.join(dir, entry.name);

      if (entry.isDirectory()) {
        if (SKIP_DIR_NAMES.has(entry.name)) {
          continue;
        }

        await walk(fullPath);
        continue;
      }

      if (!entry.isFile() || entry.name !== "HOOK.md") {
        continue;
      }

      const hookDir = path.dirname(fullPath);
      const hookMd = await fs.readFile(fullPath, "utf8");
      const frontmatter = extractFrontmatter(hookMd);
      const handlerPath = await resolveHandlerPath(hookDir);

      if (!handlerPath) {
        continue;
      }

      hooks.push({
        name: parseHookName(frontmatter, path.basename(hookDir)),
        hookDir,
        hookFile: fullPath,
        handlerPath,
        events: parseEvents(frontmatter),
        exportName: parseExportName(frontmatter),
      });
    }
  }

  await walk(absoluteTarget);

  return hooks;
}

/**
 * @typedef {Object} HarnessInvocationResult
 * @property {boolean} timedOut
 * @property {number} exitCode
 * @property {string} stderr
 * @property {Record<string, unknown> | null} parsed
 * @property {string | null} parseError
 */

/**
 * @param {HookDescriptor} hook
 * @param {number} timeoutMs
 * @returns {Promise<HarnessInvocationResult>}
 */
async function inspectHookHandler(hook, timeoutMs) {
  const args = [
    HOOK_EXECUTOR_PATH,
    "--handler",
    hook.handlerPath,
    "--export",
    hook.exportName || "default",
  ];

  return new Promise((resolve) => {
    const proc = spawn("node", args, {
      stdio: ["ignore", "pipe", "pipe"],
      env: {
        PATH: process.env.PATH || "",
        CLAWSEC_DAST_STATIC_INSPECTION: "1",
      },
    });

    let stdout = "";
    let stderr = "";
    let timedOut = false;

    const timer = setTimeout(() => {
      timedOut = true;
      proc.kill("SIGKILL");
    }, timeoutMs);

    proc.stdout.on("data", (chunk) => {
      stdout += String(chunk);
    });

    proc.stderr.on("data", (chunk) => {
      stderr += String(chunk);
    });

    proc.on("close", (code) => {
      clearTimeout(timer);

      const raw = stdout.trim();
      if (!raw) {
        resolve({
          timedOut,
          exitCode: code ?? 1,
          stderr,
          parsed: null,
          parseError: raw ? null : "Harness produced no JSON output",
        });
        return;
      }

      try {
        const parsed = JSON.parse(raw);
        resolve({
          timedOut,
          exitCode: code ?? 1,
          stderr,
          parsed,
          parseError: null,
        });
      } catch (error) {
        resolve({
          timedOut,
          exitCode: code ?? 1,
          stderr,
          parsed: null,
          parseError: error instanceof Error ? error.message : String(error),
        });
      }
    });
  });
}

/**
 * @param {unknown} value
 * @returns {value is Record<string, unknown>}
 */
function isObject(value) {
  return typeof value === "object" && value !== null;
}

/**
 * @param {unknown} parsed
 * @returns {{ok: boolean, error: string, staticOnly: boolean, riskSignals: string[], handlerExportDeclared: boolean}}
 */
function normalizeStaticPayload(parsed) {
  if (!isObject(parsed)) {
    return {
      ok: false,
      error: "Harness output is not an object",
      staticOnly: false,
      riskSignals: [],
      handlerExportDeclared: false,
    };
  }

  const ok = parsed.ok === true;
  const error = typeof parsed.error === "string" ? parsed.error : "";
  const staticOnly = parsed.static_only === true;
  const riskSignals = Array.isArray(parsed.risk_signals)
    ? parsed.risk_signals.filter((signal) => typeof signal === "string")
    : [];
  const handlerExportDeclared = parsed.handler_export_declared === true;

  return {
    ok,
    error,
    staticOnly,
    riskSignals,
    handlerExportDeclared,
  };
}

/**
 * @param {string} input
 * @returns {string}
 */
function slug(input) {
  return String(input)
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "")
    .slice(0, 60);
}

/**
 * @param {Vulnerability[]} bucket
 * @param {string} id
 * @param {'critical' | 'high' | 'medium' | 'low' | 'info'} severity
 * @param {HookDescriptor} hook
 * @param {string} eventKey
 * @param {string} title
 * @param {string} description
 */
function pushHookVulnerability(bucket, id, severity, hook, eventKey, title, description) {
  bucket.push({
    id,
    source: "dast",
    severity,
    package: hook.name,
    version: `${eventKey}:${path.basename(hook.handlerPath)}`,
    fixed_version: "",
    title,
    description,
    references: [hook.hookFile],
    discovered_at: getTimestamp(),
  });
}

/**
 * @param {HookDescriptor} hook
 * @param {string} _targetPath
 * @param {number} timeoutMs
 * @returns {Promise<Vulnerability[]>}
 */
async function evaluateHook(hook, _targetPath, timeoutMs) {
  const findings = [];
  const invocationTimeoutMs = Math.max(1000, timeoutMs);
  // Static inspection depends only on the handler source/export, so reuse it for all hook events.
  const inspection = await inspectHookHandler(hook, invocationTimeoutMs);

  for (const eventKey of hook.events) {
    if (inspection.timedOut) {
      pushHookVulnerability(
        findings,
        `DAST-STATIC-TIMEOUT-${slug(`${hook.name}-${eventKey}`)}`,
        "medium",
        hook,
        eventKey,
        "Hook static inspection timed out",
        `Static hook inspection exceeded ${invocationTimeoutMs}ms for event '${eventKey}'. Target code was not executed.`,
      );
      continue;
    }

    if (inspection.parseError) {
      pushHookVulnerability(
        findings,
        `DAST-STATIC-HARNESS-${slug(`${hook.name}-${eventKey}`)}`,
        "medium",
        hook,
        eventKey,
        "Hook static inspection output invalid",
        `Could not parse static inspection output for event '${eventKey}': ${inspection.parseError}. stderr: ${inspection.stderr || "(empty)"}`,
      );
      continue;
    }

    const normalized = normalizeStaticPayload(inspection.parsed);
    if (!normalized.ok || !normalized.staticOnly) {
      const reason = normalized.error || inspection.stderr || "unknown static inspection error";
      pushHookVulnerability(
        findings,
        `DAST-STATIC-COVERAGE-${slug(`${hook.name}-${eventKey}`)}`,
        "info",
        hook,
        eventKey,
        "Hook not executed during DAST static inspection",
        `DAST did not execute hook code for event '${eventKey}'. Static inspection failed with: ${reason}`,
      );
      continue;
    }

    const signalSuffix = normalized.riskSignals.length > 0
      ? ` Static signals observed: ${normalized.riskSignals.join(", ")}.`
      : "";
    const exportSuffix = normalized.handlerExportDeclared
      ? ""
      : " The configured handler export was not obvious from static source inspection.";

    pushHookVulnerability(
      findings,
      `DAST-STATIC-COVERAGE-${slug(`${hook.name}-${eventKey}`)}`,
      "info",
      hook,
      eventKey,
      "Hook inspected statically without executing target code",
      `DAST inspected the hook source for event '${eventKey}' without importing, transpiling, or invoking the handler.${signalSuffix}${exportSuffix}`,
    );
  }

  return findings;
}

/**
 * Execute DAST hook tests.
 *
 * @param {string} targetPath
 * @param {number} timeout
 * @returns {Promise<Vulnerability[]>}
 */
export async function runDastTests(targetPath, timeout) {
  const hooks = await discoverHooks(targetPath);
  if (hooks.length === 0) {
    process.stderr.write(`[dast] No OpenClaw hooks discovered under ${targetPath}; skipping DAST harness execution\n`);
    return [];
  }

  const vulnerabilities = [];

  for (const hook of hooks) {
    const hookFindings = await evaluateHook(hook, targetPath, timeout);
    vulnerabilities.push(...hookFindings);
  }

  return vulnerabilities;
}

/**
 * CLI entry point.
 */
async function main() {
  try {
    const args = parseArgs(process.argv.slice(2));

    const targetExists = await fileExists(args.target);
    if (!targetExists) {
      throw new Error(`Target path does not exist: ${args.target}`);
    }

    const vulnerabilities = await runDastTests(args.target, args.timeout);
    const report = generateReport(vulnerabilities, args.target);

    if (args.format === "text") {
      process.stdout.write(formatReportText(report));
      process.stdout.write("\n");
    } else {
      process.stdout.write(formatReportJson(report));
      process.stdout.write("\n");
    }

    const hasCriticalOrHigh = report.summary.critical > 0 || report.summary.high > 0;
    process.exit(hasCriticalOrHigh ? 1 : 0);
  } catch (error) {
    process.stderr.write("DAST runner failed:\n");
    if (error instanceof Error) {
      process.stderr.write(`${error.message}\n`);
    } else {
      process.stderr.write(`${String(error)}\n`);
    }
    process.exit(1);
  }
}

if (import.meta.url === `file://${process.argv[1]}`) {
  main();
}

import { normalizeSeverity, getTimestamp, uniqueStrings } from '../lib/utils.mjs';

/**
 * Query OSV API for vulnerability data.
 * OSV is the primary CVE source (free, no auth, broad ecosystem support).
 *
 * @param {string} packageName - Package name (e.g., 'lodash')
 * @param {string} ecosystem - Ecosystem identifier (e.g., 'npm', 'PyPI')
 * @param {string} [version] - Optional specific version to check
 * @returns {Promise<import('../lib/types.ts').Vulnerability[]>}
 */
export async function queryOSV(packageName, ecosystem, version = undefined) {
  const url = 'https://api.osv.dev/v1/query';

  const requestBody = {
    package: {
      name: packageName,
      ecosystem: ecosystem,
    },
  };

  if (version) {
    requestBody.version = version;
  }

  try {
    const controller = new globalThis.AbortController();
    const timeout = globalThis.setTimeout(() => controller.abort(), 10000);

    const response = await globalThis.fetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(requestBody),
      signal: controller.signal,
    });

    globalThis.clearTimeout(timeout);

    if (!response.ok) {
      console.warn(`OSV API returned status ${response.status} for ${packageName}`);
      return [];
    }

    const data = await response.json();
    const vulns = data.vulns || [];

    return vulns.map((vuln) => normalizeOSVVulnerability(vuln, packageName, version || '*'));
  } catch (error) {
    if (error instanceof Error) {
      console.warn(`OSV API error for ${packageName}: ${error.message}`);
    }
    return [];
  }
}

/**
 * Query NVD API 2.0 for CVE data.
 * Gated behind CLAWSEC_NVD_API_KEY environment variable.
 * Enforces 6-second rate limiting without API key.
 *
 * @param {string} cveId - CVE identifier (e.g., 'CVE-2023-12345')
 * @returns {Promise<import('../lib/types.ts').Vulnerability | null>}
 */
export async function queryNVD(cveId) {
  const apiKey = process.env.CLAWSEC_NVD_API_KEY;
  const url = `https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=${cveId}`;

  const headers = {};
  if (apiKey) {
    headers['apiKey'] = apiKey;
  }

  try {
    const controller = new globalThis.AbortController();
    const timeout = globalThis.setTimeout(() => controller.abort(), 15000);

    const response = await globalThis.fetch(url, {
      method: 'GET',
      headers,
      signal: controller.signal,
    });

    globalThis.clearTimeout(timeout);

    // Rate limiting: 6-second delay required WITHOUT API key
    if (!apiKey) {
      await new Promise((r) => globalThis.setTimeout(r, 6000));
    }

    if (!response.ok) {
      console.warn(`NVD API returned status ${response.status} for ${cveId}`);
      return null;
    }

    const data = await response.json();

    if (!data.vulnerabilities || data.vulnerabilities.length === 0) {
      return null;
    }

    const cveItem = data.vulnerabilities[0].cve;
    return normalizeNVDVulnerability(cveItem);
  } catch (error) {
    if (error instanceof Error) {
      console.warn(`NVD API error for ${cveId}: ${error.message}`);
    }
    return null;
  }
}

/**
 * Query GitHub Advisory Database (optional - requires OAuth token).
 * Currently a placeholder for future implementation.
 *
 * @param {string} _packageName - Package name
 * @param {string} _ecosystem - Ecosystem (e.g., 'npm', 'pip')
 * @returns {Promise<import('../lib/types.ts').Vulnerability[]>}
 */
export async function queryGitHub(_packageName, _ecosystem) {
  const token = process.env.GITHUB_TOKEN;

  if (!token) {
    console.warn('GitHub Advisory Database query skipped: GITHUB_TOKEN not set');
    return [];
  }

  // TODO: Implement GitHub GraphQL advisory query
  // This requires GraphQL API integration with oauth token
  // Placeholder for future enhancement
  console.warn('GitHub Advisory Database integration not yet implemented');
  return [];
}

/**
 * Normalize OSV vulnerability data to unified schema.
 *
 * @param {any} osvVuln - Raw OSV vulnerability object
 * @param {string} packageName - Package name
 * @param {string} version - Package version
 * @returns {import('../lib/types.ts').Vulnerability}
 */
function normalizeOSVVulnerability(osvVuln, packageName, version) {
  const id = osvVuln.id || 'UNKNOWN';
  const summary = osvVuln.summary || 'No description available';
  const details = osvVuln.details || summary;

  // Extract severity from database_specific or severity array
  let severity = 'info';
  if (osvVuln.severity && Array.isArray(osvVuln.severity) && osvVuln.severity.length > 0) {
    severity = normalizeSeverity(osvVuln.severity[0].type || 'info');
  } else if (osvVuln.database_specific && osvVuln.database_specific.severity) {
    severity = normalizeSeverity(osvVuln.database_specific.severity);
  }

  // Extract references
  const references = [];
  if (Array.isArray(osvVuln.references)) {
    references.push(...osvVuln.references.map((ref) => ref.url).filter(Boolean));
  }

  // Extract fixed version from affected ranges
  let fixedVersion = undefined;
  if (Array.isArray(osvVuln.affected)) {
    for (const affected of osvVuln.affected) {
      if (Array.isArray(affected.ranges)) {
        for (const range of affected.ranges) {
          if (Array.isArray(range.events)) {
            for (const event of range.events) {
              if (event.fixed) {
                fixedVersion = event.fixed;
                break;
              }
            }
          }
        }
      }
    }
  }

  return {
    id,
    source: 'osv',
    severity,
    package: packageName,
    version,
    fixed_version: fixedVersion,
    title: summary,
    description: details,
    references: uniqueStrings(references),
    discovered_at: getTimestamp(),
  };
}

/**
 * Normalize NVD vulnerability data to unified schema.
 *
 * @param {any} nvdCve - Raw NVD CVE object
 * @returns {import('../lib/types.ts').Vulnerability}
 */
function normalizeNVDVulnerability(nvdCve) {
  const id = nvdCve.id || 'UNKNOWN';

  // Extract description
  let description = 'No description available';
  if (nvdCve.descriptions && Array.isArray(nvdCve.descriptions)) {
    const englishDesc = nvdCve.descriptions.find((d) => d.lang === 'en');
    if (englishDesc && englishDesc.value) {
      description = englishDesc.value;
    }
  }

  // Extract severity from CVSS metrics
  let severity = 'info';
  if (nvdCve.metrics) {
    // Try CVSS v3.1 first, then v3.0, then v2.0
    const cvssV31 = nvdCve.metrics.cvssMetricV31?.[0];
    const cvssV30 = nvdCve.metrics.cvssMetricV30?.[0];
    const cvssV2 = nvdCve.metrics.cvssMetricV2?.[0];

    const cvssData = cvssV31?.cvssData || cvssV30?.cvssData || cvssV2?.cvssData;
    if (cvssData && cvssData.baseSeverity) {
      severity = normalizeSeverity(cvssData.baseSeverity);
    }
  }

  // Extract references
  const references = [];
  if (nvdCve.references && Array.isArray(nvdCve.references)) {
    references.push(...nvdCve.references.map((ref) => ref.url).filter(Boolean));
  }

  return {
    id,
    source: 'nvd',
    severity,
    package: 'N/A',
    version: '*',
    fixed_version: undefined,
    title: description.slice(0, 100),
    description,
    references: uniqueStrings(references),
    discovered_at: getTimestamp(),
  };
}

/**
 * Enrich vulnerability data by querying multiple CVE databases.
 * OSV is primary, NVD is fallback for additional details.
 *
 * @param {string} packageName - Package name
 * @param {string} ecosystem - Ecosystem (e.g., 'npm', 'PyPI')
 * @param {string} [version] - Optional version
 * @returns {Promise<import('../lib/types.ts').Vulnerability[]>}
 */
export async function enrichVulnerability(packageName, ecosystem, version = undefined) {
  const results = [];

  // Query OSV first (primary source)
  const osvResults = await queryOSV(packageName, ecosystem, version);
  results.push(...osvResults);

  // Optionally query NVD for each CVE ID found in OSV results
  const nvdApiKey = process.env.CLAWSEC_NVD_API_KEY;
  if (nvdApiKey && results.length > 0) {
    for (const vuln of results) {
      if (vuln.id.startsWith('CVE-')) {
        const nvdData = await queryNVD(vuln.id);
        if (nvdData) {
          // Merge NVD references into OSV vulnerability
          vuln.references = uniqueStrings([...vuln.references, ...nvdData.references]);
        }
      }
    }
  }

  return results;
}

// CLI entry point for testing
if (import.meta.url === `file://${process.argv[1]}`) {
  const args = process.argv.slice(2);
  const packageName = args[0] || 'lodash';
  const ecosystem = args[1] || 'npm';
  const version = args[2];

  console.log(`Querying OSV for ${packageName}@${ecosystem}${version ? ` version ${version}` : ''}...`);

  const results = await queryOSV(packageName, ecosystem, version);
  console.log(JSON.stringify(results, null, 2));
  console.log(`\nFound ${results.length} vulnerabilities`);
}