@cyclonedx/cdxgen 12.1.5 → 12.2.0

package/lib/helpers/ciParsers/circleCi.js

@@ -0,0 +1,286 @@
+import { readFileSync } from "node:fs";
+
+import { v4 as uuidv4 } from "uuid";
+import { parse as _load } from "yaml";
+
+import { disambiguateSteps } from "./common.js";
+
+/**
+ * Parse a single CircleCI config file and return formulation-shaped data.
+ *
+ * @param {string} f Absolute path to the config file
+ * @param {Object} _options CLI options
+ * @returns {{ workflows: Object[], components: Object[], services: Object[], properties: Object[], dependencies: Object[] }}
+ */
+function parseCircleCiFile(f, _options) {
+  const workflows = [];
+  const components = [];
+  const dependencies = [];
+
+  let raw;
+  try {
+    raw = readFileSync(f, { encoding: "utf-8" });
+  } catch (_e) {
+    return {
+      workflows,
+      components,
+      services: [],
+      properties: [],
+      dependencies,
+    };
+  }
+
+  let yamlObj;
+  try {
+    yamlObj = _load(raw);
+  } catch (_e) {
+    return {
+      workflows,
+      components,
+      services: [],
+      properties: [],
+      dependencies,
+    };
+  }
+
+  if (!yamlObj || typeof yamlObj !== "object") {
+    return {
+      workflows,
+      components,
+      services: [],
+      properties: [],
+      dependencies,
+    };
+  }
+
+  // Collect orbs as components
+  if (yamlObj.orbs && typeof yamlObj.orbs === "object") {
+    for (const [orbAlias, orbRef] of Object.entries(yamlObj.orbs)) {
+      if (typeof orbRef === "string") {
+        const atIdx = orbRef.lastIndexOf("@");
+        const fullName = atIdx >= 0 ? orbRef.substring(0, atIdx) : orbRef;
+        const version = atIdx >= 0 ? orbRef.substring(atIdx + 1) : "";
+        const slashIdx = fullName.indexOf("/");
+        const namespace = slashIdx >= 0 ? fullName.substring(0, slashIdx) : "";
+        const name =
+          slashIdx >= 0 ? fullName.substring(slashIdx + 1) : fullName;
+        components.push({
+          "bom-ref": orbRef,
+          type: "application",
+          group: namespace,
+          name,
+          version,
+          properties: [
+            { name: "SrcFile", value: f },
+            { name: "cdx:circleci:orb:alias", value: orbAlias },
+          ],
+        });
+      }
+    }
+  }
+
+  // Collect executor images as components
+  if (yamlObj.executors && typeof yamlObj.executors === "object") {
+    for (const [exName, exDef] of Object.entries(yamlObj.executors)) {
+      const image =
+        exDef?.docker?.[0]?.image ||
+        exDef?.machine?.image ||
+        exDef?.macos?.xcode ||
+        "";
+      if (image) {
+        components.push({
+          type: "container",
+          name: image,
+          properties: [
+            { name: "SrcFile", value: f },
+            { name: "cdx:circleci:executor:name", value: exName },
+          ],
+        });
+      }
+    }
+  }
+
+  // Build a workflow/task tree per CircleCI workflow
+  const circleCiWorkflows =
+    yamlObj.workflows && typeof yamlObj.workflows === "object"
+      ? Object.entries(yamlObj.workflows).filter(([key]) => key !== "version")
+      : [];
+
+  for (const [wfName, wfDef] of circleCiWorkflows) {
+    if (!wfDef || typeof wfDef !== "object") {
+      continue;
+    }
+    const workflowRef = uuidv4();
+    const tasks = [];
+    const workflowDependsOn = [];
+
+    const wfJobs = Array.isArray(wfDef.jobs) ? wfDef.jobs : [];
+    for (const jobEntry of wfJobs) {
+      // Each entry is either a string (job name) or { jobName: { requires, ... } }
+      let jobName;
+      let jobConfig = {};
+      if (typeof jobEntry === "string") {
+        jobName = jobEntry;
+      } else if (typeof jobEntry === "object") {
+        jobName = Object.keys(jobEntry)[0];
+        jobConfig = jobEntry[jobName] || {};
+      }
+      if (!jobName) {
+        continue;
+      }
+
+      const taskRef = uuidv4();
+      const taskProperties = [
+        { name: "cdx:circleci:job:name", value: jobName },
+      ];
+
+      const requires = Array.isArray(jobConfig.requires)
+        ? jobConfig.requires
+        : [];
+      if (requires.length) {
+        taskProperties.push({
+          name: "cdx:circleci:job:requires",
+          value: requires.join(","),
+        });
+      }
+
+      const jobFilters = jobConfig.filters;
+      if (jobFilters?.branches) {
+        const only = Array.isArray(jobFilters.branches.only)
+          ? jobFilters.branches.only.join(",")
+          : jobFilters.branches.only || "";
+        if (only) {
+          taskProperties.push({
+            name: "cdx:circleci:job:branch:only",
+            value: only,
+          });
+        }
+      }
+
+      // Look up job definition for steps
+      const jobDef = yamlObj.jobs?.[jobName] || {};
+      const steps = [];
+      for (const step of Array.isArray(jobDef.steps) ? jobDef.steps : []) {
+        if (typeof step === "string") {
+          steps.push({ name: step });
+        } else if (typeof step === "object") {
+          const stepKey = Object.keys(step)[0];
+          const stepVal = step[stepKey];
+          const stepName =
+            typeof stepVal?.name === "string" ? stepVal.name : stepKey;
+          const command =
+            typeof stepVal?.command === "string" ? stepVal.command : undefined;
+          steps.push({
+            name: stepName,
+            commands: command ? [{ executed: command }] : undefined,
+          });
+        }
+      }
+
+      tasks.push({
+        "bom-ref": taskRef,
+        uid: taskRef,
+        name: jobName,
+        taskTypes: ["build"],
+        steps: disambiguateSteps(steps),
+        properties: taskProperties,
+      });
+      workflowDependsOn.push(taskRef);
+    }
+
+    const workflow = {
+      "bom-ref": workflowRef,
+      uid: workflowRef,
+      name: wfName,
+      taskTypes: ["build"],
+      tasks: tasks.length ? tasks : undefined,
+      properties: [
+        { name: "cdx:circleci:config", value: f },
+        { name: "cdx:circleci:workflow:name", value: wfName },
+      ],
+    };
+
+    workflows.push(workflow);
+    if (workflowDependsOn.length) {
+      dependencies.push({ ref: workflowRef, dependsOn: workflowDependsOn });
+    }
+  }
+
+  // Fallback: if no workflows block, create a single workflow from jobs
+  if (
+    workflows.length === 0 &&
+    yamlObj.jobs &&
+    typeof yamlObj.jobs === "object"
+  ) {
+    const workflowRef = uuidv4();
+    const tasks = [];
+    const workflowDependsOn = [];
+
+    for (const jobName of Object.keys(yamlObj.jobs)) {
+      const taskRef = uuidv4();
+      tasks.push({
+        "bom-ref": taskRef,
+        uid: taskRef,
+        name: jobName,
+        taskTypes: ["build"],
+        properties: [{ name: "cdx:circleci:job:name", value: jobName }],
+      });
+      workflowDependsOn.push(taskRef);
+    }
+
+    workflows.push({
+      "bom-ref": workflowRef,
+      uid: workflowRef,
+      name: "CircleCI Pipeline",
+      taskTypes: ["build"],
+      tasks: tasks.length ? tasks : undefined,
+      properties: [{ name: "cdx:circleci:config", value: f }],
+    });
+    if (workflowDependsOn.length) {
+      dependencies.push({ ref: workflowRef, dependsOn: workflowDependsOn });
+    }
+  }
+
+  return { workflows, components, services: [], properties: [], dependencies };
+}
+
+/**
+ * CircleCI formulation parser.
+ *
+ * Matches `.circleci/config.yml` and `.circleci/config.yaml` and converts them
+ * into CycloneDX formulation workflow objects. Referenced orbs are captured as
+ * components.
+ *
+ * Parser contract: `parse(files, options)` returns
+ * `{ workflows, components, services, properties, dependencies }`.
+ */
+export const circleCiParser = {
+  id: "circleci",
+  patterns: [".circleci/config.{yml,yaml}"],
+
+  /**
+   * @param {string[]} files Matched config file paths
+   * @param {Object} options CLI options
+   * @returns {{ workflows: Object[], components: Object[], services: Object[], properties: Object[], dependencies: Object[] }}
+   */
+  parse(files, options) {
+    const workflows = [];
+    const components = [];
+    const dependencies = [];
+
+    for (const f of files) {
+      const result = parseCircleCiFile(f, options);
+      workflows.push(...result.workflows);
+      components.push(...result.components);
+      dependencies.push(...result.dependencies);
+    }
+
+    return {
+      workflows,
+      components,
+      services: [],
+      properties: [],
+      dependencies,
+    };
+  },
+};

