feat: add purls flag to eol scan (#141)

This flag allows eol scan to directly consume a list of purls to send to
our api.

Users can still generate an sbom or use an existing sbom to get a list
of purls.

This feature allows `scan eol` to be useable by clients who want
to derive a list of purls using a method besides cyclonedx sboms.

This feature also allows `scan eol` to `dog food` the output of
`report purls -s`.

Author: edezekiel

README.md

@@ -122,13 +122,14 @@ Scan a given sbom for EOL data
 
 ```
 USAGE
-  $ hd scan eol [--json] [-f <value>] [-d <value>] [-s] [-a] [-c]
+  $ hd scan eol [--json] [-f <value>] [-p <value>] [-d <value>] [-s] [-a] [-c]
 
 FLAGS
   -a, --all                 Show all components (default is EOL and LTS only)
   -c, --getCustomerSupport  Get Never-Ending Support for End-of-Life components
   -d, --dir=<value>         The directory to scan in order to create a cyclonedx sbom
   -f, --file=<value>        The file path of an existing cyclonedx sbom to scan for EOL
+  -p, --purls=<value>       The file path of a list of purls to scan for EOL
   -s, --save                Save the generated SBOM as nes.sbom.json in the scanned directory
 
 GLOBAL FLAGS
@@ -142,6 +143,8 @@ EXAMPLES
 
   $ hd scan eol --file=path/to/sbom.json
 
+  $ hd scan eol --purls=path/to/purls.json
+
   $ hd scan eol -a --dir=./my-project
 ```
 

src/commands/report/purls.ts

@@ -83,9 +83,7 @@ export default class ReportPurls extends Command {
       }
 
       // Return wrapped object with metadata
-      return {
-        purls,
-      };
+      return { purls };
     } catch (error) {
       this.error(`Failed to generate PURLs: ${getErrorMessage(error)}`);
     }

src/commands/scan/eol.ts

@@ -5,6 +5,7 @@ import type { ScanResult, ScanResultComponent } from '../../api/types/nes.types.
 import type { Sbom } from '../../service/eol/cdx.svc.ts';
 import { getErrorMessage, isErrnoException } from '../../service/error.svc.ts';
 import { extractPurls } from '../../service/purls.svc.ts';
+import { parsePurlsFile } from '../../service/purls.svc.ts';
 import { createStatusDisplay } from '../../ui/eol.ui.ts';
 import { INDICATORS, STATUS_COLORS } from '../../ui/shared.us.ts';
 import ScanSbom from './sbom.ts';
