Merge pull request #220 from OWASP/feature/issue-219-html-report

feat: add --report flag to generate HTML vulnerability dashboard

Author: sonukapoor

.gitignore

@@ -14,4 +14,7 @@ reports/
 
 coverage/
 AGENTS.md
-CLAUDE.md
+CLAUDE.md
+.superpowers/
+docs/superpowers/
+cve-report/

src/cli/args.ts

@@ -51,6 +51,18 @@ export function parseArgs(argv: string[]): { command: CliCommand; options: Parse
     if (arg.startsWith("--min-severity=")) { options.minSeverity = arg.slice("--min-severity=".length); continue; }
     if (arg === "--usage" || arg === "--usage-hints") { options.usage = true; continue; }
     if (arg === "--only-used") { options.onlyUsed = true; options.usage = true; continue; }
+    if (arg === "--report") {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        options.report = next;
+        i++;
+      } else {
+        options.report = true;
+      }
+      continue;
+    }
+    if (arg.startsWith("--report=")) { options.report = arg.slice("--report=".length); continue; }
+    if (arg === "--no-open") { options.noOpen = true; continue; }
     if (arg.startsWith("-")) throw new Error(`Unknown option: ${arg}`);
     if (!projectArg) { projectArg = arg; continue; }
     throw new Error(`Unexpected argument: ${arg}`);

src/cli/help.ts