package/lib/helpers/ciParsers/circleCi.poku.js

@@ -0,0 +1,230 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { assert, describe, it } from "poku";
+
+import { circleCiParser } from "./circleCi.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, "../../..");
+
+describe("circleCiParser", () => {
+  it("has correct metadata", () => {
+    assert.strictEqual(circleCiParser.id, "circleci");
+    assert.ok(Array.isArray(circleCiParser.patterns));
+    assert.ok(circleCiParser.patterns.length > 0);
+    assert.strictEqual(typeof circleCiParser.parse, "function");
+  });
+
+  it("returns empty arrays for no files", () => {
+    const result = circleCiParser.parse([], {});
+    assert.deepStrictEqual(result.workflows, []);
+    assert.deepStrictEqual(result.components, []);
+    assert.deepStrictEqual(result.services, []);
+    assert.deepStrictEqual(result.properties, []);
+    assert.deepStrictEqual(result.dependencies, []);
+  });
+
+  it("parses the CircleCI fixture", () => {
+    const f = path.join(repoRoot, "test", "data", "circleci-config.yml");
+    const result = circleCiParser.parse([f], {});
+
+    assert.ok(Array.isArray(result.workflows));
+    assert.ok(result.workflows.length > 0, "expected at least one workflow");
+
+    // The fixture has one workflow named 'build-test-deploy'
+    const wf = result.workflows.find((w) => w.name === "build-test-deploy");
+    assert.ok(wf, "expected build-test-deploy workflow");
+    assert.ok(wf["bom-ref"]);
+    assert.ok(Array.isArray(wf.tasks));
+    assert.ok(wf.tasks.length > 0);
+
+    const taskNames = wf.tasks.map((t) => t.name);
+    assert.ok(taskNames.includes("build"), "expected build job");
+    assert.ok(taskNames.includes("test"), "expected test job");
+  });
+
+  it("captures orb references as components", () => {
+    const f = path.join(repoRoot, "test", "data", "circleci-config.yml");
+    const result = circleCiParser.parse([f], {});
+
+    // The fixture uses circleci/node and circleci/aws-ecr orbs
+    assert.ok(result.components.length > 0, "expected orb components");
+    const orbNames = result.components.map((c) => c.name);
+    assert.ok(orbNames.includes("node"), "expected circleci/node orb");
+    assert.ok(orbNames.includes("aws-ecr"), "expected circleci/aws-ecr orb");
+  });
+
+  it("captures executor images as components", () => {
+    const f = path.join(repoRoot, "test", "data", "circleci-config.yml");
+    const result = circleCiParser.parse([f], {});
+
+    const containerComps = result.components.filter(
+      (c) => c.type === "container",
+    );
+    assert.ok(
+      containerComps.length > 0,
+      "expected container executor components",
+    );
+    assert.ok(
+      containerComps.some((c) => c.name?.includes("node")),
+      "expected a node executor image component",
+    );
+  });
+
+  it("produces workflow dependency links", () => {
+    const f = path.join(repoRoot, "test", "data", "circleci-config.yml");
+    const result = circleCiParser.parse([f], {});
+
+    assert.ok(result.dependencies.length > 0);
+    const wfDep = result.dependencies.find(
+      (d) => d.ref === result.workflows[0]["bom-ref"],
+    );
+    assert.ok(wfDep);
+    assert.ok(wfDep.dependsOn.length > 0);
+  });
+
+  it("gracefully handles missing file", () => {
+    const result = circleCiParser.parse(["/no/such/.circleci/config.yml"], {});
+    assert.deepStrictEqual(result.workflows, []);
+    assert.deepStrictEqual(result.components, []);
+  });
+
+  it("parses circleci-machine.yml: machine executor components extracted", () => {
+    const f = path.join(repoRoot, "test", "data", "circleci-machine.yml");
+    const result = circleCiParser.parse([f], {});
+
+    // machine executors produce container components
+    const machineComps = result.components.filter(
+      (c) => c.type === "container" && c.name?.includes("ubuntu"),
+    );
+    assert.ok(
+      machineComps.length > 0,
+      "expected ubuntu machine executor components",
+    );
+  });
+
+  it("parses circleci-machine.yml: no orbs — orb components absent", () => {
+    const f = path.join(repoRoot, "test", "data", "circleci-machine.yml");
+    const result = circleCiParser.parse([f], {});
+    const orbComps = result.components.filter((c) => c.type === "application");
+    assert.strictEqual(orbComps.length, 0, "no orb components expected");
+  });
+
+  it("parses circleci-machine.yml: approval gate job present", () => {
+    const f = path.join(repoRoot, "test", "data", "circleci-machine.yml");
+    const result = circleCiParser.parse([f], {});
+
+    const wf = result.workflows.find((w) => w.name === "ci-cd");
+    assert.ok(wf, "expected ci-cd workflow");
+    const taskNames = wf.tasks.map((t) => t.name);
+    assert.ok(
+      taskNames.includes("hold-for-approval"),
+      "expected hold-for-approval task",
+    );
+    assert.ok(
+      taskNames.includes("deploy-staging"),
+      "expected deploy-staging task",
+    );
+    assert.ok(
+      taskNames.includes("deploy-production"),
+      "expected deploy-production task",
+    );
+  });
+
+  it("parses circleci-machine.yml: requires chain recorded in task properties", () => {
+    const f = path.join(repoRoot, "test", "data", "circleci-machine.yml");
+    const result = circleCiParser.parse([f], {});
+
+    const wf = result.workflows[0];
+    const approvalTask = wf.tasks.find((t) => t.name === "hold-for-approval");
+    assert.ok(approvalTask, "hold-for-approval task must exist");
+    const requiresProp = approvalTask.properties.find(
+      (p) => p.name === "cdx:circleci:job:requires",
+    );
+    assert.ok(requiresProp, "expected cdx:circleci:job:requires property");
+    assert.ok(
+      requiresProp.value.includes("integration-test"),
+      "requires must include integration-test",
+    );
+    assert.ok(
+      requiresProp.value.includes("security-scan"),
+      "requires must include security-scan",
+    );
+  });
+
+  it("parses circleci-docker-sidecar.yml: multiple workflows extracted", () => {
+    const f = path.join(
+      repoRoot,
+      "test",
+      "data",
+      "circleci-docker-sidecar.yml",
+    );
+    const result = circleCiParser.parse([f], {});
+
+    const wfNames = result.workflows.map((w) => w.name);
+    assert.ok(wfNames.includes("test-matrix"), "expected test-matrix workflow");
+    assert.ok(
+      wfNames.includes("scheduled-tests"),
+      "expected scheduled-tests workflow",
+    );
+  });
+
+  it("parses circleci-docker-sidecar.yml: sidecar containers as executor components", () => {
+    const f = path.join(
+      repoRoot,
+      "test",
+      "data",
+      "circleci-docker-sidecar.yml",
+    );
+    const result = circleCiParser.parse([f], {});
+
+    // The app-with-db executor has cimg/python as first image
+    const pythonComp = result.components.find(
+      (c) => c.type === "container" && c.name?.includes("python"),
+    );
+    assert.ok(pythonComp, "expected Python executor image component");
+
+    // The app-with-mongo executor has cimg/node:20.0 as primary image
+    const nodeComp = result.components.find(
+      (c) => c.type === "container" && c.name?.includes("node"),
+    );
+    assert.ok(nodeComp, "expected Node.js executor image component");
+  });
+
+  it("parses circleci-docker-sidecar.yml: Slack orb captured as component", () => {
+    const f = path.join(
+      repoRoot,
+      "test",
+      "data",
+      "circleci-docker-sidecar.yml",
+    );
+    const result = circleCiParser.parse([f], {});
+
+    const orbComps = result.components.filter((c) => c.type === "application");
+    assert.ok(
+      orbComps.length > 0,
+      "expected at least one circleci orb component",
+    );
+    assert.ok(
+      orbComps.some((c) => c.name === "slack"),
+      "expected circleci/slack orb component",
+    );
+    assert.ok(
+      orbComps.some((c) => c.version === "4.12.5"),
+      "expected slack orb version 4.12.5",
+    );
+  });
+
+  it("parses multiple CircleCI files: two files produce combined results", () => {
+    const f1 = path.join(repoRoot, "test", "data", "circleci-config.yml");
+    const f2 = path.join(repoRoot, "test", "data", "circleci-machine.yml");
+    const result = circleCiParser.parse([f1, f2], {});
+    // f1 has 1 workflow, f2 has 1 workflow → combined 2
+    assert.strictEqual(
+      result.workflows.length,
+      2,
+      "expected workflows from both files",
+    );
+  });
+});

package/lib/helpers/ciParsers/common.js

@@ -0,0 +1,24 @@
+/**
+ * Ensure all step objects in the array are unique (CycloneDX `uniqueItems: true`).
+ *
+ * Identical steps are disambiguated by appending a ` (N)` counter to the step name.
+ * The first occurrence is always left unchanged.
+ *
+ * @param {Object[]} steps
+ * @returns {Object[]|undefined}
+ */
+export function disambiguateSteps(steps) {
+  if (!steps?.length) {
+    return undefined;
+  }
+  const seenKeys = new Map();
+  return steps.map((step) => {
+    const key = JSON.stringify(step);
+    const count = seenKeys.get(key) ?? 0;
+    seenKeys.set(key, count + 1);
+    if (count === 0) {
+      return step;
+    }
+    return { ...step, name: `${step.name} (${count + 1})` };
+  });
+}