@@ -15,13 +16,18 @@ export default class ScanEol extends Command {
   static override examples = [
     '<%= config.bin %> <%= command.id %> --dir=./my-project',
     '<%= config.bin %> <%= command.id %> --file=path/to/sbom.json',
+    '<%= config.bin %> <%= command.id %> --purls=path/to/purls.json',
     '<%= config.bin %> <%= command.id %> -a --dir=./my-project',
   ];
   static override flags = {
     file: Flags.string({
       char: 'f',
       description: 'The file path of an existing cyclonedx sbom to scan for EOL',
     }),
+    purls: Flags.string({
+      char: 'p',
+      description: 'The file path of a list of purls to scan for EOL',
+    }),
     dir: Flags.string({
       char: 'd',
       description: 'The directory to scan in order to create a cyclonedx sbom',
@@ -50,8 +56,7 @@ export default class ScanEol extends Command {
       this.log(ux.colorize('yellow', 'Never-Ending Support is on the way. Please stay tuned for this feature.'));
     }
 
-    const sbom = await ScanSbom.loadSbom(flags, this.config);
-    const scan = await this.scanSbom(sbom);
+    const scan = await this.getScan(flags, this.config);
 
     ux.action.stop('\nScan completed');
 
@@ -70,6 +75,27 @@ export default class ScanEol extends Command {
     return { components: filteredComponents };
   }
 
+  private async getScan(flags: Record<string, string>, config: Command['config']): Promise<ScanResult> {
+    if (flags.purls) {
+      const purls = this.getPurlsFromFile(flags.purls);
+      return submitScan(purls);
+    }
+
+    const sbom = await ScanSbom.loadSbom(flags, config);
+    const scan = this.scanSbom(sbom);
+
+    return scan;
+  }
+
+  private getPurlsFromFile(filePath: string): string[] {
+    try {
+      const purlsFileString = fs.readFileSync(filePath, 'utf8');
+      return parsePurlsFile(purlsFileString);
+    } catch (error) {
+      this.error(`Failed to read purls file. ${getErrorMessage(error)}`);
+    }
+  }
+
   private async scanSbom(sbom: Sbom): Promise<ScanResult> {
     let scan: ScanResult;
     let purls: string[];

src/service/purls.svc.ts

@@ -31,3 +31,33 @@ export async function extractPurls(sbom: Sbom): Promise<string[]> {
   const { components: comps } = sbom;
   return comps.map((c) => c.purl) ?? [];
 }
+
+/**
+ * Parse a purls file in either JSON or text format, including the format of
+ * nes.purls.json - { purls: [ 'pkg:npm/express@4.18.2', 'pkg:npm/[email protected]' ] }
+ * or a text file with one purl per line.
+ */
+export function parsePurlsFile(purlsFileString: string): string[] {
+  try {
+    const parsed = JSON.parse(purlsFileString);
+
+    if (parsed && Array.isArray(parsed.purls)) {
+      return parsed.purls;
+    }
+
+    if (Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    const lines = purlsFileString
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && line.startsWith('pkg:'));
+
+    if (lines.length > 0) {
+      return lines;
+    }
+  }
+
+  throw new Error('Invalid purls file: must be either JSON with purls array or text file with one purl per line');
+}

test/service/purls.svc.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert';
 import { describe, it } from 'node:test';
-import { formatCsvValue, getPurlOutput } from '../../src/service/purls.svc.ts';
+import { formatCsvValue, getPurlOutput, parsePurlsFile } from '../../src/service/purls.svc.ts';
 
 describe('getPurlOutput', () => {
   describe('json output', () => {
@@ -49,3 +49,73 @@ describe('formatCsvValue', () => {
     assert.strictEqual(formatCsvValue(''), '');
   });
 });
+
+describe('parsePurlsFile', () => {
+  describe('JSON format', () => {
+    it('should parse nes.purls.json format', () => {
+      const input = JSON.stringify({
+        purls: ['pkg:npm/@apollo/[email protected]', 'pkg:npm/[email protected]'],
+      });
+      const result = parsePurlsFile(input);
+      assert.deepStrictEqual(result, ['pkg:npm/@apollo/[email protected]', 'pkg:npm/[email protected]']);
+    });
+
+    it('should parse direct JSON array', () => {
+      const input = JSON.stringify(['pkg:npm/[email protected]', 'pkg:npm/[email protected]']);
+      const result = parsePurlsFile(input);
+      assert.deepStrictEqual(result, ['pkg:npm/[email protected]', 'pkg:npm/[email protected]']);
+    });
+  });
+
+  describe('text format', () => {
+    it('should parse text file with one purl per line', () => {
+      const input = `pkg:npm/[email protected]
+pkg:npm/[email protected]`;
+      const result = parsePurlsFile(input);
+      assert.deepStrictEqual(result, ['pkg:npm/[email protected]', 'pkg:npm/[email protected]']);
+    });
+
+    it('should handle empty lines and whitespace', () => {
+      const input = `
+        pkg:npm/[email protected]
+        
+        pkg:npm/[email protected]
+      `;
+      const result = parsePurlsFile(input);
+      assert.deepStrictEqual(result, ['pkg:npm/[email protected]', 'pkg:npm/[email protected]']);
+    });
+
+    it('should filter out invalid lines', () => {
+      const input = `
+        not-a-purl
+        pkg:npm/[email protected]
+        also-not-a-purl
+        pkg:npm/[email protected]
+      `;
+      const result = parsePurlsFile(input);
+      assert.deepStrictEqual(result, ['pkg:npm/[email protected]', 'pkg:npm/[email protected]']);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw error for invalid JSON', () => {
+      const input = '{ invalid json }';
+      assert.throws(() => parsePurlsFile(input), {
+        message: 'Invalid purls file: must be either JSON with purls array or text file with one purl per line',
+      });
+    });
+
+    it('should throw error for empty file', () => {
+      assert.throws(() => parsePurlsFile(''), {
+        message: 'Invalid purls file: must be either JSON with purls array or text file with one purl per line',
+      });
+    });
+
+    it('should throw error for file with no valid purls', () => {
+      const input = 'not-a-purl\nstill-not-a-purl';
+      assert.throws(() => parsePurlsFile(input), {
+        message: 'Invalid purls file: must be either JSON with purls array or text file with one purl per line',
+      });
+    });
+  });
+});