@herodevs/cli 2.0.0-beta.0 → 2.0.0-beta.10

package/README.md

@@ -10,27 +10,68 @@ The HeroDevs CLI
 * [@herodevs/cli](#herodevscli)
 <!-- tocstop -->
 
+### Prerequisites
+
+- Install node v20 or higher: [Download Node](https://nodejs.org/en/download)
+- The HeroDevs CLI expects that you have all required technology installed for the project that you are running the CLI against
+  - For example, if you are running the CLI against a Gradle project, the CLI expects you to have Java installed.
+
+
+### Installation methods
+
+#### Node Package Execute (NPX)
+
+With Node installed, you can run the CLI directly from the npm registry without installing it globally or locally on your system
+
+```sh
+npx @herodevs/cli@beta
+```
+
+#### Global NPM Installation
+
+```sh
+npm install -g @herodevs/cli@beta
+```
+
+#### Binary Installation
+
+HeroDevs CLI is available as a binary installation, without requiring `npm`. To do that, you may either download and run the script manually, or use the following cURL or Wget command:
+
+```sh
+curl -o- https://raw.githubusercontent.com/herodevs/cli/v2.0.0-beta.10/scripts/install.sh | bash
+```
+
+```sh
+wget -qO- https://raw.githubusercontent.com/herodevs/cli/v2.0.0-beta.10/scripts/install.sh | bash
+```
+
 ## TERMS
 
 Use of this CLI is governed by the [HeroDevs End of Life Dataset Terms of Service and Data Policy](https://docs.herodevs.com/legal/end-of-life-dataset-terms).
 
 ## Scanning Behavior
 
-The CLI's scanning commands (`hd scan eol` and `hd scan sbom`) are designed to be non-invasive:
+The CLI is designed to be non-invasive:
+
+* It does **not** install dependencies or modify package manager files (package-lock.json, yarn.lock, etc.)
+* It analyzes the project in its current state
 
-* They do not install dependencies or modify package manager files (package-lock.json, yarn.lock, etc.)
-* They analyze the project in its current state
-* If you need dependencies installed for accurate scanning, please install them manually before running the scan
+## Installing Dependencies Before Use
 
+Some projects and ecosystems require projects to have dependencies installed already, to achieve an accurate scan result. It is **highly** recommended that you install all dependencies of your project to your working directory, before running a scan on your project, to ensure scan accuracy.
+
+### Java Users
+
+Maven and Gradle projects should run an install and build before scanning
 
 ## Usage
 <!-- usage -->
 ```sh-session
-$ npm install -g @herodevs/cli
+$ npm install -g @herodevs/cli@beta
 $ hd COMMAND
 running command...
 $ hd (--version)
-@herodevs/cli/2.0.0-beta.0 linux-x64 node-v22.15.0
+@herodevs/cli/2.0.0-beta.10 darwin-arm64 node-v22.18.0
 $ hd --help [COMMAND]
 USAGE
   $ hd COMMAND
@@ -40,11 +81,9 @@ USAGE
 ## Commands
 <!-- commands -->
 * [`hd help [COMMAND]`](#hd-help-command)
-* [`hd report committers`](#hd-report-committers)
-* [`hd report purls`](#hd-report-purls)
 * [`hd scan eol`](#hd-scan-eol)
-* [`hd scan sbom`](#hd-scan-sbom)
 * [`hd update [CHANNEL]`](#hd-update-channel)
+  * **NOTE:** Only applies to [binary installation method](#binary-installation). NPM users should use [`npm install`](#global-npm-installation) to update to the latest version.
 
 ## `hd help [COMMAND]`
 
@@ -64,170 +103,209 @@ DESCRIPTION
   Display help for hd.
 ```
 
-_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.28/src/commands/help.ts)_
+_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.32/src/commands/help.ts)_
 
-## `hd report committers`
+## `hd scan eol`
 
-Generate report of committers to a git repository
+Scan a given SBOM for EOL data
 
 ```
 USAGE
-  $ hd report committers [--json] [-m <value>] [-c] [-s]
+  $ hd scan eol [--json] [-f <value> | -d <value>] [-s] [--saveSbom] [--version]
 
 FLAGS
-  -c, --csv             Output in CSV format
-  -m, --months=<value>  [default: 12] The number of months of git history to review
-  -s, --save            Save the committers report as eol.committers.<output>
+  -d, --dir=<value>   [default: <current directory>] 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
+  -s, --save          Save the generated report as herodevs.report.json in the scanned directory
+      --saveSbom      Save the generated SBOM as herodevs.sbom.json in the scanned directory
+      --version       Show CLI version.
 
 GLOBAL FLAGS
   --json  Format output as json.
 
 DESCRIPTION
-  Generate report of committers to a git repository
+  Scan a given SBOM for EOL data
 
 EXAMPLES
-  $ hd report committers
+  Default behavior (no command or flags specified)
+
+    $ hd
+
+  Equivalent to
+
+    $ hd scan eol --dir .
 
-  $ hd report committers --csv -s
+  Skip SBOM generation and specify an existing file
 
-  $ hd report committers --json
+    $ hd scan eol --file /path/to/sbom.json
 
-  $ hd report committers --csv
+  Save the report or SBOM to a file
+
+    $ hd scan eol --save --saveSbom
+
+  Output the report in JSON format (for APIs, CI, etc.)
+
+    $ hd scan eol --json
 ```
 
-_See code: [src/commands/report/committers.ts](https://github.com/herodevs/cli/blob/v2.0.0-beta.0/src/commands/report/committers.ts)_
+_See code: [src/commands/scan/eol.ts](https://github.com/herodevs/cli/blob/v2.0.0-beta.10/src/commands/scan/eol.ts)_
 
-## `hd report purls`
+## `hd update [CHANNEL]`
+
+update the hd CLI
 
-Generate a list of purls from a sbom
+* **NOTE:** Only applies to [binary installation method](#binary-installation). NPM users should use [`npm install`](#global-npm-installation) to update to the latest version.
 
 ```
 USAGE
-  $ hd report purls [--json] [-f <value>] [-d <value>] [-s] [-c]
+  $ hd update [CHANNEL] [--force |  | [-a | -v <value> | -i]] [-b ]
 
 FLAGS
-  -c, --csv           Save output in CSV format (only applies when using --save)
-  -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
-  -s, --save          Save the list of purls as eol.purls.<output>
-
-GLOBAL FLAGS
-  --json  Format output as json.
+  -a, --available        See available versions.
+  -b, --verbose          Show more details about the available versions.
+  -i, --interactive      Interactively select version to install. This is ignored if a channel is provided.
+  -v, --version=<value>  Install a specific version.
+      --force            Force a re-download of the requested version.
 
 DESCRIPTION
-  Generate a list of purls from a sbom
+  update the hd CLI
 
 EXAMPLES
-  $ hd report purls --json -s
-
-  $ hd report purls --dir=./my-project
+  Update to the stable channel:
 
-  $ hd report purls --file=path/to/sbom.json
+    $ hd update stable
 
-  $ hd report purls --dir=./my-project --save
+  Update to a specific version:
 
-  $ hd report purls --save --csv
-```
+    $ hd update --version 1.0.0
 
-_See code: [src/commands/report/purls.ts](https://github.com/herodevs/cli/blob/v2.0.0-beta.0/src/commands/report/purls.ts)_
+  Interactively select version:
 
-## `hd scan eol`
+    $ hd update --interactive
 
-Scan a given sbom for EOL data
+  See available versions:
 
+    $ hd update --available
 ```
-USAGE
-  $ hd scan eol [--json] [-f <value>] [-p <value>] [-d <value>] [-s] [-a] [-t]
-
-FLAGS
-  -a, --all            Show all components (default is EOL and SUPPORTED only)
-  -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 report as eol.report.json in the scanned directory
-  -t, --table          Display the results in a table
 
-GLOBAL FLAGS
-  --json  Format output as json.
+_See code: [@oclif/plugin-update](https://github.com/oclif/plugin-update/blob/v4.7.4/src/commands/update.ts)_
+<!-- commandsstop -->
 
-DESCRIPTION
-  Scan a given sbom for EOL data
+## CI/CD Usage
 
-EXAMPLES
-  $ hd scan eol --dir=./my-project
+You can use `@herodevs/cli` in your CI/CD pipelines to automate EOL scanning.
 
-  $ hd scan eol --file=path/to/sbom.json
+### Using the Docker Image (Recommended)
 
-  $ hd scan eol --purls=path/to/purls.json
+We provide a Docker image that's pre-configured to run EOL scans. Based on [`cdxgen`](https://github.com/CycloneDX/cdxgen),
+it contains build tools for most project types and will provide best results when generating an SBOM. Use these templates to generate a report and save it to your CI job artifact for analysis and processing after your scan runs.
 
-  $ hd scan eol -a --dir=./my-project
-```
+#### GitHub Actions
 
-_See code: [src/commands/scan/eol.ts](https://github.com/herodevs/cli/blob/v2.0.0-beta.0/src/commands/scan/eol.ts)_
+```yaml
+## .github/workflows/herodevs-eol-scan.yml
+name: HeroDevs EOL Scan
 
-## `hd scan sbom`
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
 
-Scan a SBOM for purls
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
 
+      - name: Run EOL Scan with Docker
+        uses: docker://ghcr.io/herodevs/eol-scan
+        with:
+          args: "-s"
+      
+      - name: Upload   artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: my-eol-report
+          path: herodevs.report.json
 ```
-USAGE
-  $ hd scan sbom [--json] [-f <value>] [-d <value>] [-s] [-b]
-
-FLAGS
-  -b, --background    Run the scan in the background
-  -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
-  -s, --save          Save the generated SBOM as eol.sbom.json in the scanned directory
-
-GLOBAL FLAGS
-  --json  Format output as json.
 
-DESCRIPTION
-  Scan a SBOM for purls
+#### GitLab CI/CD
+
+```yaml
+eol-scan: 
+  image: 
+    name: "ghcr.io/herodevs/eol-scan"
+    # Entrypoint or base command must be disabled due 
+    # to GitLab's execution mechanism and run manually
+    entrypoint: [""] 
+  script: "npx @herodevs/cli@beta scan eol -s"
+  artifacts:
+    paths:
+      - herodevs.report.json
+```
 
-EXAMPLES
-  $ hd scan sbom --dir=./my-project
+### Using `npx` in CI
 
-  $ hd scan sbom --file=path/to/sbom.json
-```
+You can use `npx` to run the CLI in your CI pipeline, just like you would run it locally.
 
-_See code: [src/commands/scan/sbom.ts](https://github.com/herodevs/cli/blob/v2.0.0-beta.0/src/commands/scan/sbom.ts)_
+> [!NOTE]
+> The development environment is expected to be ready to run the app. For best results,
+prefer [using the prebuilt image](#using-the-docker-image-recommended), but otherwise, prepare
+all requirements before the scan step.
 
-## `hd update [CHANNEL]`
+#### GitHub Actions
 
-update the hd CLI
+```yaml
+## .github/workflows/herodevs-eol-scan.yml
+name: HeroDevs EOL Scan
 
-```
-USAGE
-  $ hd update [CHANNEL] [--force |  | [-a | -v <value> | -i]] [-b ]
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
 
-FLAGS
-  -a, --available        See available versions.
-  -b, --verbose          Show more details about the available versions.
-  -i, --interactive      Interactively select version to install. This is ignored if a channel is provided.
-  -v, --version=<value>  Install a specific version.
-      --force            Force a re-download of the requested version.
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
 
-DESCRIPTION
-  update the hd CLI
+      - run: echo # Prepare environment, install tooling, perform setup, etc.
 
-EXAMPLES
-  Update to the stable channel:
+      - name: Run EOL Scan
+        run: npx @herodevs/cli@beta
 
-    $ hd update stable
+      - name: Upload   artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: my-eol-report
+          path: herodevs.report.json
+```
 
-  Update to a specific version:
+#### GitLab CI/CD
 
-    $ hd update --version 1.0.0
+```yaml
+image: alpine
 
-  Interactively select version:
+eol-scan:
+  script:
+    - echo # Prepare environment, install tooling, perform setup, etc.
+    - npx @herodevs/cli@beta scan eol -s
+  artifacts:
+    paths:
+      - herodevs.report.json
+```
 
-    $ hd update --interactive
+## Local Docker image scans
 
-  See available versions:
+The same pre-configured image can be pulled locally to scan in an optimized environment. Mount your code
+to `/app` or a specified working directory to perform the scan:
 
-    $ hd update --available
+```shell
+docker run -v "$PWD":/app ghcr.io/herodevs/eol-scan
 ```
-
-_See code: [@oclif/plugin-update](https://github.com/oclif/plugin-update/blob/v4.6.39/src/commands/update.ts)_
-<!-- commandsstop -->

package/bin/dev.js

@@ -1,12 +1,9 @@
 #!/usr/bin/env node
 
-process.env.GRAPHQL_HOST = 'https://api.dev.nes.herodevs.com';
-process.env.EOL_REPORT_URL = 'https://eol-report-card.stage.apps.herodevs.io/reports';
-
 import main from './main.js';
 
 try {
   await main(false);
-} catch (error) {
+} catch {
   process.exit(1);
 }

package/bin/main.js

@@ -7,9 +7,9 @@ async function main(isProduction = false) {
     strict: false, // Don't validate flags
   });
 
-  // If no arguments at all, default to scan:eol -t
+  // If no arguments at all, default to scan:eol
   if (positionals.length === 0) {
-    process.argv.splice(2, 0, 'scan:eol', '-t');
+    process.argv.splice(2, 0, 'scan:eol');
   }
   // If only flags are provided, set scan:eol as the command for those flags
   else if (positionals.length === 1 && positionals[0].startsWith('-')) {
@@ -21,7 +21,7 @@ async function main(isProduction = false) {
       development: !isProduction,
       dir: new URL('./dev.js', import.meta.url),
     });
-  } catch (error) {
+  } catch {
     process.exit(1);
   }
 }

package/bin/run.js

@@ -4,6 +4,6 @@ import main from './main.js';
 
 try {
   await main(true);
-} catch (error) {
+} catch {
   process.exit(1);
 }

package/dist/api/gql-operations.d.ts

@@ -0,0 +1,2 @@
+export declare const createReportMutation: import("graphql/language/ast.js").DocumentNode;
+export declare const getEolReportQuery: import("graphql/language/ast.js").DocumentNode;

package/dist/api/gql-operations.js

@@ -0,0 +1,36 @@
+import { gql } from '@apollo/client/core/core.cjs';
+export const createReportMutation = gql `
+mutation createReport($input: CreateEolReportInput) {
+  eol {
+    createReport(input: $input) {
+      success
+      id
+      totalRecords
+    }
+  }
+}
+`;
+export const getEolReportQuery = gql `
+query GetEolReport($input: GetEolReportInput) {
+  eol {
+    report(input: $input) {
+      id
+      createdOn
+      metadata
+      components {
+        purl
+        metadata
+        nesRemediation {
+          remediations {
+            urls {
+              main
+            }
+          }
+        }
+      }
+      page
+      totalRecords
+    }
+  }
+}
+`;

package/dist/api/nes.client.d.ts

@@ -0,0 +1,12 @@
+import { ApolloClient } from '@apollo/client/core/index.js';
+import type { CreateEolReportInput, EolReport } from '@herodevs/eol-shared';
+export declare const createApollo: (uri: string) => ApolloClient<import("@apollo/client/core/index.js").NormalizedCacheObject>;
+export declare const SbomScanner: (client: ReturnType<typeof createApollo>) => (input: CreateEolReportInput) => Promise<EolReport>;
+export declare class NesClient {
+    startScan: ReturnType<typeof SbomScanner>;
+    constructor(url: string);
+}
+/**
+ * Submit a scan for a list of purls
+ */
+export declare function submitScan(input: CreateEolReportInput): Promise<EolReport>;

package/dist/api/nes.client.js

@@ -0,0 +1,75 @@
+import { ApolloClient, HttpLink, InMemoryCache } from '@apollo/client/core/index.js';
+import { config } from "../config/constants.js";
+import { debugLogger } from "../service/log.svc.js";
+import { stripTypename } from "../utils/strip-typename.js";
+import { createReportMutation, getEolReportQuery } from "./gql-operations.js";
+export const createApollo = (uri) => new ApolloClient({
+    cache: new InMemoryCache(),
+    defaultOptions: {
+        query: { fetchPolicy: 'no-cache' },
+    },
+    link: new HttpLink({
+        uri,
+        headers: {
+            'User-Agent': `hdcli/${process.env.npm_package_version ?? 'unknown'}`,
+        },
+    }),
+});
+export const SbomScanner = (client) => {
+    return async (input) => {
+        const res = await client.mutate({
+            mutation: createReportMutation,
+            variables: { input },
+        });
+        const result = res.data?.eol?.createReport;
+        if (!result?.success || !result.id) {
+            debugLogger('failed scan %o', result || {});
+            throw new Error('Failed to create EOL report');
+        }
+        const totalRecords = result.totalRecords || 0;
+        const totalPages = Math.ceil(totalRecords / config.pageSize);
+        const pages = Array.from({ length: totalPages }, (_, index) => client.query({
+            query: getEolReportQuery,
+            variables: {
+                input: {
+                    id: result.id,
+                    page: index + 1,
+                    size: config.pageSize,
+                },
+            },
+        }));
+        const components = [];
+        let reportMetadata = null;
+        for (let i = 0; i < pages.length; i += config.concurrentPageRequests) {
+            const batch = pages.slice(i, i + config.concurrentPageRequests);
+            const batchResponses = await Promise.all(batch);
+            for (const response of batchResponses) {
+                const report = response.data.eol.report;
+                reportMetadata ??= report;
+                components.push(...(report?.components ?? []));
+            }
+        }
+        if (!reportMetadata) {
+            throw new Error('Failed to fetch EOL report');
+        }
+        return stripTypename({
+            ...reportMetadata,
+            components,
+        });
+    };
+};
+export class NesClient {
+    startScan;
+    constructor(url) {
+        this.startScan = SbomScanner(createApollo(url));
+    }
+}
+/**
+ * Submit a scan for a list of purls
+ */
+export function submitScan(input) {
+    const url = config.graphqlHost + config.graphqlPath;
+    debugLogger('Submitting scan to %s', url);
+    const client = new NesClient(url);
+    return client.startScan(input);
+}

package/dist/commands/scan/eol.d.ts

@@ -1,31 +1,25 @@
+import type { EolReport } from '@herodevs/eol-shared';
 import { Command } from '@oclif/core';
-import type { InsightsEolScanComponent } from '../../api/types/nes.types.ts';
 export default class ScanEol extends Command {
     static description: string;
     static enableJsonFlag: boolean;
-    static examples: string[];
+    static examples: {
+        description: string;
+        command: string;
+    }[];
     static flags: {
         file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        purls: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        dir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        dir: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         save: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        table: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        saveSbom: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        version: import("@oclif/core/interfaces").BooleanFlag<void>;
     };
-    run(): Promise<{
-        components: InsightsEolScanComponent[];
-    }>;
-    private getScan;
-    private getPurlsFromFile;
-    private printWebReportUrl;
+    run(): Promise<EolReport | undefined>;
+    private loadSbom;
     private scanSbom;
-    private getFilteredComponents;
     private saveReport;
+    private saveSbom;
     private displayResults;
-    private displayResultsInTable;
-    private displayTable;
-    private displayNoComponentsMessage;
-    private logLine;
-    private displayStatusSection;
-    private logLegend;
+    private getSbomFromScan;
+    private getSbomFromFile;
 }