@cyclonedx/cdxgen 9.3.2 → 9.5.0

package/README.md

@@ -2,13 +2,19 @@
 
 ![cdxgen logo](cdxgen.png)
 
-cdxgen is a cli tool and a library to create a valid and compliant [CycloneDX][cyclonedx-homepage] Software Bill-of-Materials (SBOM) containing an aggregate of all project dependencies for c/c++, node.js, php, python, ruby, rust, java, .Net, dart, haskell, elixir, and Go projects in JSON format. CycloneDX 1.5 is a lightweight SBOM specification that is easily created, human and machine-readable, and simple to parse.
+cdxgen is a cli tool, library, [REPL](./ADVANCED.md) and server to create a valid and compliant [CycloneDX][cyclonedx-homepage] Software Bill-of-Materials (SBOM) containing an aggregate of all project dependencies for c/c++, node.js, php, python, ruby, rust, java, .Net, dart, haskell, elixir, and Go projects in JSON format. CycloneDX 1.5 is a lightweight SBOM specification that is easily created, human and machine-readable, and simple to parse.
 
-When used with plugins, cdxgen could generate an SBoM for Linux docker images and even VMs running Linux or Windows operating system.
+When used with plugins, cdxgen could generate an SBoM for Linux docker images and even VMs running Linux or Windows operating system. cdxgen also includes a tool called `evinse` that can generate component evidences for some languages.
 
 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`.
+CycloneDX 1.5 specification is 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
 
@@ -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
 
@@ -87,7 +93,7 @@ sudo npm install -g @cyclonedx/cdxgen@8.6.0
 Deno install is also supported.
 
 ```shell
