@cyclonedx/cdxgen 9.0.1 → 9.1.0

package/README.md

@@ -2,10 +2,14 @@
 
 ![cdxgen logo](cdxgen.png)
 
-This tool creates 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 XML and 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 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.
 
 When used with plugins, cdxgen could generate an SBoM for Linux docker images and even VMs running Linux or Windows operating system.
 
+NOTE:
+
+CycloneDX 1.5 specification is brand new and unsupported by many downstream tools. Use version 8.6.0 for 1.4 compatibility.
+
 ## Supported languages and package format
 
 | Language/Platform               | Package format                                                                                          | Transitive dependencies                                                                           |
@@ -57,6 +61,8 @@ Footnotes:
 - [4] - See section on plugins
 - [5] - Powered by osquery. See section on plugins
 
+![cdxgen tree](./docs/cdxgen-tree.jpg)
+
 ### Automatic usage detection
 
 For node.js projects, lock files are parsed initially so the SBoM would include all dependencies including dev dependencies. An AST parser powered by babel-parser is then used to detect packages that are imported and used by non-test code. Such imported packages would automatically have their `scope` property set to `required` in the resulting SBoM. By passing the argument `--no-babel`, you can disable this analysis. Scope property would then be set based on the `dev` attribute in the lock file.
@@ -73,12 +79,35 @@ For go, `go mod why` command is used to identify required packages. For php, com
 
 ```shell
 sudo npm install -g @cyclonedx/cdxgen
+
+# For CycloneDX 1.4 compatibility use version 8.6.0
+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"
 ```
 
 You can also use the cdxgen container image
 
 ```bash
 docker run --rm -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen -r /app -o /app/bom.json
+
+docker run --rm -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen:v8.6.0 -r /app -o /app/bom.json
+```
+
+To use the deno version, use `ghcr.io/cyclonedx/cdxgen-deno` as the image name.
+
+```bash
+docker run --rm -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen-deno -r /app -o /app/bom.json
+```
+
+In deno applications, cdxgen could be directly imported without any conversion. Please see the section on [integration as library](#integration-as-library)
+
+```ts
+import { createBom, submitBom } from "npm:@cyclonedx/cdxgen@^9.0.1";
 ```
 
 ## Getting Help
@@ -86,40 +115,43 @@ docker run --rm -v /tmp:/tmp -v $(pwd):/app:rw -t ghcr.io/cyclonedx/cdxgen -r /a
 ```text
 $ cdxgen -h
 Options:
-  -o, --output                 Output file for bom.xml or bom.json. Default
-                               bom.json
+  -o, --output                 Output file for bom.xml or bom.json. Default bom.
+                               json
   -t, --type                   Project type
   -r, --recurse                Recurse mode suitable for mono-repos    [boolean]
-  -p, --print                  Print the SBoM as a table. Defaults to true if
-                               output file is not specified with -o    [boolean]
-  -c, --resolve-class          Resolve class names for packages. jars only for
-                               now.                                    [boolean]
-      --deep                   Perform deep searches for components. Useful
-                               while scanning live OS and oci images.  [boolean]
-      --server-url             Dependency track url. Eg:
-                               https://deptrack.cyclonedx.io
+  -p, --print                  Print the SBoM as a table with tree. Defaults to
+                               true if output file is not specified with -o
+                                                                       [boolean]
+  -c, --resolve-class          Resolve class names for packages. jars only for n
+                               ow.                                     [boolean]
+      --deep                   Perform deep searches for components. Useful whil
+                               e scanning live OS and oci images.      [boolean]
+      --server-url             Dependency track url. Eg: https://deptrack.cyclon
+                               edx.io
       --api-key                Dependency track api key
       --project-group          Dependency track project group
-      --project-name           Dependency track project name. Default use the
-                               directory name
+      --project-name           Dependency track project name. Default use the di
+                               rectory name
       --project-version        Dependency track project version    [default: ""]
-      --project-id             Dependency track project id. Either provide the
-                               id or the project name and version together
+      --project-id             Dependency track project id. Either provide the i
+                               d or the project name and version together
       --required-only          Include only the packages with required scope on
                                the SBoM.                               [boolean]
       --fail-on-error          Fail if any dependency extractor fails. [boolean]
-      --no-babel               Do not use babel to perform usage analysis for
-                               JavaScript/TypeScript projects.         [boolean]
+      --no-babel               Do not use babel to perform usage analysis for Ja
+                               vaScript/TypeScript projects.           [boolean]
       --generate-key-and-sign  Generate an RSA public/private key pair and then
-                               sign the generated SBoM using JSON Web
-                               Signatures.                             [boolean]
+                               sign the generated SBoM using JSON Web Signatures
+                               .                                       [boolean]
       --server                 Run cdxgen as a server                  [boolean]
       --server-host            Listen address             [default: "127.0.0.1"]
       --server-port            Listen port                     [default: "9090"]
-      --install-deps           Install dependencies automatically for some
-                               projects. Defaults to true but disabled for
-                               containers and oci scans. Use --no-install-deps
-                               to disable this feature.[boolean] [default: true]
+      --install-deps           Install dependencies automatically for some proje
+                               cts. Defaults to true but disabled for containers
+                                and oci scans. Use --no-install-deps to disable
+                               this feature.           [boolean] [default: true]
+      --validate               Validate the generated SBoM using json schema.
+                                                      [boolean] [default: false]
       --version                Show version number                     [boolean]
   -h                           Show help                               [boolean]
 ```
@@ -231,6 +263,7 @@ cdxgen can retain the dependency tree under the `dependencies` attribute for a s
 - pnpm-lock.yaml
 - Maven (pom.xml)
 - Gradle
+- Python (requirements.txt, setup.py, pyproject.toml)
 
 ## Environment variables
 
@@ -348,16 +381,22 @@ Permission to modify and redistribute is granted under the terms of the Apache 2
 
 ## Integration as library
 
-This project is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) and requires Node.js >= 16
+cdxgen is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) and could be imported and used with both deno and Node.js >= 16
 
 Minimal example:
 
