@cyclonedx/cdxgen 12.1.5 → 12.2.1

package/lib/helpers/formulationParsers.js

@@ -0,0 +1,351 @@
+import process from "node:process";
+
+import { v4 as uuidv4 } from "uuid";
+
+import { collectOSCryptoLibs } from "./cbomutils.js";
+import { azurePipelinesParser } from "./ciParsers/azurePipelines.js";
+import { circleCiParser } from "./ciParsers/circleCi.js";
+import { githubActionsParser } from "./ciParsers/githubActions.js";
+import { gitlabCiParser } from "./ciParsers/gitlabCi.js";
+import { jenkinsParser } from "./ciParsers/jenkins.js";
+import { trimComponents } from "./depsUtils.js";
+import {
+  collectEnvInfo,
+  getBranch,
+  getOriginUrl,
+  gitTreeHashes,
+  listFiles,
+} from "./envcontext.js";
+import { getAllFiles } from "./utils.js";
+
+/**
+ * The parser registry. Pre-populated with the five built-in CI system parsers.
+ *
+ * External parsers added via {@link registerParser} are appended here.
+ *
+ * Each entry must satisfy the FormulationParser contract:
+ * ```
+ * {
+ *   id:       string,                         // unique stable identifier
+ *   patterns: string[],                       // non-empty array of glob patterns for file discovery
+ *   parse(files: string[], options: Object):  // synchronous function
+ *     { workflows?, components?, services?, properties?, dependencies? }
+ * }
+ * ```
+ */
+const _parsers = [
+  githubActionsParser,
+  gitlabCiParser,
+  jenkinsParser,
+  circleCiParser,
+  azurePipelinesParser,
+];
+
+/**
+ * Register an external formulation parser.
+ *
+ * The parser is appended to the registry and will be invoked by
+ * {@link addFormulationSection} on the next call.
+ *
+ * @param {{ id: string, patterns: string[], parse: Function }} parser
+ */
+export function registerParser(parser) {
+  const hasValidPatterns =
+    Array.isArray(parser?.patterns) &&
+    parser.patterns.length > 0 &&
+    parser.patterns.every(
+      (pattern) => typeof pattern === "string" && pattern.trim().length > 0,
+    );
+  if (
+    typeof parser?.id !== "string" ||
+    parser.id.trim().length === 0 ||
+    !hasValidPatterns ||
+    typeof parser?.parse !== "function"
+  ) {
+    throw new TypeError(
+      "registerParser: parser must have id (string), patterns (non-empty string[]), and parse (function)",
+    );
+  }
+  _parsers.push(parser);
+}
+
+/**
+ * Return a shallow copy of the currently registered parsers.
+ *
+ * @returns {Array<{ id: string, patterns: string[], parse: Function }>}
+ */
+export function getParsers() {
+  return [..._parsers];
+}
+
+/**
+ * Environment-variable prefixes whose values are safe to include in the
+ * formulation section.  All other variables are ignored.
+ */
+const ENV_PREFIXES = [
+  "GIT_",
+  "ANDROID_",
+  "DENO_",
+  "DOTNET_",
+  "JAVA_",
+  "SDKMAN_",
+  "CARGO_",
+  "CONDA_",
+  "RUST",
+  "GEM_",
+  "SCALA_",
+  "MAVEN_",
+  "GRADLE_",
+];
+
+/**
+ * Sub-strings that, when found (case-insensitively) in the variable *name*
+ * or *value*, cause the variable to be excluded from the formulation section.
+ *
+ * This blocklist is intentionally conservative to avoid leaking secrets.
+ * Common CI tokens and credentials patterns are enumerated explicitly.
+ */
+const ENV_BLOCKLIST = [
+  "key",
+  "token",
+  "pass",
+  "secret",
+  "user",
+  "email",
+  "auth",
+  "session",
+  "proxy",
+  "cred",
+  "askpass",
+  "api_key",
+  "apikey",
+  "private",
+  "signature",
+  "webhook",
+];
+
+/**
+ * Build the formulation section for a CycloneDX BOM.
+ *
+ * This function is the top-level aggregator: it collects git metadata,
+ * invokes every registered CI parser, and merges the results into a single
+ * CycloneDX formulation entry.
+ *
+ * The function falls back to a minimal stub workflow when no CI config files
+ * are detected at the given path.
+ *
+ * @param {string} filePath         File path
+ * @param {Object} options          CLI options; `options.path` is used as the
+ *                                  project root for file discovery.
+ * @param {Object} [context={}]     Optional context object.  If it contains a
+ *                                  non-empty `formulationList` array those
+ *                                  components are merged into the result.
+ *
+ * @returns {{ formulation: Object[], dependencies: Object[] }}
+ *   `formulation` – array to be placed at `bomJson.formulation`
+ *   `dependencies` – dependency objects to be merged into
+ *                    `bomJson.dependencies` via `mergeDependencies`
+ */
+export function addFormulationSection(filePath, options, context = {}) {
+  const projectPath = filePath;
+  const formulation = [];
+  const dependencies = [];
+
+  // ── Git metadata ─────────────────────────────────────────────────────────
+  const gitBranch = getBranch(undefined, projectPath);
+  const originUrl = getOriginUrl(projectPath);
+  const gitFiles = listFiles(projectPath);
+  const treeHashes = gitTreeHashes(projectPath);
+
+  let components = [];
+
+  // Reuse any existing formulation components (e.g. from Pixi lock data)
+  // See: PR #1172
+  if (context?.formulationList?.length) {
+    components = components.concat(trimComponents(context.formulationList));
+  }
+
+  // OmniBOR / Artifact Dependency Graph components (spec 1.6+)
+  let parentOmniborId;
+  let treeOmniborId;
+  if (options.specVersion >= 1.6 && Object.keys(treeHashes).length === 2) {
+    // treeHashes.parent is the parent commit SHA → gitoid:commit:sha1:
+    // treeHashes.tree is the git tree object SHA → gitoid:tree:sha1:
+    parentOmniborId = `gitoid:commit:sha1:${treeHashes.parent}`;
+    treeOmniborId = `gitoid:tree:sha1:${treeHashes.tree}`;
+    components.push({
+      type: "file",
+      name: "git-parent",
+      description: "Git Parent Node.",
+      "bom-ref": parentOmniborId,
+      omniborId: [parentOmniborId],
+      swhid: [`swh:1:rev:${treeHashes.parent}`],
+    });
+    components.push({
+      type: "file",
+      name: "git-tree",
+      description: "Git Tree Node.",
+      "bom-ref": treeOmniborId,
+      omniborId: [treeOmniborId],
+      swhid: [`swh:1:dir:${treeHashes.tree}`],
+    });
+    // OmniBOR linkage goes into the top-level dependencies array
+    dependencies.push({ ref: parentOmniborId, provides: [treeOmniborId] });
+  }
+
+  // Git file list
+  if (gitBranch && gitFiles?.length) {
+    const gitFileComponents = gitFiles.map((f) =>
+      options.specVersion >= 1.6
+        ? {
+            type: "file",
+            name: f.name,
+            version: f.hash,
+            "bom-ref": f.omniborId,
+            omniborId: [f.omniborId],
+            swhid: [f.swhid],
+          }
+        : {
+            type: "file",
+            name: f.name,
+            version: f.hash,
+          },
+    );
+    components = components.concat(gitFileComponents);
+
+    // Complete the Artifact Dependency Graph: tree → blob links
+    if (options.specVersion >= 1.6 && treeOmniborId) {
+      dependencies.push({
+        ref: treeOmniborId,
+        provides: gitFiles.map((f) => f.omniborId).filter(Boolean),
+      });
+    }
+  }
+
+  // Build environment details (Java, .NET, Python, Node, GCC, Rust, Go, Ruby)
+  const infoComponents = collectEnvInfo(projectPath);
+  if (infoComponents?.length) {
+    components = components.concat(infoComponents);
+  }
+
+  // OS crypto libraries (cbom mode)
+  if (options.includeCrypto) {
+    const cryptoLibs = collectOSCryptoLibs(options);
+    if (cryptoLibs?.length) {
+      components = components.concat(cryptoLibs);
+    }
+  }
+
+  // ── CI parser dispatch ────────────────────────────────────────────────────
+  const ciWorkflows = [];
+  const ciComponents = [];
+  const ciServices = [];
+  const ciProperties = [];
+
+  const discoveryPath = projectPath || ".";
+
+  for (const parser of _parsers) {
+    const matchedFiles = [];
+    for (const pattern of parser.patterns) {
+      const found = getAllFiles(discoveryPath, pattern, options);
+      if (found?.length) {
+        matchedFiles.push(...found);
+      }
+    }
+    const uniqueMatchedFiles = [...new Set(matchedFiles)];
+    if (!uniqueMatchedFiles.length) {
+      continue;
+    }
+
+    let result;
+    try {
+      result = parser.parse(uniqueMatchedFiles, options);
+    } catch (err) {
+      // A broken parser must not kill SBOM generation
+      console.warn(
+        `[formulationParsers] Parser "${parser.id}" threw an error:`,
+        err.message,
+      );
+      continue;
+    }
+
+    if (result?.workflows?.length) {
+      ciWorkflows.push(...result.workflows);
+    }
+    if (result?.components?.length) {
+      ciComponents.push(...result.components);
+    }
+    if (result?.services?.length) {
+      ciServices.push(...result.services);
+    }
+    if (result?.properties?.length) {
+      ciProperties.push(...result.properties);
+    }
+    if (result?.dependencies?.length) {
+      dependencies.push(...result.dependencies);
+    }
+  }
+
+  // Merge CI components into the formulation component list
+  if (ciComponents.length) {
+    components = components.concat(ciComponents);
+  }
+
+  // ── Environment variables ─────────────────────────────────────────────────
+  let environmentVars = gitBranch?.length
+    ? [{ name: "GIT_BRANCH", value: gitBranch }]
+    : [];
+
+  for (const aevar of Object.keys(process.env)) {
+    const lower = aevar.toLowerCase();
+    const value = process.env[aevar] ?? "";
+    if (
+      ENV_PREFIXES.some((p) => aevar.startsWith(p)) &&
+      !ENV_BLOCKLIST.some((b) => lower.includes(b)) &&
+      !ENV_BLOCKLIST.some((b) => value.toLowerCase().includes(b)) &&
+      value.length
+    ) {
+      environmentVars.push({ name: aevar, value });
+    }
+  }
+
+  if (!environmentVars.length) {
+    environmentVars = undefined;
+  }
+
+  // ── Assemble formulation object ───────────────────────────────────────────
+  const aformulation = {
+    "bom-ref": uuidv4(),
+    components: trimComponents(components),
+  };
+
+  if (ciServices.length) {
+    aformulation.services = ciServices;
+  }
+
+  if (ciProperties.length) {
+    aformulation.properties = ciProperties;
+  }
+
+  // Use CI-detected workflows; fall back to a minimal stub when none found
+  if (ciWorkflows.length) {
+    aformulation.workflows = ciWorkflows;
+  } else {
+    let sourceInput;
+    if (environmentVars) {
+      sourceInput = { environmentVars };
+    }
+    const sourceWorkflow = {
+      "bom-ref": uuidv4(),
+      uid: uuidv4(),
+      taskTypes: originUrl ? ["build", "clone"] : ["build"],
+    };
+    if (sourceInput) {
+      sourceWorkflow.inputs = [sourceInput];
+    }
+    aformulation.workflows = [sourceWorkflow];
+  }
+
+  formulation.push(aformulation);
+  return { formulation, dependencies };
+}

