@cyclonedx/cdxgen 10.2.6 → 10.3.0

package/README.md

@@ -2,13 +2,18 @@
 
 ![cdxgen logo](cdxgen.png)
 
-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.
+[![JSR](https://jsr.io/badges/@cyclonedx/cdxgen)](https://jsr.io/@cyclonedx/cdxgen)
 
-When used with plugins, cdxgen could generate an OBOM for Linux docker images and even VMs running Linux or Windows operating systems. cdxgen also includes an evinse tool to generate component evidence and SaaSBOM for some languages.
+cdxgen is a CLI tool, library, [REPL](./ADVANCED.md), and server to create a valid and compliant [CycloneDX][cyclonedx-homepage] Bill of Materials (BOM) 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 is a full-stack BOM specification that is easily created, human and machine-readable, and simple to parse. The tool supports CycloneDX specification versions from 1.4 - 1.6.
+
+When used with plugins:
+
+- cdxgen could generate an OBOM for Linux docker images and even VMs running Linux or Windows operating systems
+- cdxgen also includes an evinse tool to generate component evidence, CBOM and SaaSBOM for some languages
 
 ## Why cdxgen?
 
-Most SBOM tools are like simple barcode scanners. For easy applications, they can parse a few package manifests and create a list of components only based on these files without any deep inspection. Further, a typical application might have several repos, components, and libraries with complex build requirements. Traditional techniques to generate an SBOM per language or package manifest either do not work in enterprise environments or don't provide the confidence required for both compliance and automated analysis. So we built cdxgen - the universal polyglot SBOM generator that is user-friendly, precise and comprehensive!
+Most SBOM tools are like simple barcode scanners. For easy applications, they can parse a few package manifests and create a list of components only based on these files without any deep inspection. Further, a typical application might have several repos, components, and libraries with complex build requirements. Traditional techniques to generate an SBOM per language or package manifest either do not work in enterprise environments or don't provide the confidence required for both compliance and automated analysis. So we built cdxgen - the universal polyglot SBOM generator that is user-friendly, precise, and comprehensive!
 
 <img src="./docs/why-cdxgen.jpg" alt="why cdxgen" width="256">
 
@@ -85,9 +90,6 @@ For go, `go mod why` command is used to identify required packages. For php, com
 
 ```shell
 npm install -g @cyclonedx/cdxgen
-
-# For CycloneDX 1.4 compatibility use version 8.6.0 or pass the argument `--spec-version 1.4`
-npm install -g @cyclonedx/cdxgen@8.6.0
 ```
 
 If you are a [Homebrew](https://brew.sh/) user, you can also install [cdxgen](https://formulae.brew.sh/formula/cdxgen) via:
@@ -228,9 +230,13 @@ To recursively generate a single BOM for all languages pass `-r` argument.
 cdxgen -r -o bom.json
 ```
 
-To generate SBOM for an older specification version, such as 1.4, pass the version number using the `--spec-version` argument.
+The default specification used by cdxgen is 1.5. To generate BOM for a different specification version, such as 1.6 or 1.4, pass the version number using the `--spec-version` argument.
 
 ```shell
+# 1.6 is unsupported by most tools
+cdxgen -r -o bom.json --spec-version 1.6
+
+# 1.4 is supported by most tools
 cdxgen -r -o bom.json --spec-version 1.4
 ```
 
@@ -411,7 +417,7 @@ cdxgen could be extended with external binary plugins to support more SBOM use c
 sudo npm install -g @cyclonedx/cdxgen-plugins-bin
 ```
 
-### Docker / OCI container support
+## Docker / OCI container support
 
 `docker` type is automatically detected based on the presence of values such as `sha256` or `docker.io` prefix etc in the path.
 
@@ -446,7 +452,7 @@ systemctl --user start podman.socket
 podman system service -t 0 &
 ```
 
-### Generate OBOM for a live system
+## Generate OBOM for a live system
 
 You can use the `obom` command to generate an OBOM for a live system or a VM for compliance and vulnerability management purposes. Windows and Linux operating systems are supported in this mode.
 
@@ -458,6 +464,15 @@ obom
 
 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 of various types, such as operating-system, device-drivers, files, and data.
 
+## Generate Cryptography Bill of Materials (CBOM)
+
+Use the `cbom` alias to generate a CBOM. This is currently supported only for Java projects.
+
+```shell
+cbom -t java
+# cdxgen -t java --include-crypto -o bom.json .
+```
+
 ## Generating SaaSBOM and component evidences
 
 See [evinse mode](./ADVANCED.md) in the advanced documentation.

package/bin/cdxgen.js

@@ -294,11 +294,18 @@ if (!args.projectName) {
   }
 }
 
-// Support for obom aliases
+// Support for obom/cbom aliases
 if (process.argv[1].includes("obom") && !args.type) {
   args.type = "os";
 }
 
+if (process.argv[1].includes("cbom") && !args.type) {
+  options.includeCrypto = true;
+  options.includeFormulation = true;
+  options.evidence = true;
+  options.specVersion = 1.6;
+}
+
 /**
  * Method to apply advanced options such as profile and lifecycles
  *
@@ -593,7 +600,7 @@ const checkPermissions = (filePath) => {
     }
   }
   // Evidence generation
-  if (options.evidence) {
+  if (options.evidence || options.includeCrypto) {
     const evinserModule = await import("../evinser.js");
     const evinseOptions = {
       _: args._,
@@ -607,7 +614,8 @@ const checkPermissions = (filePath) => {
       usagesSlicesFile: options.usagesSlicesFile,
       dataFlowSlicesFile: options.dataFlowSlicesFile,
       reachablesSlicesFile: options.reachablesSlicesFile,
-      includeCrypto: options.includeCrypto
+      includeCrypto: options.includeCrypto,
+      specVersion: options.specVersion
     };
     const dbObjMap = await evinserModule.prepareDB(evinseOptions);
     if (dbObjMap) {

package/binary.js

@@ -19,7 +19,12 @@ let url = import.meta.url;
 if (!url.startsWith("file://")) {
   url = new URL(`file://${import.meta.url}`).toString();
 }
-const dirName = import.meta ? dirname(fileURLToPath(url)) : __dirname;
+let dirName = import.meta ? dirname(fileURLToPath(url)) : __dirname;
+// When cdxgen is used as a library, dirName would be inside the node_modules directory
+// we need to locate the base directory of the dependent project in this case.
+if (dirName.includes("node_modules")) {
+  dirName = dirName.split(join("node_modules", "@cyclonedx"))[0];
+}
 
 const isWin = _platform() === "win32";
 
@@ -399,10 +404,7 @@ export function getOSPackages(src) {
         osReleaseFile = join(src, "usr", "lib", "os-release");
       }
       if (osReleaseFile) {
-        const osReleaseInfo = readFileSync(
-          join(src, "usr", "lib", "os-release"),
-          "utf-8"
-        );
+        const osReleaseInfo = readFileSync(osReleaseFile, "utf-8");
         if (osReleaseInfo) {
           osReleaseInfo.split("\n").forEach((l) => {
             if (!l.startsWith("#") && l.includes("=")) {
@@ -425,6 +427,15 @@ export function getOSPackages(src) {
         case "pop":
           purl_type = "deb";
           break;
+        case "alpine":
+          purl_type = "apk";
+          if (osReleaseData.VERSION_ID) {
+            const versionParts = osReleaseData["VERSION_ID"].split(".");
+            if (versionParts.length >= 2) {
+              distro_codename = `alpine-${versionParts[0]}.${versionParts[1]}`;
+            }
+          }
+          break;
         default:
           if (distro_id_like.includes("debian")) {
             purl_type = "deb";
@@ -524,7 +535,7 @@ export function getOSPackages(src) {
                   } else if (group === "alpine") {
                     const dtmpA = purlObj.qualifiers.distro.split(".");
                     if (dtmpA && dtmpA.length > 2) {
-                      distro_codename = group + "-" + dtmpA[0] + "." + dtmpA[1];
+                      distro_codename = dtmpA[0] + "." + dtmpA[1];
                     }
                   } else if (group === "photon") {
                     const dtmpA = purlObj.qualifiers.distro.split("-");

package/cbomutils.js

@@ -5,6 +5,9 @@ import { join } from "node:path";
 const cbomosDbQueries = JSON.parse(
   readFileSync(join(dirNameStr, "data", "cbomosdb-queries.json"), "utf-8")
 );
+const cbomCryptoOids = JSON.parse(
+  readFileSync(join(dirNameStr, "data", "crypto-oid.json"), "utf-8")
+);
 
 /**
  * Method to collect crypto and ssl libraries from the OS.
@@ -12,7 +15,7 @@ const cbomosDbQueries = JSON.parse(
  * @param {Object} options
  * @returns osPkgsList Array of OS crypto packages
  */
-export const collectOSCryptoLibs = (options) => {
+export function collectOSCryptoLibs(options) {
   let osPkgsList = [];
   for (const queryCategory of Object.keys(cbomosDbQueries)) {
     const queryObj = cbomosDbQueries[queryCategory];
@@ -36,4 +39,29 @@ export const collectOSCryptoLibs = (options) => {
     }
   }
   return osPkgsList;
-};
+}
+
+function cleanStr(str) {
+  return str.toLowerCase().replace(/[^0-9a-z ]/gi, "");
+}
+
+/**
+ * Find crypto algorithm in the given code snippet
+ *
+ * @param {String} Code snippet
+ * @returns {Array} Arary of crypto algorithm objects with oid and description
+ */
+export function findCryptoAlgos(code) {
+  const cleanCode = cleanStr(code);
+  const cryptoAlgos = [];
+  for (const algoName of Object.keys(cbomCryptoOids)) {
+    if (cleanCode.includes(cleanStr(algoName))) {
+      cryptoAlgos.push({
+        ...cbomCryptoOids[algoName],
+        name: algoName,
+        ref: `crypto/algorithm/${algoName}@${cbomCryptoOids[algoName].oid}`
+      });
+    }
+  }
+  return cryptoAlgos;
+}

package/data/README.md

@@ -2,22 +2,23 @@
 
 Contents of data directory and their purpose.
 
-| Filename              | Purpose                                                                   |
-| --------------------- | ------------------------------------------------------------------------- |
-| bom-1.4.schema.json   | CycloneDX 1.4 jsonschema for validation                                   |
-| bom-1.5.schema.json   | CycloneDX 1.5 jsonschema for validation                                   |
-| cosdb-queries.json    | osquery useful for identifying OS packages for C                          |
-| cbomosdb-queries.json | osquery for identifying ssl packages in OS                                |
-| jsf-0.82.schema.json  | jsonschema for validation                                                 |
-| known-licenses.json   | Hard coded list to correct any license id. Not maintained.                |
-| lic-mapping.json      | Hard coded list to match a license id based on name                       |
-| pypi-pkg-aliases.json | Hard coded list to match a pypi package name from module name             |
-| python-stdlib.json    | Standard libraries that can be filtered out in python                     |
-| queries-win.json      | osquery used to generate obom for windows                                 |
-| queries.json          | osquery used to generate obom for linux                                   |
-| queries-darwin.json   | osquery used to generate obom for darwin                                  |
-| spdx-licenses.json    | valid spdx id                                                             |
-| spdx.schema.json      | jsonschema for validation                                                 |
-| vendor-alias.json     | List to correct the group names. Used while parsing .jar files            |
-| wrapdb-releases.json  | Database of all available meson wraps. Generated using contrib/wrapdb.py. |
-| frameworks-list.json  | List of string fragments to categorize components into frameworks         |
+| Filename              | Purpose                                                                                                  |
+| --------------------- | -------------------------------------------------------------------------------------------------------- |
+| bom-1.4.schema.json   | CycloneDX 1.4 jsonschema for validation                                                                  |
+| bom-1.5.schema.json   | CycloneDX 1.5 jsonschema for validation                                                                  |
+| cosdb-queries.json    | osquery useful for identifying OS packages for C                                                         |
+| cbomosdb-queries.json | osquery for identifying ssl packages in OS                                                               |
+| jsf-0.82.schema.json  | jsonschema for validation                                                                                |
+| known-licenses.json   | Hard coded list to correct any license id. Not maintained.                                               |
+| lic-mapping.json      | Hard coded list to match a license id based on name                                                      |
+| pypi-pkg-aliases.json | Hard coded list to match a pypi package name from module name                                            |
+| python-stdlib.json    | Standard libraries that can be filtered out in python                                                    |
+| queries-win.json      | osquery used to generate obom for windows                                                                |
+| queries.json          | osquery used to generate obom for linux                                                                  |
+| queries-darwin.json   | osquery used to generate obom for darwin                                                                 |
+| spdx-licenses.json    | valid spdx id                                                                                            |
+| spdx.schema.json      | jsonschema for validation                                                                                |
+| vendor-alias.json     | List to correct the group names. Used while parsing .jar files                                           |
+| wrapdb-releases.json  | Database of all available meson wraps. Generated using contrib/wrapdb.py.                                |
+| frameworks-list.json  | List of string fragments to categorize components into frameworks                                        |
+| crypto-oid.json       | Peter Gutmann's crypto oid [mapping](https://www.cs.auckland.ac.nz/~pgut001). GPL, BSD, or CC BY license |