+```ts
+import { createBom, submitBom } from "npm:@cyclonedx/cdxgen@^9.0.1";
+```
+
+See the [Deno Readme](./contrib/deno/README.md) for detailed instruction.
+
 ```javascript
 import { createBom, submitBom } from "@cyclonedx/cdxgen";
 // bomNSData would contain bomJson, bomXml
 const bomNSData = await createBom(filePath, options);
 // Submission to dependency track server
-const dbody = await submitBom(args, bomNSData.bomXml);
+const dbody = await submitBom(args, bomNSData.bomJson);
 ```
 
 ## Node.js >= 20 permission model

package/analyzer.js

@@ -36,7 +36,7 @@ const getAllFiles = (dir, extn, files, result, regex) => {
     if (IGNORE_FILE_PATTERN.test(files[i])) {
       continue;
     }
-    let file = join(dir, files[i]);
+    const file = join(dir, files[i]);
     if (statSync(file).isDirectory()) {
       // Ignore directories
       const dirName = basename(file);

package/bin/cdxgen.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { createBom, submitBom } from "../index.js";
+import { createBom, submitBom, validateBom } from "../index.js";
 import fs from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
@@ -9,8 +9,8 @@ import crypto from "crypto";
 import { start as _serverStart } from "../server.js";
 import { fileURLToPath } from "node:url";
 import globalAgent from "global-agent";
-import { table } from "table";
 import process from "node:process";
+import { printTable, printDependencyTree } from "../display.js";
 
 let url = import.meta.url;
 if (!url.startsWith("file://")) {
@@ -39,7 +39,7 @@ const args = yargs(hideBin(process.argv))
     alias: "p",
     type: "boolean",
     description:
-      "Print the SBoM as a table. Defaults to true if output file is not specified with -o"
+      "Print the SBoM as a table with tree. Defaults to true if output file is not specified with -o"
   })
   .option("resolve-class", {
     alias: "c",
@@ -107,6 +107,11 @@ const args = yargs(hideBin(process.argv))
     description:
       "Install dependencies automatically for some projects. Defaults to true but disabled for containers and oci scans. Use --no-install-deps to disable this feature."
   })
+  .option("validate", {
+    type: "boolean",
+    default: false,
+    description: "Validate the generated SBoM using json schema."
+  })
   .scriptName("cdxgen")
   .version()
   .help("h").argv;
@@ -130,7 +135,7 @@ if (process.env.GLOBAL_AGENT_HTTP_PROXY || process.env.HTTP_PROXY) {
   globalAgent.bootstrap();
 }
 
-let filePath = args._[0] || ".";
+const filePath = args._[0] || ".";
 if (!args.projectName) {
   if (filePath !== ".") {
     args.projectName = basename(filePath);
@@ -143,7 +148,7 @@ if (!args.projectName) {
  * projectType: python, nodejs, java, golang
  * multiProject: Boolean to indicate monorepo or multi-module projects
  */
-let options = {
+const options = {
   projectType: args.type,
   multiProject: args.recurse,
   output: args.output,
@@ -340,7 +345,12 @@ const checkPermissions = (filePath) => {
       console.log("Try running the command with -t <type> or -r argument");
     }
   }
-
+  // Perform automatic validation
+  if (args.validate) {
+    if (!validateBom(bomNSData.bomJson)) {
+      process.exit(1);
+    }
+  }
   // Automatically submit the bom data
   if (args.serverUrl && args.serverUrl != true && args.apiKey) {
     try {
@@ -352,23 +362,7 @@ const checkPermissions = (filePath) => {
   }
 
   if (args.print && bomNSData.bomJson && bomNSData.bomJson.components) {
-    const data = [["Group", "Name", "Version", "Scope"]];
-    for (let comp of bomNSData.bomJson.components) {
-      data.push([comp.group || "", comp.name, comp.version, comp.scope || ""]);
-    }
-    const config = {
-      header: {
-        alignment: "center",
-        content: "Software Bill-of-Materials\nGenerated by @cyclonedx/cdxgen"
-      }
-    };
-    console.log(table(data, config));
-    console.log(
-      "BOM includes",
-      bomNSData.bomJson.components.length,
-      "components and",
-      bomNSData.bomJson.dependencies.length,
-      "dependencies"
-    );
+    printDependencyTree(bomNSData.bomJson);
+    printTable(bomNSData.bomJson);
   }
 })();

package/binary.js

@@ -78,7 +78,7 @@ if (
 if (!CDXGEN_PLUGINS_DIR) {
   let globalNodePath = process.env.GLOBAL_NODE_MODULES_PATH || undefined;
   if (!globalNodePath) {
-    let result = spawnSync(
+    const result = spawnSync(
       isWin ? "npm.cmd" : "npm",
       ["root", "--quiet", "-g"],
       {
@@ -251,7 +251,7 @@ export const getGoBuildInfo = (src) => {
 
 export const getCargoAuditableInfo = (src) => {
   if (CARGO_AUDITABLE_BIN) {
-    let result = spawnSync(CARGO_AUDITABLE_BIN, [src], {
+    const result = spawnSync(CARGO_AUDITABLE_BIN, [src], {
       encoding: "utf-8"
     });
     if (result.status !== 0 || result.error) {
@@ -278,7 +278,7 @@ export const getOSPackages = (src) => {
     if (existsSync(src)) {
       imageType = "rootfs";
     }
-    let tempDir = mkdtempSync(join(tmpdir(), "trivy-cdxgen-"));
+    const tempDir = mkdtempSync(join(tmpdir(), "trivy-cdxgen-"));
     const bomJsonFile = join(tempDir, "trivy-bom.json");
     const args = [
       imageType,
@@ -299,7 +299,7 @@ export const getOSPackages = (src) => {
     if (DEBUG_MODE) {
       console.log("Executing", TRIVY_BIN, args.join(" "));
     }
-    let result = spawnSync(TRIVY_BIN, args, {
+    const result = spawnSync(TRIVY_BIN, args, {
       encoding: "utf-8"
     });
     if (result.status !== 0 || result.error) {
@@ -350,7 +350,7 @@ export const getOSPackages = (src) => {
             }
             // Fix the group
             let group = dirname(comp.name);
-            let name = basename(comp.name);
+            const name = basename(comp.name);
             let purlObj = undefined;
             let distro_codename = "";
             if (group === ".") {
@@ -461,7 +461,7 @@ export const getOSPackages = (src) => {
             pkgList.push(comp);
             // If there is a source package defined include it as well
             if (srcName && srcVersion && srcName !== comp.name) {
-              let newComp = Object.assign({}, comp);
+              const newComp = Object.assign({}, comp);
               newComp.name = srcName;
               newComp.version = srcVersion;
               if (purlObj) {
@@ -495,7 +495,7 @@ export const executeOsQuery = (query) => {
     if (DEBUG_MODE) {
       console.log("Execuing", OSQUERY_BIN, args.join(" "));
     }
-    let result = spawnSync(OSQUERY_BIN, args, {
+    const result = spawnSync(OSQUERY_BIN, args, {
       encoding: "utf-8"
     });
     if (result.status !== 0 || result.error) {