-deno install --allow-read --allow-env --allow-run --allow-sys=uid,systemMemoryInfo --allow-write --allow-net -n cdxgen "npm:@cyclonedx/cdxgen"
+deno install --allow-read --allow-env --allow-run --allow-sys=uid,systemMemoryInfo --allow-write --allow-net -n cdxgen "npm:@cyclonedx/cdxgen/cdxgen"
 ```
 
 You can also use the cdxgen container image
@@ -367,6 +373,10 @@ cdxgen -t os
 
 This feature is powered by osquery which is [installed](https://github.com/cyclonedx/cdxgen-plugins-bin/blob/main/build.sh#L8) along with the binary plugins. cdxgen would opportunistically try to detect as many components, apps and extensions as possible using the [default queries](queries.json). The process would take several minutes and result in an SBoM file with thousands of components.
 
+## Generating component evidence
+
+See [evinse mode](./ADVANCED.md) in the advanced documentation.
+
 ## SBoM signing
 
 cdxgen can sign the generated SBoM json file to increase authenticity and non-repudiation capabilities. To enable this, set the following environment variables.
@@ -375,13 +385,45 @@ 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
+
+Use the bundled `cdx-verify` command which supports verifying a single signature added at the bom level.
+
+```shell
+npm install -g @cyclonedx/cdxgen
+cdx-verify -i bom.json --public-key public.key
+```
+
+### Custom verification tool (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.
+cdxgen can 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. With [evinse](./ADVANCED.md), additional services could be detected by parsing common annotations from the source code.
 
 ## Conversion to SPDX format
 
@@ -427,3 +469,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/analyzer.js

@@ -1,5 +1,5 @@
 import { parse } from "@babel/parser";
-import babelTraverse from "@babel/traverse";
+import traverse from "@babel/traverse";
 import { join } from "path";
 import { readdirSync, statSync, readFileSync } from "fs";
 import { basename, resolve, isAbsolute } from "path";
@@ -23,7 +23,7 @@ const IGNORE_DIRS = [
 ];
 
 const IGNORE_FILE_PATTERN = new RegExp(
-  "(conf|test|spec|mock|\\.d)\\.(js|ts|tsx)$",
+  "(conf|config|test|spec|mock|\\.d)\\.(js|ts|tsx)$",
   "i"
 );
 
@@ -64,6 +64,7 @@ const babelParserOptions = {
   sourceType: "unambiguous",
   allowImportExportEverywhere: true,
   allowAwaitOutsideFunction: true,
+  allowNewTargetOutsideFunction: true,
   allowReturnOutsideFunction: true,
   allowSuperOutsideMethod: true,
   errorRecovery: true,
@@ -123,8 +124,32 @@ const setFileRef = (allImports, file, pathway) => {
  */
 const parseFileASTTree = (file, allImports) => {
   const ast = parse(readFileSync(file, "utf-8"), babelParserOptions);
-  babelTraverse(ast, {
-    // Used for all ES6 import statements
+  traverse.default(ast, {
+    Import: (path) => {
+      if (path && path.node) {
+        setFileRef(allImports, file, path.node.source.value);
+      }
+    },
+    ImportDefaultSpecifier: (path) => {
+      if (path && path.node) {
+        setFileRef(allImports, file, path.node.source.value);
+      }
+    },
+    ImportNamespaceSpecifier: (path) => {
+      if (path && path.node) {
+        setFileRef(allImports, file, path.node.source.value);
+      }
+    },
+    ImportAttribute: (path) => {
+      if (path && path.node) {
+        setFileRef(allImports, file, path.node.source.value);
+      }
+    },
+    ImportOrExportDeclaration: (path) => {
+      if (path && path.node) {
+        setFileRef(allImports, file, path.node.source.value);
+      }
+    },
     ImportDeclaration: (path) => {
       if (path && path.node) {
         setFileRef(allImports, file, path.node.source.value);

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/evinse.js

@@ -0,0 +1,121 @@
+// Evinse (Evinse Verification Is Nearly SBoM Evidence)
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { join } from "node:path";
+import fs from "node:fs";
+import { homedir, platform as _platform } from "node:os";
+import process from "node:process";
+import { analyzeProject, createEvinseFile, prepareDB } from "../evinser.js";
+import { validateBom } from "../validator.js";
+import { printCallStack, printOccurrences, printServices } from "../display.js";
+
+const isWin = _platform() === "win32";
+const isMac = _platform() === "darwin";
+let ATOM_DB = join(homedir(), ".local", "share", ".atomdb");
+if (isWin) {
+  ATOM_DB = join(homedir(), "AppData", "Local", ".atomdb");
+} else if (isMac) {
+  ATOM_DB = join(homedir(), "Library", "Application Support", ".atomdb");
+}
+
+if (!process.env.ATOM_DB && !fs.existsSync(ATOM_DB)) {
+  try {
+    fs.mkdirSync(ATOM_DB, { recursive: true });
+  } catch (e) {
+    // ignore
+  }
+}
+const args = yargs(hideBin(process.argv))
+  .option("input", {
+    alias: "i",
+    description: "Input SBoM file. Default bom.json",
+    default: "bom.json"
+  })
+  .option("output", {
+    alias: "o",
+    description: "Output file. Default bom.evinse.json",
+    default: "bom.evinse.json"
+  })
+  .option("language", {
+    alias: "l",
+    description: "Application language",
+    default: "java",
+    choices: ["java", "jar", "javascript", "python", "android", "cpp"]
+  })
+  .option("db-path", {
+    description: `Atom slices DB path. Default ${ATOM_DB}`,
+    default: process.env.ATOM_DB || ATOM_DB
+  })
+  .option("force", {
+    description: "Force creation of the database",
+    default: false,
+    type: "boolean"
+  })
+  .option("skip-maven-collector", {
+    description:
+      "Skip collecting jars from maven and gradle caches. Can speedup re-runs if the data was cached previously.",
+    default: false,
+    type: "boolean"
+  })
+  .option("with-deep-jar-collector", {
+    description:
+      "Enable collection of all jars from maven cache directory. Useful to improve the recall for callstack evidence.",
+    default: false,
+    type: "boolean"
+  })
+  .option("annotate", {
+    description: "Include contents of atom slices as annotations",
+    default: true,
+    type: "boolean"
+  })
+  .option("with-data-flow", {
+    description: "Enable inter-procedural data-flow slicing.",
+    default: false,
+    type: "boolean"
+  })
+  .option("usages-slices-file", {
+    description: "Use an existing usages slices file.",
+    default: "usages.slices.json"
+  })
+  .option("data-flow-slices-file", {
+    description: "Use an existing data-flow slices file.",
+    default: "data-flow.slices.json"
+  })
+  .option("print", {
+    alias: "p",
+    type: "boolean",
+    description: "Print the evidences as table"
+  })
+  .scriptName("evinse")
+  .version()
+  .help("h").argv;
+
+const evinseArt = `
+███████╗██╗   ██╗██╗███╗   ██╗███████╗███████╗
+██╔════╝██║   ██║██║████╗  ██║██╔════╝██╔════╝
+█████╗  ██║   ██║██║██╔██╗ ██║███████╗█████╗  
+██╔══╝  ╚██╗ ██╔╝██║██║╚██╗██║╚════██║██╔══╝  
+███████╗ ╚████╔╝ ██║██║ ╚████║███████║███████╗
+╚══════╝  ╚═══╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝
+`;
+
+console.log(evinseArt);
+(async () => {
+  // First, prepare the database by cataloging jars and other libraries
+  const dbObjMap = await prepareDB(args);
+  if (dbObjMap) {
+    // Analyze the project using atom. Convert package namespaces to purl using the db
+    const sliceArtefacts = await analyzeProject(dbObjMap, args);
+    // Create the SBoM with Evidence
+    const bomJson = createEvinseFile(sliceArtefacts, args);
+    // Validate our final SBoM
+    if (!validateBom(bomJson)) {
+      process.exit(1);
+    }
+    if (args.print) {
+      printOccurrences(bomJson);
+      printCallStack(bomJson);
+      printServices(bomJson);
+    }
+  }
+})();