Fix JSON output; add ignore unbounded malware option

aegilops · aegilops · commit 125965c81021 · 2025-10-03T12:46:15.000+01:00
diff --git a/README.md b/README.md
@@ -15,6 +15,7 @@ Search collected SBOMs by PURL, cache them for offline analysis, sync malware se
 - Version-aware matching of SBOM packages vs. malware advisories
 - Optional SARIF 2.1.0 output per repository for malware matches with optional Code Scanning upload
 - YAML ignore file support to suppress specific advisory IDs or PURLs globally or scoped to an org / repo
+- Optional suppression of "unbounded" malware advisories that claim all versions are affected (e.g. vulnerable range '*', '>=0')
 - Works with GitHub.com, GitHub Enterprise Server, GitHub Enterprise Managed Users and GitHub Enterprise Cloud with Data Residency (custom base URL)
 - Reason tracing: every search match shows which query matched; every malware match shows which advisory triggered it
 - Interactive REPL for ad‑hoc PURL queries (history, graceful Ctrl+C handling)
@@ -70,6 +71,7 @@ npm run start -- --sync-sboms --enterprise ent --base-url https://github.interna
 | `--malware-cache <dir>` | Advisory cache directory (required with malware operations) |
 | `--malware-cutoff <ISO-date>` | Ignore advisories whose publishedAt AND updatedAt are both before this date/time (e.g. `2025-09-29` or full timestamp) |
 | `--ignore-file <path>` | YAML ignore file (advisories / purls / scoped blocks) to filter malware matches before output |
+| `--ignore-unbounded-malware` | Ignore matches whose advisory vulnerable version range covers all versions (e.g. `*`, `>=0`, `0.0.0`) |
 | `--sarif-dir <dir>` | Write SARIF 2.1.0 files per repository (with malware matches) |
 | `--upload-sarif` | Upload generated SARIF to Code Scanning (requires --match-malware & --sarif-dir and a GitHub token) |
 | `--concurrency <n>` | Parallel SBOM fetches (default 5) |
@@ -178,6 +180,26 @@ Rules precedence:
 
 The first matching rule suppresses the finding; output logs will show how many were ignored. Ignored items are fully removed from SARIF and JSON/CSV outputs.
 
+##### Ignoring "Unbounded" Malware Advisories
+
+Some malware advisories list a vulnerable version range that effectively covers every possible version of a package (examples: `*`, `>=0`, `0`, `0.0.0`, `>=0.0.0`). These can create low‑signal noise when you only want to focus on advisories with actionable version scoping.
+
+Use the flag:
+
+```bash
+--ignore-unbounded-malware
+```
+
+When enabled, any malware match whose `vulnerableVersionRange` normalizes to one of those unbounded patterns is filtered out before JSON / SARIF / CSV output. A summary line (to stderr) reports how many were removed.
+
+Heuristics currently treated as unbounded:
+
+- `*`
+- `>=0`, `>0`
+- `0`, `0.0.0`, `>=0.0.0`
+
+If you need broader or narrower interpretation (e.g., treat `>=0 <999999.0.0` as unbounded) please file an issue or extend the matcher.
+
 #### Advisory Date Cutoff
 
 Use `--malware-cutoff` to exclude older advisories from matching. An advisory will be skipped if **both** its `publishedAt` and `updatedAt` timestamps are strictly earlier than the cutoff.