package/lib/helpers/logger.js

@@ -44,6 +44,14 @@ const traceLogger = new Console({
 if (THINK_MODE) {
   thinkLogger.group(colorizeText("<think>"));
 }
+/**
+ * Logs a thought message to the think logger if THINK_MODE is enabled.
+ * Automatically appends a period to the message if it lacks terminal punctuation.
+ *
+ * @param {string} s The thought message to log
+ * @param {Object} [args] Optional additional arguments to log alongside the message
+ * @returns {void}
+ */
 export function thoughtLog(s, args) {
   if (!THINK_MODE) {
     return;
@@ -58,6 +66,12 @@ export function thoughtLog(s, args) {
     thinkLogger.log(colorizeText(`${s}`));
   }
 }
+/**
+ * Closes the think log group by emitting the closing `</think>` marker.
+ * Has no effect if THINK_MODE is not enabled.
+ *
+ * @returns {void}
+ */
 export function thoughtEnd() {
   if (THINK_MODE) {
     thinkLogger.groupEnd();

package/lib/helpers/protobom.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from "node:fs";
 
-import { cdx_15, cdx_16 } from "@appthreat/cdx-proto";
+import { cdx_16, cdx_17 } from "@appthreat/cdx-proto";
 import {
   fromBinary,
   fromJsonString,
@@ -32,10 +32,10 @@ const stringifyIfNeeded = (bomJson) => {
 export const writeBinary = (bomJson, binFile) => {
   if (bomJson && binFile) {
     let bomSchema;
-    if (+bomJson.specVersion === 1.6) {
-      bomSchema = cdx_16.BomSchema;
+    if (+bomJson.specVersion === 1.7) {
+      bomSchema = cdx_17.BomSchema;
     } else {
-      bomSchema = cdx_15.BomSchema;
+      bomSchema = cdx_16.BomSchema;
     }
     writeFileSync(
       binFile,
@@ -57,17 +57,17 @@ export const writeBinary = (bomJson, binFile) => {
  *
  * @param {string} binFile Binary file name
  * @param {boolean} asJson Convert to JSON
- * @param {number} specVersion Specification version. Defaults to 1.6
+ * @param {number} specVersion Specification version. Defaults to 1.7
  */
-export const readBinary = (binFile, asJson = true, specVersion = 1.6) => {
+export const readBinary = (binFile, asJson = true, specVersion = 1.7) => {
   if (!safeExistsSync(binFile)) {
     return undefined;
   }
   let bomSchema;
-  if (specVersion === 1.6) {
-    bomSchema = cdx_16.BomSchema;
+  if (specVersion === 1.7) {
+    bomSchema = cdx_17.BomSchema;
   } else {
-    bomSchema = cdx_15.BomSchema;
+    bomSchema = cdx_16.BomSchema;
   }
   const bomObject = fromBinary(bomSchema, readFileSync(binFile), {
     readUnknownFields: true,

package/lib/helpers/pythonutils.js

@@ -266,6 +266,15 @@ function _findCondaPythonPackage(condaMetaDir) {
   }
 }
 
+/**
+ * Determines the appropriate Python executable path from a virtual environment.
+ * Inspects the virtual environment metadata to detect the Python type (system,
+ * conda, pyenv, etc.) and returns the most specific executable found, falling
+ * back to the global `PYTHON_CMD` constant when no executable is detected.
+ *
+ * @param {string} env Path to the Python virtual environment directory
+ * @returns {string} Path to the Python executable or the fallback command name
+ */
 export function get_python_command_from_env(env) {
   const fallbackCmd = PYTHON_CMD;
   const meta = getVenvMetadata(env);

package/lib/helpers/remote/dependency-track.js

@@ -0,0 +1,84 @@
+import { Buffer } from "node:buffer";
+
+/**
+ * Returns the Dependency-Track BOM API URL.
+ *
+ * @param {string} serverUrl Dependency-Track server URL
+ * @returns {string} API URL to submit BOM payload
+ */
+export function getDependencyTrackBomUrl(serverUrl) {
+  return `${serverUrl.replace(/\/$/, "")}/api/v1/bom`;
+}
+
+/**
+ * Build the payload for Dependency-Track BOM submission.
+ *
+ * @param {Object} args CLI/server arguments
+ * @param {Object} bomContents BOM Json
+ * @returns {Object | undefined} payload object if project coordinates are valid
+ */
+export function buildDependencyTrackBomPayload(args, bomContents) {
+  let encodedBomContents = Buffer.from(JSON.stringify(bomContents)).toString(
+    "base64",
+  );
+  if (encodedBomContents.startsWith("77u/")) {
+    encodedBomContents = encodedBomContents.substring(4);
+  }
+  const autoCreate =
+    typeof args.autoCreate === "boolean"
+      ? args.autoCreate
+      : args.autoCreate !== "false";
+  const bomPayload = {
+    autoCreate: String(autoCreate),
+    bom: encodedBomContents,
+  };
+  if (
+    typeof args.projectId !== "undefined" ||
+    typeof args.projectName !== "undefined"
+  ) {
+    if (typeof args.projectId !== "undefined") {
+      bomPayload.project = args.projectId;
+    }
+    if (typeof args.projectName !== "undefined") {
+      bomPayload.projectName = args.projectName;
+    }
+    // Dependency-Track submissions use "main" as fallback when no version is provided.
+    bomPayload.projectVersion = args.projectVersion || "main";
+  } else {
+    return undefined;
+  }
+  const parentProjectId = args.parentProjectId || args.parentUUID;
+  const hasParentUuidMode = typeof parentProjectId !== "undefined";
+  const hasParentName = typeof args.parentProjectName !== "undefined";
+  const hasParentVersion = typeof args.parentProjectVersion !== "undefined";
+  const hasParentCoordsMode = hasParentName || hasParentVersion;
+  if (hasParentUuidMode && hasParentCoordsMode) {
+    return undefined;
+  }
+  if (!hasParentUuidMode && hasParentName !== hasParentVersion) {
+    return undefined;
+  }
+  if (hasParentUuidMode) {
+    bomPayload.parentUUID = parentProjectId;
+  }
+  if (hasParentName && hasParentVersion) {
+    bomPayload.parentName = args.parentProjectName;
+    bomPayload.parentVersion = args.parentProjectVersion;
+  }
+  if (
+    typeof args.isLatest === "boolean" ||
+    args.isLatest === "true" ||
+    args.isLatest === "false"
+  ) {
+    bomPayload.isLatest =
+      typeof args.isLatest === "boolean"
+        ? args.isLatest
+        : args.isLatest === "true";
+  }
+  if (typeof args.projectTag !== "undefined") {
+    bomPayload.projectTags = (
+      Array.isArray(args.projectTag) ? args.projectTag : [args.projectTag]
+    ).map((tag) => ({ name: tag }));
+  }
+  return bomPayload;
+}

package/lib/helpers/remote/dependency-track.poku.js

@@ -0,0 +1,119 @@
+import { assert, describe, it } from "poku";
+
+import {
+  buildDependencyTrackBomPayload,
+  getDependencyTrackBomUrl,
+} from "./dependency-track.js";
+
+describe("Dependency-Track helper tests", () => {
+  it("returns submission URL without trailing slash duplication", () => {
+    assert.strictEqual(
+      getDependencyTrackBomUrl("https://dtrack.example.com/"),
+      "https://dtrack.example.com/api/v1/bom",
+    );
+    assert.strictEqual(
+      getDependencyTrackBomUrl("https://dtrack.example.com"),
+      "https://dtrack.example.com/api/v1/bom",
+    );
+  });
+
+  it("builds payload with parentUUID and tags", () => {
+    const payload = buildDependencyTrackBomPayload(
+      {
+        projectName: "child",
+        projectVersion: "1.0.0",
+        parentProjectId: "d9628844-5f04-4ca7-88a2-64eb6bc64db0",
+        projectTag: ["tag1", "tag2"],
+      },
+      { bom: "test" },
+    );
+    assert.deepStrictEqual(payload, {
+      autoCreate: "true",
+      bom: "eyJib20iOiJ0ZXN0In0=",
+      parentUUID: "d9628844-5f04-4ca7-88a2-64eb6bc64db0",
+      projectName: "child",
+      projectTags: [{ name: "tag1" }, { name: "tag2" }],
+      projectVersion: "1.0.0",
+    });
+  });
+
+  it("builds payload with parentName and parentVersion", () => {
+    const payload = buildDependencyTrackBomPayload(
+      {
+        projectName: "child",
+        projectVersion: "1.0.0",
+        parentProjectName: "parent",
+        parentProjectVersion: "2.0.0",
+      },
+      { bom: "test2" },
+    );
+    assert.deepStrictEqual(payload, {
+      autoCreate: "true",
+      bom: "eyJib20iOiJ0ZXN0MiJ9",
+      parentName: "parent",
+      parentVersion: "2.0.0",
+      projectName: "child",
+      projectVersion: "1.0.0",
+    });
+  });
+
+  it("returns undefined when project identity is missing", () => {
+    const payload = buildDependencyTrackBomPayload({}, { bom: "test3" });
+    assert.strictEqual(payload, undefined);
+  });
+
+  it("supports configurable autoCreate and isLatest", () => {
+    const payload = buildDependencyTrackBomPayload(
+      {
+        autoCreate: false,
+        isLatest: true,
+        projectName: "child",
+      },
+      { bom: "test4" },
+    );
+    assert.deepStrictEqual(payload, {
+      autoCreate: "false",
+      bom: "eyJib20iOiJ0ZXN0NCJ9",
+      isLatest: true,
+      projectName: "child",
+      projectVersion: "main",
+    });
+  });
+
+  it("defaults projectVersion to main when only projectName is provided", () => {
+    const payload = buildDependencyTrackBomPayload(
+      { projectName: "child" },
+      { bom: "test5" },
+    );
+    assert.deepStrictEqual(payload, {
+      autoCreate: "true",
+      bom: "eyJib20iOiJ0ZXN0NSJ9",
+      projectName: "child",
+      projectVersion: "main",
+    });
+  });
+
+  it("returns undefined when parent UUID and parent name/version are both provided", () => {
+    const payload = buildDependencyTrackBomPayload(
+      {
+        parentProjectId: "d9628844-5f04-4ca7-88a2-64eb6bc64db0",
+        parentProjectName: "parent",
+        parentProjectVersion: "1.0.0",
+        projectName: "child",
+      },
+      { bom: "test6" },
+    );
+    assert.strictEqual(payload, undefined);
+  });
+
+  it("returns undefined when parent name/version mode is incomplete", () => {
+    const payload = buildDependencyTrackBomPayload(
+      {
+        parentProjectName: "parent",
+        projectName: "child",
+      },
+      { bom: "test7" },
+    );
+    assert.strictEqual(payload, undefined);
+  });
+});