@cyclonedx/cdxgen 9.3.1 → 9.4.0

package/README.md

@@ -10,6 +10,12 @@ NOTE:
 
 CycloneDX 1.5 specification is brand new and unsupported by many downstream tools. Use version 8.6.0 for 1.4 compatibility or pass the argument `--spec-version 1.4`.
 
+## Why cdxgen?
+
+A typical application might comprise of several repos, components, and libraries linked together. Traditional techniques to generate a single SBoM per language or package manifest do not work in enterprise environments. So we built cdxgen - the universal polyglot SBoM generator!
+
+<img src="./docs/why-cdxgen.jpg" alt="why cdxgen" width="256">
+
 ## Supported languages and package format
 
 | Language/Platform               | Package format                                                                                                    | Transitive dependencies                                                                           |
@@ -61,7 +67,7 @@ Footnotes:
 - [4] - See section on plugins
 - [5] - Powered by osquery. See section on plugins
 
-![cdxgen tree](./docs/cdxgen-tree.jpg)
+<img src="./docs/cdxgen-tree.jpg" alt="cdxgen tree" width="256">
 
 ### Automatic usage detection
 
@@ -289,7 +295,9 @@ cdxgen can retain the dependency tree under the `dependencies` attribute for a s
 | MAVEN_HOME                   | Specify maven home                                                                                                          |
 | GRADLE_CACHE_DIR             | Specify gradle cache directory. Useful for class name resolving                                                             |
 | GRADLE_MULTI_PROJECT_MODE    | Unused. Automatically handled                                                                                               |
-| GRADLE_ARGS                  | Set to pass additional arguments such as profile or settings to gradle. Eg: --configuration runtimeClassPath                |
+| GRADLE_ARGS                  | Set to pass additional arguments such as profile or settings to gradle (all tasks). Eg: --configuration runtimeClassPath    |
+| GRADLE_ARGS_PROPERTIES       | Set to pass additional arguments only to the `gradle properties` task, used for collecting metadata about the project       |
+| GRADLE_ARGS_DEPENDENCIES     | Set to pass additional arguments only to the `gradle dependencies` task, used for listing actual project dependencies       |
 | GRADLE_HOME                  | Specify gradle home                                                                                                         |
 | GRADLE_CMD                   | Set to override gradle command                                                                                              |
 | GRADLE_DEPENDENCY_TASK       | By default cdxgen use the task "dependencies" to collect packages. Set to override the task name.                           |
@@ -373,10 +381,33 @@ cdxgen can sign the generated SBoM json file to increase authenticity and non-re
 - SBOM_SIGN_PRIVATE_KEY: Location to the RSA private key
 - SBOM_SIGN_PUBLIC_KEY: Optional. Location to the RSA public key
 
