@herodevs/cli 2.0.0-beta.4 → 2.0.0-beta.6

package/README.md

@@ -14,8 +14,8 @@ The HeroDevs CLI
 
 1. Install node v20 or higher: [Download Node](https://nodejs.org/en/download)
 1. Install the CLI using one of the following methods:
-   - Globally: Refer to the [Usage](#usage) instructions on installing the CLI globally
-   - Npx:`npx @herodevs/cli@beta <commands>`
+   * Globally: Refer to the [Usage](#usage) instructions on installing the CLI globally
+   * npx: `npx @herodevs/cli@beta`
 1. Refer to the [Commands](#commands) section for a list of commands
 
 ## TERMS
@@ -24,21 +24,20 @@ Use of this CLI is governed by the [HeroDevs End of Life Dataset Terms of Servic
 
 ## 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:
 
-* They do not install dependencies or modify package manager files (package-lock.json, yarn.lock, etc.)
-* They analyze the project in its current state
+* It does not install dependencies or modify package manager files (package-lock.json, yarn.lock, etc.)
+* It analyzes the project in its current state
 * If you need dependencies installed for accurate scanning, please install them manually before running the scan
 
-
 ## 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.4 linux-x64 node-v22.16.0
+@herodevs/cli/2.0.0-beta.6 darwin-arm64 node-v22.18.0
 $ hd --help [COMMAND]
 USAGE
   $ hd COMMAND
@@ -48,10 +47,7 @@ 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)
 
 ## `hd help [COMMAND]`
@@ -72,168 +68,206 @@ DESCRIPTION
   Display help for hd.
 ```
 
-_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.29/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]
 
 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 herodevs.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
 
 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.4/src/commands/report/committers.ts)_
+_See code: [src/commands/scan/eol.ts](https://github.com/herodevs/cli/blob/v2.0.0-beta.5/src/commands/scan/eol.ts)_
 
-## `hd report purls`
+## `hd update [CHANNEL]`
 
-Generate a list of purls from a sbom
+update the hd CLI
 
 ```
 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 herodevs.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.4/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]
-
-FLAGS
-  -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 herodevs.report.json in the scanned directory
 
-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.4/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 herodevs.sbom.json in the scanned directory
+#### 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
+```
 
-GLOBAL FLAGS
-  --json  Format output as json.
+### Using `npx`
 
-DESCRIPTION
-  Scan a SBOM for purls
+You can use `npx` to run the CLI just like you'd run it locally.
 
-EXAMPLES
-  $ hd scan sbom --dir=./my-project
+> [!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 scan sbom --file=path/to/sbom.json
-```
+#### GitHub Actions
 
-_See code: [src/commands/scan/sbom.ts](https://github.com/herodevs/cli/blob/v2.0.0-beta.4/src/commands/scan/sbom.ts)_
+```yaml
+## .github/workflows/herodevs-eol-scan.yml
+name: HeroDevs EOL Scan
 
-## `hd update [CHANNEL]`
-
-update the hd CLI
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
 
-```
-USAGE
-  $ hd update [CHANNEL] [--force |  | [-a | -v <value> | -i]] [-b ]
-
-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.45/src/commands/update.ts)_
-<!-- commandsstop -->

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,71 @@
+import { ApolloClient, HttpLink, InMemoryCache } from '@apollo/client/core/index.js';
+import { config } from "../config/constants.js";
+import { debugLogger } from "../service/log.svc.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 { ...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,24 +1,24 @@
+import type { EolReport } from '@herodevs/eol-shared';
 import { Command } from '@oclif/core';
-import type { ComponentStatus, 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>;
+        saveSbom: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
-    run(): Promise<{
-        components: InsightsEolScanComponent[];
-        createdOn: string;
-    }>;
-    private getScan;
-    private getPurlsFromFile;
-    private printWebReportUrl;
+    run(): Promise<EolReport | undefined>;
+    private loadSbom;
     private scanSbom;
     private saveReport;
+    private saveSbom;
     private displayResults;
+    private getSbomFromScan;
+    private getSbomFromFile;
 }
-export declare function countComponentsByStatus(components: InsightsEolScanComponent[]): Record<ComponentStatus | 'NES_AVAILABLE', number>;