openclaw/scripts/dependency-vulnerability-gate.mts

#!/usr/bin/env node

// Checks resolved dependencies against npm advisory data and gate policy.
import { readFile } from "node:fs/promises";
import path from "node:path";
import process from "node:process";
import { parseReportCliArgs, writeReportArtifact } from "./lib/report-cli-helpers.mts";
import {
  collectAllResolvedPackagesFromLockfile,
  collectProdResolvedPackagesFromLockfile,
  createBulkAdvisoryPayload,
  fetchBulkAdvisories,
} from "./pre-commit/pnpm-audit-prod.mjs";

const SEVERITY_RANK = {
  info: 0,
  low: 1,
  moderate: 2,
  high: 3,
  critical: 4,
};

type Advisory = Partial<
  Record<"overview" | "severity" | "title" | "url" | "vulnerable_versions", string>
> & { id?: string | number };
type Graph = "all" | "production";
type AdvisoryMap = Record<string, Advisory[]>;
type AdvisoryPayload = Record<string, string[]>;
type AdvisorySets = { allAdvisories: AdvisoryMap; productionAdvisories: AdvisoryMap };

function isSeverity(severity: string): severity is keyof typeof SEVERITY_RANK {
  return severity in SEVERITY_RANK;
}

function normalizeSeverity(severity: unknown) {
  const normalized = typeof severity === "string" ? severity.toLowerCase() : "info";
  return isSeverity(normalized) ? normalized : "info";
}

function isMalwareAdvisory(advisory: Advisory) {
  const fields = [advisory.title, advisory.overview, advisory.url].filter(
    (field) => typeof field === "string",
  );
  return fields.some((field) => /\bmalware\b/iu.test(field));
}

function findingFromAdvisory(packageName: string, advisory: Advisory, graph: Graph) {
  return {
    graph,
    packageName,
    id: advisory.id ?? "unknown",
    severity: normalizeSeverity(advisory.severity),
    title: advisory.title ?? "Untitled advisory",
    url: advisory.url ?? null,
    vulnerableVersions: advisory.vulnerable_versions ?? null,
    malware: isMalwareAdvisory(advisory),
  };
}

type Finding = ReturnType<typeof findingFromAdvisory>;

function chunkEntries<T>(entries: T[], size: number) {
  const chunks: T[][] = [];
  for (let index = 0; index < entries.length; index += size) {
    chunks.push(entries.slice(index, index + size));
  }
  return chunks;
}

async function fetchBulkAdvisoriesForPayload(payload: AdvisoryPayload, fetchImpl: typeof fetch) {
  const advisoryResults: AdvisoryMap = {};
  for (const payloadChunk of chunkEntries(Object.entries(payload), 400)) {
    const chunkPayload = Object.fromEntries(payloadChunk);
    Object.assign(
      advisoryResults,
      await fetchBulkAdvisories({
        payload: chunkPayload,
        fetchImpl,
      }),
    );
  }
  return advisoryResults;
}

function flattenAdvisories(advisoriesByPackage: AdvisoryMap, graphName: Graph) {
  const findings: Finding[] = [];
  for (const [packageName, advisories] of Object.entries(advisoriesByPackage ?? {})) {
    if (!Array.isArray(advisories)) {
      continue;
    }
    for (const advisory of advisories) {
      if (!advisory || typeof advisory !== "object") {
        continue;
      }
      findings.push(findingFromAdvisory(packageName, advisory, graphName));
    }
  }
  return findings;
}

function findingKey(finding: Finding) {
  return [
    finding.packageName,
    String(finding.id),
    finding.severity,
    finding.vulnerableVersions ?? "",
  ].join("\0");
}

function dedupeFindings(findings: Finding[]) {
  const byKey = new Map<string, Finding>();
  for (const finding of findings) {
    const key = findingKey(finding);
    const existing = byKey.get(key);
    if (!existing) {
      byKey.set(key, finding);
      continue;
    }
    if (existing.graph !== "production" && finding.graph === "production") {
      byKey.set(key, finding);
    }
  }
  return [...byKey.values()];
}

function sortFindings(findings: Finding[]) {
  return findings.toSorted((left, right) => {
    const severityDelta =
      (SEVERITY_RANK[right.severity] ?? -1) - (SEVERITY_RANK[left.severity] ?? -1);
    if (severityDelta !== 0) {
      return severityDelta;
    }
    if (left.graph !== right.graph) {
      return left.graph.localeCompare(right.graph);
    }
    if (left.packageName !== right.packageName) {
      return left.packageName.localeCompare(right.packageName);
    }
    return String(left.id).localeCompare(String(right.id));
  });
}

/**
 * Classifies npm advisory findings into report-only findings and hard blockers.
 */
export function classifyVulnerabilityFindings({
  allAdvisories,
  productionAdvisories,
}: AdvisorySets) {
  const allFindings = flattenAdvisories(allAdvisories, "all");
  const productionFindings = flattenAdvisories(productionAdvisories, "production");
  const blockers: Finding[] = [];

  for (const finding of allFindings) {
    if (finding.malware || finding.severity === "critical") {
      blockers.push(finding);
    }
  }
  for (const finding of productionFindings) {
    if (finding.severity === "high" || finding.severity === "critical" || finding.malware) {
      blockers.push(finding);
    }
  }

  return {
    blockers: sortFindings(dedupeFindings(blockers)),
    findings: sortFindings(dedupeFindings([...allFindings, ...productionFindings])),
  };
}

function countPayloadVersions(payload: AdvisoryPayload) {
  return Object.values(payload).reduce((sum, versions) => sum + versions.length, 0);
}