diff --git a/package-lock.json b/package-lock.json
diff --git a/src/cli.ts b/src/cli.ts
@@ -38,6 +38,7 @@ async function main() {
     .option("output-file", { type: "string", describe: "Write search JSON/CSV output to this file. Required when using --cli with JSON/CSV." })
     .option("csv", { type: "boolean", describe: "Emit results (search + malware matches) as CSV" })
     .option("ignore-file", { type: "string", describe: "Path to YAML ignore file (advisories, purls, scoped ignores)" })
+    .option("ignore-unbounded-malware", { type: "boolean", default: false, describe: "Ignore malware advisories whose vulnerable range covers all versions (e.g. '*', '>=0')" })
     .check(args => {
       const syncing = !!args.syncSboms;
       if (syncing) {
@@ -83,6 +84,10 @@ async function main() {
 
   const offline = !argv.syncSboms;
   const quiet = argv.quiet as boolean;
+  const wantJson = !!argv.json;
+  const wantCsv = !!argv.csv;
+  const hasOutputFile = !!argv.outputFile;
+  const wantCli = !!argv.cli && hasOutputFile; // only allow CLI alongside machine output when writing file
   const collector = new SbomCollector({
     token: token,
     enterprise: argv.enterprise as string | undefined,
@@ -124,6 +129,19 @@ async function main() {
   if (argv["match-malware"]) {
     const { matchMalware, buildSarifPerRepo, writeSarifFiles, uploadSarifPerRepo } = await import("./malwareMatcher.js");
     malwareMatches = matchMalware(mas.getAdvisories(), sboms, { advisoryDateCutoff: argv["malware-cutoff"] as string | undefined });
+    // Optional suppression of unbounded version-range advisories
+    if (argv["ignore-unbounded-malware"] && malwareMatches?.length) {
+      const before = malwareMatches.length;
+      const isUnbounded = (range: string | null) => {
+        if (!range) return false;
+        const r = range.trim();
+        if (r === "*") return true;
+        const compact = r.replace(/\s+/g, "");
+        return /^(>=|>=?) ?0(\.0){0,2}$/i.test(compact); // '>=0', '>0', '0', '0.0.0'
+      };
+      malwareMatches = malwareMatches.filter(m => !isUnbounded(m.vulnerableVersionRange));
+      if (!quiet) process.stderr.write(chalk.yellow(`Filtered ${before - malwareMatches.length} unbounded-range malware match(es)`) + "\n");
+    }
     // Apply ignore file if provided
     if (argv["ignore-file"] && malwareMatches?.length) {
       try {
@@ -145,7 +163,8 @@ async function main() {
     }
     if (!quiet) process.stderr.write(chalk.magenta(`Malware matches found: ${malwareMatches?.length ?? 0}`) + "\n");
     if (malwareMatches) {
-      if (!quiet) {
+      const showMalwareCli = (!wantJson && !wantCsv) || wantCli; // show only in pure CLI or combined mode
+      if (showMalwareCli && !quiet) {
         for (const m of malwareMatches) {
           process.stdout.write(`${m.repo} :: ${m.purl} => ${m.advisoryGhsaId} (${m.vulnerableVersionRange ?? "(no range)"}) {advisory: ${m.reason}} ${m.advisoryPermalink}\n`);
         }
@@ -170,13 +189,12 @@ async function main() {
     process.stderr.write(chalk.blue("All repositories reused from cache (no new SBOM writes).") + "\n");
   }
 
-  const runSearch = (purls: string[]) => {
-    const results = collector.searchByPurlsWithReasons(purls);
-    if (!quiet) process.stderr.write(chalk.magenta(`Search results for ${purls.length} purl(s):`) + "\n");
+  const runSearchCli = (purls: string[], results: Map<string, { purl: string; reason: string }[]>) => {
     if (!results.size) {
-      if (!quiet) process.stdout.write("No matches.\n");
+      process.stdout.write("No matches.\n");
       return;
     }
+    if (!quiet) process.stderr.write(chalk.magenta(`Search results for ${purls.length} purl(s):`) + "\n");
     for (const [repo, entries] of results.entries()) {
       process.stdout.write(chalk.bold(repo) + "\n");
       for (const { purl, reason } of entries) process.stdout.write(`  - ${purl} {query: ${reason}}\n`);
@@ -201,55 +219,41 @@ async function main() {
   }
   const combinedPurlsRaw = [...(argv.purl as string[] ?? []), ...filePurls];
   const combinedPurls = combinedPurlsRaw.map(p => p.startsWith("pkg:") ? p : `pkg:${p}`);
+  let searchMap: Map<string, { purl: string; reason: string }[]> | undefined;
   if (combinedPurls.length) {
-    // We'll also consider CSV export after JSON handling
-    if (argv.json || argv.outputFile) {
-      const map = collector.searchByPurlsWithReasons(combinedPurls);
-      const jsonSearch = Array.from(map.entries()).map(([repo, entries]) => ({ repo, matches: entries }));
-      if (argv.outputFile) {
-        try {
-          const fs = await import("fs");
-          let existing: { search?: unknown; malwareMatches?: import("./malwareMatcher.js").MalwareMatch[] } = {};
-          if (fs.existsSync(argv.outputFile as string)) {
-            try { existing = JSON.parse(fs.readFileSync(argv.outputFile as string, "utf8")); } catch { existing = {}; }
-          }
-          existing.search = jsonSearch;
-          if (malwareMatches) existing.malwareMatches = existing.malwareMatches || malwareMatches; // preserve if already set
-          const payload = JSON.stringify(existing, null, 2) + "\n";
-          fs.writeFileSync(argv.outputFile as string, payload, "utf8");
-          if (!quiet) process.stderr.write(chalk.green(`Wrote search JSON to ${argv.outputFile}`) + "\n");
-        } catch (e) {
-          console.error(chalk.red(`Failed to write output file: ${e instanceof Error ? e.message : String(e)}`));
-          process.exit(1);
+    searchMap = collector.searchByPurlsWithReasons(combinedPurls);
+  }
+  if (wantJson) {
+    const jsonSearch = Array.from((searchMap || new Map()).entries()).map(([repo, entries]) => ({ repo, matches: entries }));
+    if (hasOutputFile) {
+      try {
+        const fs = await import("fs");
+        let existing: { search?: unknown; malwareMatches?: import("./malwareMatcher.js").MalwareMatch[] } = {};
+        if (fs.existsSync(argv.outputFile as string)) {
+          try { existing = JSON.parse(fs.readFileSync(argv.outputFile as string, "utf8")); } catch { existing = {}; }
         }
-      } else {
-        const payloadObj: { search: unknown; malwareMatches?: import("./malwareMatcher.js").MalwareMatch[] } = { search: jsonSearch };
-        if (malwareMatches) payloadObj.malwareMatches = malwareMatches;
-        process.stdout.write(JSON.stringify(payloadObj, null, 2) + "\n");
-      }
-      // If CLI output requested (either implicit because no --json OR explicit --cli with output-file requirement) then show human form
-      if (((!argv.json && !argv.csv) && !argv.outputFile) || (argv.cli && (argv.json || argv.outputFile))) {
-        runSearch(combinedPurls);
-      } else if (argv.cli) { // This branch only occurs when validation prevented missing output-file
-        runSearch(combinedPurls);
+        existing.search = jsonSearch;
+        if (malwareMatches) existing.malwareMatches = existing.malwareMatches || malwareMatches;
+        fs.writeFileSync(argv.outputFile as string, JSON.stringify(existing, null, 2) + "\n", "utf8");
+        if (!quiet) process.stderr.write(chalk.green(`Wrote search JSON to ${argv.outputFile}`) + "\n");
+      } catch (e) {
+        console.error(chalk.red(`Failed to write output file: ${(e as Error).message}`));
+        process.exit(1);
       }
     } else {
-      // Pure CLI
-      runSearch(combinedPurls);
+      const payloadObj: { search: unknown; malwareMatches?: import("./malwareMatcher.js").MalwareMatch[] } = { search: jsonSearch };
+      if (malwareMatches) payloadObj.malwareMatches = malwareMatches;
+      process.stdout.write(JSON.stringify(payloadObj, null, 2) + "\n");
     }
-  }
-
-  // CSV output section (covers search results and malware matches if present)
-  if (argv.csv) {
+    if (wantCli && searchMap) runSearchCli(combinedPurls, searchMap);
+  } else if (wantCsv) {
+    // CSV output section (covers search results and malware matches if present)
     const fs = await import("fs");
     // Collect search data if searches were run; reconstruct from collector if we have combinedPurls
     const searchRows: Array<{ repo: string; purl: string; reason: string }> = [];
-    if (combinedPurls.length) {
-      const map = collector.searchByPurlsWithReasons(combinedPurls);
-      for (const [repo, entries] of map.entries()) {
-        for (const { purl, reason } of entries) {
-          searchRows.push({ repo, purl, reason });
-        }
+    if (combinedPurls.length && searchMap) {
+      for (const [repo, entries] of searchMap.entries()) {
+        for (const { purl, reason } of entries) searchRows.push({ repo, purl, reason });
       }
     }
     const malwareRows: Array<{ repo: string; purl: string; advisory: string; range: string | null; updatedAt: string }> = [];
@@ -291,17 +295,21 @@ async function main() {
       ].join(","));
     }
     const csvPayload = lines.join("\n") + "\n";
-    if (argv.outFile) {
+    if (hasOutputFile) {
       try {
-        fs.writeFileSync(argv.outFile as string, csvPayload, "utf8");
-        if (!quiet) process.stderr.write(chalk.green(`Wrote CSV to ${argv.outFile}`) + "\n");
+        fs.writeFileSync(argv.outputFile as string, csvPayload, "utf8");
+        if (!quiet) process.stderr.write(chalk.green(`Wrote CSV to ${argv.outputFile}`) + "\n");
       } catch (e) {
         console.error(chalk.red(`Failed to write CSV file: ${e instanceof Error ? e.message : String(e)}`));
         process.exit(1);
       }
     } else {
       process.stdout.write(csvPayload);
     }
+    if (wantCli && searchMap) runSearchCli(combinedPurls, searchMap);
+  } else if (combinedPurls.length && searchMap) {
+    // Pure CLI (no json/csv)
+    runSearchCli(combinedPurls, searchMap);
   }
 
   // If malware matches were computed but no search JSON writing happened yet and an output file was requested, persist them now.
@@ -361,7 +369,8 @@ async function main() {
         }
         const list = trimmed.split(/[\s,]+/).filter(Boolean);
         try {
-          runSearch(list);
+          const map = collector.searchByPurlsWithReasons(list.map(p => p.startsWith("pkg:") ? p : `pkg:${p}`));
+          runSearchCli(list, map);
         } catch (e) {
           console.error(chalk.red((e as Error).message));
         }
@@ -379,7 +388,8 @@ async function main() {
           { name: "purl", message: "Enter a PURL (blank to exit)", type: "input" }
         ]);
         if (!ans.purl) break;
-        runSearch([ans.purl]);
+  const map = collector.searchByPurlsWithReasons([ans.purl.startsWith("pkg:") ? ans.purl : `pkg:${ans.purl}`]);
+  runSearchCli([ans.purl], map);
       }
     }
   }