-To generate test public/private key pairs, you can run cdxgen by passing the argument `--generate-key-and-sign`. The generated json file would have an attribute called `signature` which could be used for validation. [jwt.io](jwt.io) is a known site that could be used for such signature validation.
+To generate test public/private key pairs, you can run cdxgen by passing the argument `--generate-key-and-sign`. The generated json file would have an attribute called `signature` which could be used for validation. [jwt.io](https://jwt.io) is a known site that could be used for such signature validation.
 
 ![SBoM signing](sbom-sign.jpg)
 
+### Verifying the signature (Node.js example)
+
+There are many [libraries](https://jwt.io/#libraries-io) available to validate JSON Web Tokens. Below is a javascript example.
+
+```js
+# npm install jws
+const jws = require("jws");
+const fs = require("fs");
+// Location of the SBoM json file
+const bomJsonFile = "bom.json";
+// Location of the public key
+const publicKeyFile = "public.key";
+const bomJson = JSON.parse(fs.readFileSync(bomJsonFile, "utf8"));
+// Retrieve the signature
+const bomSignature = bomJson.signature.value;
+const validationResult = jws.verify(bomSignature, bomJson.signature.algorithm, fs.readFileSync(publicKeyFile, "utf8"));
+if (validationResult) {
+  console.log("Signature is valid!");
+} else {
+  console.log("SBoM signature is invalid :(");
+}
+```
+
 ## Automatic services detection
 
 cdxgen could automatically detect names of services from YAML manifests such as docker-compose or Kubernetes or Skaffold manifests. These would be populated under the `services` attribute in the generated SBoM. Please help improve this feature by filing issues for any inaccurate detection.
@@ -412,6 +443,50 @@ const bomNSData = await createBom(filePath, options);
 const dbody = await submitBom(args, bomNSData.bomJson);
 ```
 
+## Interactive mode
+
+`cdxi` is a new interactive REPL server to interactively create, import and search an SBoM. All the exported functions from cdxgen and node.js could be used in this mode. In addition, several custom commands are defined.
+
+### Custom commands
+
+| Command   | Description                                                                                                                                                                                                    |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| .create   | Create an SBoM from a path                                                                                                                                                                                     |
+| .import   | Import an existing SBoM from a path. Any SBoM in CycloneDX format is supported.                                                                                                                                |
+| .search   | Search the given string in the components name, group, purl and description                                                                                                                                    |
+| .sort     | Sort the components based on the given attribute. Eg: .sort name to sort by name. Accepts full jsonata [order by](http://docs.jsonata.org/path-operators#order-by-) clause too. Eg: `.sort components^(>name)` |
+| .query    | Pass a raw query in [jsonata](http://docs.jsonata.org/) format                                                                                                                                                 |
+| .print    | Print the SBoM as a table                                                                                                                                                                                      |
+| .tree     | Print the dependency tree if available                                                                                                                                                                         |
+| .validate | Validate the SBoM                                                                                                                                                                                              |
+| .exit     | To exit the shell                                                                                                                                                                                              |
+| .save     | To save the modified SBoM to a new file                                                                                                                                                                        |
+| .update   | Update components based on query expression. Use syntax `\| query \| new object \|`. See example.                                                                                                              |
+
+### Sample REPL usage
+
+Start the REPL server.
+
+```shell
+cdxi
+```
+
+Below are some example commands to create an SBoM for a spring application and perform searches and queries.
+
+```
+.create /mnt/work/vuln-spring
+.print
+.search spring
+.query components[name ~> /spring/ and scope = "required"]
+.sort name
+.sort components^(>name)
+.update | components[name ~> /spring/] | {'publisher': "foo"} |
+```
+
+### REPL History
+
+Repl history will get persisted under `$HOME/.config/.cdxgen` directory. To override this location, use the environment variable `CDXGEN_REPL_HISTORY`.
+
 ## Node.js >= 20 permission model
 
 Refer to the [permissions document](./docs/PERMISSIONS.md)
@@ -425,3 +500,7 @@ npm run lint
 npm run pretty
 npm test
 ```
+
+## Enterprise support
+
+Enterprise support including custom development and integration services are available via AppThreat Ltd. Free community support is also available via [discord](https://discord.gg/tmmtjCEHNV).

package/bin/cdxgen.js

@@ -266,9 +266,10 @@ const checkPermissions = (filePath) => {
           }
           let privateKeyToUse = undefined;
           let jwkPublicKey = undefined;
+          let publicKeyFile = undefined;
           if (args.generateKeyAndSign) {
             const jdirName = dirname(jsonFile);
-            const publicKeyFile = join(jdirName, "public.key");
+            publicKeyFile = join(jdirName, "public.key");
             const privateKeyFile = join(jdirName, "private.key");
             const { privateKey, publicKey } = crypto.generateKeyPairSync(
               "rsa",
@@ -331,6 +332,26 @@ const checkPermissions = (filePath) => {
                 jsonFile,
                 JSON.stringify(bomJsonUnsignedObj, null, 2)
               );
+              if (publicKeyFile) {
+                // Verifying this signature
+                const signatureVerification = jws.verify(
+                  signature,
+                  alg,
+                  fs.readFileSync(publicKeyFile, "utf8")
+                );
+                if (signatureVerification) {
+                  console.log(
+                    "SBoM signature is verifiable with the public key and the algorithm",
+                    publicKeyFile,
+                    alg
+                  );
+                } else {
+                  console.log("SBoM signature verification was unsuccessful");
+                  console.log(
+                    "Check if the public key was exported in PEM format"
+                  );
+                }
+              }
             }
           } catch (ex) {
             console.log("SBoM signing was unsuccessful", ex);

package/bin/repl.js

@@ -0,0 +1,311 @@
+import repl from "node:repl";
+import jsonata from "jsonata";
+import fs from "node:fs";
+import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import process from "node:process";
+
+import { createBom } from "../index.js";
+import { validateBom } from "../validator.js";
+import { printTable, printDependencyTree } from "../display.js";
+
+const options = {
+  useColors: true,
+  breakEvalOnSigint: true,
+  preview: true,
+  prompt: "↝ ",
+  ignoreUndefined: true,
+  useGlobal: true
+};
+
+const cdxArt = ` ██████╗██████╗ ██╗  ██╗
+██╔════╝██╔══██╗╚██╗██╔╝
+██║     ██║  ██║ ╚███╔╝ 
+██║     ██║  ██║ ██╔██╗ 
+╚██████╗██████╔╝██╔╝ ██╗
+ ╚═════╝╚═════╝ ╚═╝  ╚═╝
+`;
+
+console.log("\n" + cdxArt);
+
+// The current sbom is stored here
+let sbom = undefined;
+
+let historyFile = undefined;
+const historyConfigDir = join(homedir(), ".config", ".cdxgen");
+if (!process.env.CDXGEN_REPL_HISTORY && !fs.existsSync(historyConfigDir)) {
+  try {
+    fs.mkdirSync(historyConfigDir, { recursive: true });
+    historyFile = join(historyConfigDir, ".repl_history");
+  } catch (e) {
+    // ignore
+  }
+} else {
+  historyFile = join(historyConfigDir, ".repl_history");
+}
+
+export const importSbom = (sbomOrPath) => {
+  if (sbomOrPath && sbomOrPath.endsWith(".json") && fs.existsSync(sbomOrPath)) {
+    try {
+      sbom = JSON.parse(fs.readFileSync(sbomOrPath, "utf-8"));
+      console.log(`✅ SBoM imported successfully from ${sbomOrPath}`);
+    } catch (e) {
+      console.log(
+        `⚠ Unable to import the SBoM from ${sbomOrPath} due to ${e}`
+      );
+    }
+  } else {
+    console.log(`⚠ ${sbomOrPath} is invalid.`);
+  }
+};
+// Load any sbom passed from the command line
+if (process.argv.length > 2) {
+  importSbom(process.argv[process.argv.length - 1]);
+  console.log("💭 Type .print to view the SBoM as a table");
+} else if (fs.existsSync("bom.json")) {
+  // If the current directory has a bom.json load it
+  importSbom("bom.json");
+} else {
+  console.log("💭 Use .create <path> to create an SBoM for the given path.");
+  console.log("💭 Use .import <json> to import an existing SBoM.");
+  console.log("💭 Type .exit or press ctrl+d to close.");
+}
+
+const cdxgenRepl = repl.start(options);
+if (historyFile) {
+  cdxgenRepl.setupHistory(
+    process.env.CDXGEN_REPL_HISTORY || historyFile,
+    (err) => {
+      if (err) {
+        console.log(
+          "⚠ REPL history would not be persisted for this session. Set the environment variable CDXGEN_REPL_HISTORY to specify a custom history file"
+        );
+      }
+    }
+  );
+}
+cdxgenRepl.defineCommand("create", {
+  help: "create an SBoM for the given path",
+  async action(sbomOrPath) {
+    this.clearBufferedCommand();
+    const tempDir = fs.mkdtempSync(join(tmpdir(), "cdxgen-repl-"));
+    const bomFile = join(tempDir, "bom.json");
+    const bomNSData = await createBom(sbomOrPath, {
+      multiProject: true,
+      installDeps: true,
+      output: bomFile
+    });
+    if (bomNSData) {
+      sbom = bomNSData.bomJson;
+      console.log("✅ SBoM imported successfully.");
+      console.log("💭 Type .print to view the SBoM as a table");
+    } else {
+      console.log("SBoM was not generated successfully");
+    }
+    this.displayPrompt();
+  }
+});
+cdxgenRepl.defineCommand("import", {
+  help: "import an existing SBoM",
+  action(sbomOrPath) {
+    this.clearBufferedCommand();
+    importSbom(sbomOrPath);
+    this.displayPrompt();
+  }
+});
+cdxgenRepl.defineCommand("exit", {
+  help: "exit",
+  action() {
+    this.close();
+  }
+});
+cdxgenRepl.defineCommand("sbom", {
+  help: "show the current sbom",
+  action() {
+    if (sbom) {
+      console.log(sbom);
+    } else {
+      console.log(
+        "⚠ No SBoM is loaded. Use .import command to import an existing SBoM"
+      );
+    }
+    this.displayPrompt();
+  }
+});
+cdxgenRepl.defineCommand("search", {
+  help: "search the current sbom",
+  async action(searchStr) {
+    if (sbom) {
+      if (searchStr) {
+        try {
+          if (!searchStr.includes("~>")) {
+            searchStr = `components[group ~> /${searchStr}/i or name ~> /${searchStr}/i or description ~> /${searchStr}/i or publisher ~> /${searchStr}/i or purl ~> /${searchStr}/i]`;
+          }
+          const expression = jsonata(searchStr);
+          let components = await expression.evaluate(sbom);
+          if (!components) {
+            console.log("No results found!");
+          } else {
+            printTable({ components, dependencies: [] });
+          }
+        } catch (e) {
+          console.log(e);
+        }
+      } else {
+        console.log(
+          "⚠ Specify the search string. Eg: .search <search string>"
+        );
+      }
+    } else {
+      console.log(
+        "⚠ No SBoM is loaded. Use .import command to import an existing SBoM"
+      );
+    }
+    this.displayPrompt();
+  }
+});
+cdxgenRepl.defineCommand("sort", {
+  help: "sort the current sbom based on the attribute",
+  async action(sortStr) {
+    if (sbom) {
+      if (sortStr) {
+        try {
+          if (!sortStr.includes("^")) {
+            sortStr = `components^(${sortStr})`;
+          }
+          const expression = jsonata(sortStr);
+          let components = await expression.evaluate(sbom);
+          if (!components) {
+            console.log("No results found!");
+          } else {
+            printTable({ components, dependencies: [] });
+            // Store the sorted list in memory
+            if (components.length === sbom.components.length) {
+              sbom.components = components;
+            }
+          }
+        } catch (e) {
+          console.log(e);
+        }
+      } else {
+        console.log("⚠ Specify the attribute to sort by. Eg: .sort name");
+      }
+    } else {
+      console.log(
+        "⚠ No SBoM is loaded. Use .import command to import an existing SBoM"
+      );
+    }
+    this.displayPrompt();
+  }
+});
+cdxgenRepl.defineCommand("query", {
+  help: "query the current sbom",
+  async action(querySpec) {
+    if (sbom) {
+      if (querySpec) {
+        try {
+          const expression = jsonata(querySpec);
+          console.log(await expression.evaluate(sbom));
+        } catch (e) {
+          console.log(e);
+        }
+      } else {
+        console.log(
+          "⚠ Specify the search specification in jsonata format. Eg: .query metadata.component"
+        );
+      }
+    } else {
+      console.log(
+        "⚠ No SBoM is loaded. Use .import command to import an existing SBoM"
+      );
+    }
+    this.displayPrompt();
+  }
+});
+cdxgenRepl.defineCommand("print", {
+  help: "print the current sbom as a table",
+  action() {
+    if (sbom) {
+      printTable(sbom);
+    } else {
+      console.log(
+        "⚠ No SBoM is loaded. Use .import command to import an existing SBoM"
+      );
+    }
+    this.displayPrompt();
+  }
+});
+cdxgenRepl.defineCommand("tree", {
+  help: "display the dependency tree",
+  action() {
+    if (sbom) {
+      printDependencyTree(sbom);
+    } else {
+      console.log(
+        "⚠ No SBoM is loaded. Use .import command to import an existing SBoM"
+      );
+    }
+    this.displayPrompt();
+  }
+});
+cdxgenRepl.defineCommand("validate", {
+  help: "validate the sbom",
+  action() {
+    if (sbom) {
+      const result = validateBom(sbom);
+      if (result) {
+        console.log("SBoM is valid!");
+      }
+    } else {
+      console.log(
+        "⚠ No SBoM is loaded. Use .import command to import an existing SBoM"
+      );
+    }
+    this.displayPrompt();
+  }
+});
+cdxgenRepl.defineCommand("save", {
+  help: "save the sbom to a new file",
+  action(saveToFile) {
+    if (sbom) {
+      if (!saveToFile) {
+        saveToFile = "bom.json";
+      }
+      fs.writeFileSync(saveToFile, JSON.stringify(sbom, null, 2));
+      console.log(`SBoM saved successfully to ${saveToFile}`);
+    } else {
+      console.log(
+        "⚠ No SBoM is loaded. Use .import command to import an existing SBoM"
+      );
+    }
+    this.displayPrompt();
+  }
+});
+cdxgenRepl.defineCommand("update", {
+  help: "update the sbom components based on the given query",
+  async action(updateSpec) {
+    if (sbom) {
+      if (!updateSpec) {
+        return;
+      }
+      if (!updateSpec.startsWith("|")) {
+        updateSpec = "|" + updateSpec;
+      }
+      if (!updateSpec.endsWith("|")) {
+        updateSpec = updateSpec + "|";
+      }
+      updateSpec = "$ ~> " + updateSpec;
+      const expression = jsonata(updateSpec);
+      const newSbom = await expression.evaluate(sbom);
+      if (newSbom && newSbom.components.length <= sbom.components.length) {
+        sbom = newSbom;
+      }
+      console.log("SBoM updated successfully.");
+    } else {
+      console.log(
+        "⚠ No SBoM is loaded. Use .import command to import an existing SBoM"
+      );
+    }
+    this.displayPrompt();
+  }
+});

package/display.js

@@ -13,6 +13,9 @@ const MAX_TREE_DEPTH = 3;
 
 export const printTable = (bomJson) => {
   const data = [["Group", "Name", "Version", "Scope"]];
+  if (!bomJson || !bomJson.components) {
+    return;
+  }
   for (const comp of bomJson.components) {
     data.push([comp.group || "", comp.name, comp.version, comp.scope || ""]);
   }

package/docker.js

@@ -24,7 +24,7 @@ import { x } from "tar";
 import { spawnSync } from "node:child_process";
 import { DEBUG_MODE } from "./utils.js";
 
-const isWin = _platform() === "win32";
+export const isWin = _platform() === "win32";
 
 let dockerConn = undefined;
 let isPodman = false;

package/docker.test.js

@@ -3,14 +3,17 @@ import {
   parseImageName,
   getImage,
   removeImage,
-  exportImage
+  exportImage,
+  isWin
 } from "./docker.js";
 import { expect, test } from "@jest/globals";
 
 test("docker connection", async () => {
-  const dockerConn = await getConnection();
-  expect(dockerConn);
-});
+  if (!(isWin && process.env.CI === "true")) {
+    const dockerConn = await getConnection();
+    expect(dockerConn);
+  }
+}, 120000);
 
 test("parseImageName tests", () => {
   expect(parseImageName("debian")).toEqual({
@@ -59,7 +62,7 @@ test("parseImageName tests", () => {
     digest: "5d008306a7c5d09ba0161a3408fa3839dc2c9dd991ffb68adecc1040399fe9e1",
     platform: ""
   });
-});
+}, 120000);
 
 test("docker getImage", async () => {
   const imageData = await getImage("hello-world:latest");