@@ -35,6 +35,8 @@ export function printHelp(): void {
     "",
     "Scan options:",
     "  --json                    Print JSON output",
+    "  --report [dir]            Generate an HTML report in [dir] (default: ./cve-report)",
+    "  --no-open                 Don't auto-open the report in the browser",
     "  --fix                     Apply validated direct dependency fixes and rescan",
     "  --osv-url <url>           Use a custom OSV-compatible advisory endpoint",
     "  --verbose                 Show detailed output with fix plan, paths, and full table",

src/index.ts

@@ -26,6 +26,7 @@ import {
   serializeFinding,
   sortFindingsForOutput
 } from "./output/formatters.js";
+import { buildReportData, writeHtmlReport } from "./output/html-reporter.js";
 import {
   printSummary,
   printActionSummary,
@@ -118,6 +119,10 @@ if (parsedArgs) {
       throw new Error("--fix cannot be used with --json");
     }
 
+    if (options.report && options.json) {
+      throw new Error("--report cannot be used with --json");
+    }
+
     let advisorySourceLine: string;
     let advisoryDbFreshnessLine: string | null = null;
     let advisoryDbWarning: string | null = null;
@@ -263,6 +268,29 @@ if (parsedArgs) {
       printCompactOutput(scanState.sorted, scanInput);
     }
 
+    if (options.report) {
+      const outputDir = path.resolve(
+        typeof options.report === "string" ? options.report : "./cve-report"
+      );
+      const reportData = buildReportData({
+        projectPath,
+        cliVersion,
+        packageManager: scanInput.source,
+        lockfileSource: scanInput.filePath ? path.basename(scanInput.filePath) : scanInput.source,
+        packageCount: packages.length,
+        findings: scanState.sorted,
+        suggestedFixCommands: scanState.suggestedFixCommands,
+        notes: [...scanInput.notes, ...scanState.coverage],
+        warnings: scanInput.warnings,
+      });
+      const { reportPath } = await writeHtmlReport({
+        outputDir,
+        data: reportData,
+        autoOpen: !options.noOpen,
+      });
+      console.log(`${chalk.gray("Report:")} ${chalk.cyan(reportPath)}`);
+    }
+
     const failLevel = normalizeSeverity(options.failOn);
     const shouldFail = scanState.sorted.some(f => severityOrder[f.severity] >= severityOrder[failLevel]);
     process.exit(shouldFail ? 1 : 0);

src/output/html-reporter.ts

@@ -119,4 +119,6 @@ export type ParsedOptions = {
   output?: string;
   usage?: boolean;
   onlyUsed?: boolean;
+  report?: string | true;
+  noOpen?: boolean;
 };

src/output/logo-base64.ts

@@ -31,6 +31,8 @@ const printFinalStatusMock = jest.fn<any>();
 const printCompactOutputMock = jest.fn<any>();
 const buildSuggestedFixCommandPlanMock = jest.fn<any>();
 const spawnMock = jest.fn<any>();
+const buildReportDataMock = jest.fn<any>();
+const writeHtmlReportMock = jest.fn<any>();
 
 jest.unstable_mockModule("../src/cli/help.js", () => ({
   printBanner: printBannerMock,
@@ -104,6 +106,11 @@ jest.unstable_mockModule("node:child_process", () => ({
   spawn: spawnMock,
 }));
 
+jest.unstable_mockModule("../src/output/html-reporter.js", () => ({
+  buildReportData: buildReportDataMock,
+  writeHtmlReport: writeHtmlReportMock,
+}));
+
 function createScanInput(overrides?: Partial<ScanInput>): ScanInput {
   return {
     mode: "manifest-fallback",
@@ -202,6 +209,8 @@ describe("CLI integration", () => {
       package: finding.pkg.name,
       severity: finding.severity,
     }));
+    buildReportDataMock.mockReturnValue({ cliVersion: "1.8.0", findings: [] });
+    writeHtmlReportMock.mockResolvedValue({ reportPath: "/tmp/cve-report/index.html" });
   });
 
   it("returns a json payload and exits successfully when no findings are present", async () => {
@@ -549,4 +558,81 @@ describe("CLI integration", () => {
     expect(result.exitCode).toBe(1);
     expect(result.stderr.join("\n")).toContain("--fix cannot be used with --json");
   });
+
+  describe("--report flag", () => {
+    it("calls writeHtmlReport and prints the report path", async () => {
+      const packages = [
+        { name: "lodash", version: "4.17.21", ecosystem: "npm", paths: [["project", "lodash"]] },
+      ];
+      loadPackagesMock.mockReturnValue(createScanInput({ packages }));
+      scanPackagesMock.mockResolvedValue([]);
+      parseArgsMock.mockReturnValue({
+        command: "scan",
+        options: {
+          failOn: "critical",
+          batchSize: "100",
+          searchDepth: "4",
+          minSeverity: "medium",
+          report: "./my-report",
+          noOpen: true,
+        },
+        projectArg: ".",
+      });
+
+      const result = await runIndexModule();
+
+      expect(writeHtmlReportMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          outputDir: expect.stringContaining("my-report"),
+          autoOpen: false,
+        })
+      );
+      const output = result.stdout.join("\n");
+      expect(output).toContain("/tmp/cve-report/index.html");
+    });
+
+    it("throws when --report and --json are both set", async () => {
+      parseArgsMock.mockReturnValue({
+        command: "scan",
+        options: {
+          failOn: "critical",
+          batchSize: "100",
+          searchDepth: "4",
+          minSeverity: "medium",
+          report: true,
+          json: true,
+        },
+        projectArg: ".",
+      });
+
+      const result = await runIndexModule();
+
+      expect(result.stderr.join("\n")).toContain("--report cannot be used with --json");
+    });
+
+    it("uses ./cve-report as default output dir when --report is true (boolean)", async () => {
+      const packages = [
+        { name: "lodash", version: "4.17.21", ecosystem: "npm", paths: [["project", "lodash"]] },
+      ];
+      loadPackagesMock.mockReturnValue(createScanInput({ packages }));
+      scanPackagesMock.mockResolvedValue([]);
+      parseArgsMock.mockReturnValue({
+        command: "scan",
+        options: {
+          failOn: "critical",
+          batchSize: "100",
+          searchDepth: "4",
+          minSeverity: "medium",
+          report: true,
+          noOpen: true,
+        },
+        projectArg: ".",
+      });
+
+      await runIndexModule();
+
+      const callArgs = writeHtmlReportMock.mock.calls[0][0];
+      expect(callArgs.outputDir).toContain("cve-report");
+    });
+  });
 });