/**
 * Runs the dependency vulnerability gate against pnpm-lock.yaml.
 */
export async function runDependencyVulnerabilityGate({
  rootDir = process.cwd(),
  fetchImpl = fetch,
}: { rootDir?: string; fetchImpl?: typeof fetch } = {}) {
  const lockfileText = await readFile(path.join(rootDir, "pnpm-lock.yaml"), "utf8");
  const allPayload = createBulkAdvisoryPayload(
    collectAllResolvedPackagesFromLockfile(lockfileText),
  );
  const productionPayload = createBulkAdvisoryPayload(
    collectProdResolvedPackagesFromLockfile(lockfileText),
  );

  const [allAdvisories, productionAdvisories] = await Promise.all([
    fetchBulkAdvisoriesForPayload(allPayload, fetchImpl),
    fetchBulkAdvisoriesForPayload(productionPayload, fetchImpl),
  ]);
  const classified = classifyVulnerabilityFindings({ allAdvisories, productionAdvisories });
  return {
    generatedAt: new Date().toISOString(),
    policy: {
      blocks: [
        "known malware advisories anywhere in the installed graph",
        "critical advisories anywhere in the installed graph",
        "high advisories in the production/runtime graph",
      ],
      reports: [
        "moderate and lower advisories",
        "high advisories outside production/runtime graph",
      ],
      vulnerabilityExceptions: false,
    },
    graphs: {
      all: {
        packages: Object.keys(allPayload).length,
        packageVersions: countPayloadVersions(allPayload),
      },
      production: {
        packages: Object.keys(productionPayload).length,
        packageVersions: countPayloadVersions(productionPayload),
      },
    },
    ...classified,
  };
}

/**
 * Renders the dependency vulnerability gate report as Markdown.
 */
export function renderDependencyVulnerabilityGateMarkdownReport(
  report: Awaited<ReturnType<typeof runDependencyVulnerabilityGate>>,
) {
  const lines = [
    "# npm Advisory Vulnerability Gate: Resolved Dependency Graph",
    "",
    `Generated: ${report.generatedAt}`,
    "",
    "## Scope",
    "",
    "This gate checks resolved package versions from pnpm-lock.yaml against npm advisory data. It includes transitive dependencies. It blocks known malware anywhere, critical advisories anywhere, and high advisories in the production/runtime graph.",
    "",
    "## Summary",
    "",
    `- All graph packages: ${report.graphs.all.packages}`,
    `- All graph package versions: ${report.graphs.all.packageVersions}`,
    `- Production graph packages: ${report.graphs.production.packages}`,
    `- Production graph package versions: ${report.graphs.production.packageVersions}`,
    `- Hard blockers: ${report.blockers.length}`,
    `- Total findings: ${report.findings.length}`,
    "",
    "## Policy",
    "",
    ...report.policy.blocks.map((block) => `- Block: ${block}`),
    ...report.policy.reports.map((item) => `- Report: ${item}`),
    `- Vulnerability exceptions: ${report.policy.vulnerabilityExceptions ? "allowed" : "not allowed"}`,
    "",
  ];

  if (report.blockers.length > 0) {
    lines.push("## Hard Blockers", "");
    for (const finding of report.blockers) {
      lines.push(
        `- ${finding.severity.toUpperCase()} ${finding.packageName} (${finding.graph}) ` +
          `id=${finding.id} range=${finding.vulnerableVersions ?? "unknown"} ` +
          `${finding.malware ? "[malware] " : ""}${finding.url ?? ""}`,
      );
      lines.push(`  - ${finding.title}`);
    }
    lines.push("");
  }

  if (report.findings.length > 0) {
    lines.push("## Findings", "");
    for (const finding of report.findings) {
      lines.push(
        `- ${finding.severity.toUpperCase()} ${finding.packageName} (${finding.graph}) ` +
          `id=${finding.id} range=${finding.vulnerableVersions ?? "unknown"} ` +
          `${finding.malware ? "[malware] " : ""}${finding.url ?? ""}`,
      );
      lines.push(`  - ${finding.title}`);
    }
    lines.push("");
  }

  if (report.findings.length === 0) {
    lines.push("No advisories found.", "");
  }

  return `${lines.join("\n")}\n`;
}

export async function main(argv = process.argv.slice(2)) {
  const options = parseReportCliArgs(argv);
  const report = await runDependencyVulnerabilityGate({ rootDir: options.rootDir });
  await writeReportArtifact(options.jsonPath, `${JSON.stringify(report, null, 2)}\n`);
  await writeReportArtifact(
    options.markdownPath,
    renderDependencyVulnerabilityGateMarkdownReport(report),
  );

  if (report.blockers.length === 0) {
    const packageVersions = report.graphs.all.packageVersions;
    process.stdout.write(
      `PASS npm advisory vulnerability gate: checked ${packageVersions} resolved ` +
        `package versions across the lockfile graph; 0 hard blockers, ` +
        `${report.findings.length} total advisories.\n`,
    );
    return 0;
  }

  process.stderr.write(
    `FAIL npm advisory vulnerability gate: ${report.blockers.length} hard blockers in resolved ` +
      `dependency graph; ${report.findings.length} total advisories.\n`,
  );
  for (const blocker of report.blockers.slice(0, 25)) {
    process.stderr.write(
      `- ${blocker.severity.toUpperCase()} ${blocker.packageName} (${blocker.graph}) ` +
        `id=${blocker.id} title=${blocker.title}\n`,
    );
  }
  return 1;
}

if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
  main().then(
    (exitCode) => {
      process.exitCode = exitCode;
    },
    (error: unknown) => {
      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
      process.exitCode = 1;
    },
  );
}