@cdxgen/cdxgen 0.0.1 → 13.0.0

package/lib/inventory/ciParsers/gitlabCi.js

@@ -0,0 +1,213 @@
+import { randomUUID as uuidv4 } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+import { parse as _load } from "yaml";
+
+import { disambiguateSteps } from "./common.js";
+
+/**
+ * Parse a single .gitlab-ci.yml file and return formulation-shaped data.
+ *
+ * @param {string} f Absolute path to the YAML file
+ * @param {Object} _options CLI options
+ * @returns {{ workflows: Object[], components: Object[], services: Object[], properties: Object[], dependencies: Object[] }}
+ */
+function parseGitlabCiFile(f, _options) {
+  const workflows = [];
+  const components = [];
+  const services = [];
+  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 };
+  }
+
+  // Top-level reserved keys that are not job names
+  const RESERVED_KEYS = new Set([
+    "image",
+    "services",
+    "stages",
+    "types",
+    "before_script",
+    "after_script",
+    "variables",
+    "cache",
+    "include",
+    "workflow",
+    "default",
+    "pages",
+    ".pre",
+    ".post",
+  ]);
+
+  const globalImage = yamlObj.image?.name || yamlObj.image || "";
+  const stages = Array.isArray(yamlObj.stages) ? yamlObj.stages : [];
+
+  // Collect global services as CycloneDX service objects
+  const globalServices = Array.isArray(yamlObj.services)
+    ? yamlObj.services
+    : [];
+  for (const svc of globalServices) {
+    const svcName = typeof svc === "string" ? svc : svc?.name || "";
+    if (svcName) {
+      services.push({ name: svcName });
+    }
+  }
+
+  const tasks = [];
+  const workflowRef = uuidv4();
+  const workflowDependsOn = [];
+
+  for (const key of Object.keys(yamlObj)) {
+    if (RESERVED_KEYS.has(key) || key.startsWith(".")) {
+      continue;
+    }
+    const job = yamlObj[key];
+    if (!job || typeof job !== "object" || Array.isArray(job)) {
+      continue;
+    }
+
+    const jobRef = uuidv4();
+    const steps = [];
+    const jobProperties = [{ name: "cdx:gitlab:job:name", value: key }];
+
+    const jobStage = job.stage || "test";
+    jobProperties.push({ name: "cdx:gitlab:job:stage", value: jobStage });
+
+    const jobImage = job.image?.name || job.image || globalImage;
+    if (jobImage) {
+      jobProperties.push({ name: "cdx:gitlab:job:image", value: jobImage });
+      components.push({ type: "container", name: jobImage });
+    }
+
+    const jobEnv = job.environment?.name || job.environment || "";
+    if (jobEnv) {
+      jobProperties.push({ name: "cdx:gitlab:job:environment", value: jobEnv });
+    }
+
+    // Collect job-level services
+    const jobServices = Array.isArray(job.services) ? job.services : [];
+    for (const svc of jobServices) {
+      const svcName = typeof svc === "string" ? svc : svc?.name || "";
+      if (svcName) {
+        services.push({ name: svcName });
+      }
+    }
+    if (jobServices.length) {
+      jobProperties.push({
+        name: "cdx:gitlab:job:services",
+        value: jobServices
+          .map((s) => (typeof s === "string" ? s : s?.name || ""))
+          .join(","),
+      });
+    }
+
+    const jobNeeds = Array.isArray(job.needs) ? job.needs : [];
+    if (jobNeeds.length) {
+      const jobNeedNames = jobNeeds
+        .map((need) => (typeof need === "string" ? need : need?.job || ""))
+        .filter(Boolean);
+      if (jobNeedNames.length) {
+        jobProperties.push({
+          name: "cdx:gitlab:job:needs",
+          value: jobNeedNames.join(","),
+        });
+      }
+    }
+
+    // before_script
+    for (const cmd of Array.isArray(job.before_script)
+      ? job.before_script
+      : []) {
+      steps.push({ name: "before_script", commands: [{ executed: cmd }] });
+    }
+    // script (main)
+    for (const cmd of Array.isArray(job.script) ? job.script : []) {
+      steps.push({ name: "script", commands: [{ executed: cmd }] });
+    }
+    // after_script
+    for (const cmd of Array.isArray(job.after_script) ? job.after_script : []) {
+      steps.push({ name: "after_script", commands: [{ executed: cmd }] });
+    }
+
+    tasks.push({
+      "bom-ref": jobRef,
+      uid: jobRef,
+      name: key,
+      taskTypes: ["build"],
+      steps: disambiguateSteps(steps),
+      properties: jobProperties,
+    });
+    workflowDependsOn.push(jobRef);
+  }
+
+  const stagesProperty = stages.length
+    ? [{ name: "cdx:gitlab:stages", value: stages.join(",") }]
+    : [];
+
+  const workflow = {
+    "bom-ref": workflowRef,
+    uid: workflowRef,
+    name: "GitLab CI Pipeline",
+    taskTypes: ["build"],
+    tasks: tasks.length ? tasks : undefined,
+    properties: [{ name: "cdx:gitlab:config", value: f }, ...stagesProperty],
+  };
+
+  workflows.push(workflow);
+  if (workflowDependsOn.length) {
+    dependencies.push({ ref: workflowRef, dependsOn: workflowDependsOn });
+  }
+
+  return { workflows, components, services, properties: [], dependencies };
+}
+
+/**
+ * GitLab CI formulation parser.
+ *
+ * Matches `.gitlab-ci.yml` files and converts them into CycloneDX formulation
+ * workflow objects. Each GitLab job becomes a task; script lines become steps.
+ *
+ * Parser contract: `parse(files, options)` returns
+ * `{ workflows, components, services, properties, dependencies }`.
+ */
+export const gitlabCiParser = {
+  id: "gitlab-ci",
+  patterns: ["**/.gitlab-ci.yml", ".gitlab-ci.yml"],
+
+  /**
+   * @param {string[]} files Matched CI 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 services = [];
+    const dependencies = [];
+
+    for (const f of files) {
+      const result = parseGitlabCiFile(f, options);
+      workflows.push(...result.workflows);
+      components.push(...result.components);
+      services.push(...result.services);
+      dependencies.push(...result.dependencies);
+    }
+
+    return { workflows, components, services, properties: [], dependencies };
+  },
+};

package/lib/inventory/ciParsers/jenkins.js

@@ -0,0 +1,180 @@
+import { randomUUID as uuidv4 } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+import { disambiguateSteps } from "./common.js";
+
+/**
+ * Very lightweight declarative Jenkinsfile parser using regex heuristics.
+ *
+ * Only parses the declarative pipeline syntax (`pipeline { ... }`).
+ * Full Groovy/scripted pipelines are not supported.
+ *
+ * @param {string} f Path to Jenkinsfile
+ * @param {Object} _options CLI options
+ * @returns {{ workflows: Object[], components: Object[], services: Object[], properties: Object[], dependencies: Object[] }}
+ */
+function parseJenkinsfile(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,
+    };
+  }
+
+  // Quick check: must look like a declarative pipeline
+  if (!raw.includes("pipeline") || !raw.includes("stages")) {
+    return {
+      workflows,
+      components,
+      services: [],
+      properties: [],
+      dependencies,
+    };
+  }
+
+  const workflowRef = uuidv4();
+  const tasks = [];
+  const workflowDependsOn = [];
+  const workflowProperties = [{ name: "cdx:jenkins:file", value: f }];
+
+  // Extract agent info
+  const agentMatch = raw.match(
+    /agent\s*\{[^}]*docker\s*\{[^}]*image\s+['"]([^'"]+)['"]/s,
+  );
+  if (agentMatch) {
+    const agentImage = agentMatch[1];
+    components.push({ type: "container", name: agentImage });
+    workflowProperties.push({
+      name: "cdx:jenkins:agent:image",
+      value: agentImage,
+    });
+  } else {
+    const simpleAgentMatch = raw.match(/agent\s+['"]?(\w+)['"]?/);
+    if (simpleAgentMatch) {
+      workflowProperties.push({
+        name: "cdx:jenkins:agent",
+        value: simpleAgentMatch[1],
+      });
+    }
+  }
+
+  // Extract stage blocks using a regex heuristic.
+  // NOTE: This only works reliably for declarative pipelines with simple,
+  // non-deeply-nested stage blocks. Scripted pipelines or stages with heavily
+  // nested closures may produce incomplete or incorrect results.
+  const stagePattern =
+    /stage\s*\(\s*['"]([^'"]+)['"]\s*\)\s*\{([\s\S]*?)(?=stage\s*\(|post\s*\{|$)/g;
+  let stageMatch;
+  while ((stageMatch = stagePattern.exec(raw)) !== null) {
+    const stageName = stageMatch[1];
+    const stageBody = stageMatch[2];
+    const taskRef = uuidv4();
+    const steps = [];
+    const taskProperties = [
+      { name: "cdx:jenkins:stage:name", value: stageName },
+    ];
+
+    // Detect parallel stages
+    if (stageBody.includes("parallel")) {
+      taskProperties.push({
+        name: "cdx:jenkins:stage:parallel",
+        value: "true",
+      });
+    }
+
+    // Detect when conditions
+    const whenMatch = stageBody.match(/when\s*\{([^}]+)\}/);
+    if (whenMatch) {
+      taskProperties.push({
+        name: "cdx:jenkins:stage:when",
+        value: whenMatch[1].trim(),
+      });
+    }
+
+    // Extract sh/echo/script steps
+    const shPattern = /(?:sh|bat|powershell)\s+['"]([^'"]+)['"]/g;
+    let shMatch;
+    while ((shMatch = shPattern.exec(stageBody)) !== null) {
+      steps.push({
+        name: `sh: ${shMatch[1].substring(0, 60)}`,
+        commands: [{ executed: shMatch[1] }],
+      });
+    }
+
+    tasks.push({
+      "bom-ref": taskRef,
+      uid: taskRef,
+      name: stageName,
+      taskTypes: ["build"],
+      steps: disambiguateSteps(steps),
+      properties: taskProperties,
+    });
+    workflowDependsOn.push(taskRef);
+  }
+
+  const workflow = {
+    "bom-ref": workflowRef,
+    uid: workflowRef,
+    name: "Jenkinsfile Pipeline",
+    taskTypes: ["build"],
+    tasks: tasks.length ? tasks : undefined,
+    properties: workflowProperties,
+  };
+
+  workflows.push(workflow);
+  if (workflowDependsOn.length) {
+    dependencies.push({ ref: workflowRef, dependsOn: workflowDependsOn });
+  }
+
+  return { workflows, components, services: [], properties: [], dependencies };
+}
+
+/**
+ * Jenkins formulation parser.
+ *
+ * Matches `Jenkinsfile` and `Jenkinsfile.*` at any directory depth and converts
+ * declarative pipeline syntax into CycloneDX formulation workflow objects.
+ *
+ * Parser contract: `parse(files, options)` returns
+ * `{ workflows, components, services, properties, dependencies }`.
+ */
+export const jenkinsParser = {
+  id: "jenkins",
+  patterns: ["**/Jenkinsfile", "**/Jenkinsfile.*"],
+
+  /**
+   * @param {string[]} files Matched Jenkinsfile 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 = parseJenkinsfile(f, options);
+      workflows.push(...result.workflows);
+      components.push(...result.components);
+      dependencies.push(...result.dependencies);
+    }
+
+    return {
+      workflows,
+      components,
+      services: [],
+      properties: [],
+      dependencies,
+    };
+  },
+};

package/lib/inventory/citations.js

@@ -0,0 +1,234 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { dirNameStr } from "../core/paths.js";
+
+// CycloneDX 1.7 introduced a root-level `citations` array. A citation records
+// which entity or process supplied a given piece of BOM data, and points at the
+// field(s) it vouches for via JSON Pointer(s) or JSONPath expression(s).
+//
+// Schema constraints (data/bom-1.7.schema.json#/definitions/citation):
+//   - `timestamp` is required.
+//   - Exactly one of `pointers` or `expressions` must be present (oneOf).
+//   - At least one of `attributedTo` or `process` must be present (anyOf).
+//   - `attributedTo` / `process` hold the `bom-ref` of an object already present
+//     in the BOM (a component, service, tool, organisational entity or person,
+//     or a formulation process).
+//
+// Because `attributedTo`/`process` reference other BOM entries by bom-ref, a
+// citation is never self-contained: it must be emitted alongside the entity it
+// names. The helpers below preserve that linkage and never invent refs.
+
+const CDXGEN_VERSION_JSON = JSON.parse(
+  readFileSync(join(dirNameStr, "package.json"), "utf-8"),
+);
+
+/**
+ * Build a schema-valid CycloneDX 1.7 citation object.
+ *
+ * Either `pointers` or `expressions` must be supplied (mutually exclusive), and
+ * either `attributedTo` or `process` must be supplied. The caller is expected to
+ * pass the bom-ref of an entity that actually exists in the BOM; this helper
+ * does not fabricate refs.
+ *
+ * @param {Object} input Citation fields
+ * @param {string[]} [input.pointers] JSON Pointer strings (RFC 6901) targeting the attributed fields
+ * @param {string[]} [input.expressions] JSONPath strings (RFC 9535) targeting the attributed fields
+ * @param {string} [input.attributedTo] bom-ref of the component/service/tool/entity that supplied the data
+ * @param {string} [input.process] bom-ref of a formulation process that produced the data
+ * @param {string} [input.bomRef] Optional bom-ref for the citation itself
+ * @param {string} [input.note] Free-form context or quality note
+ * @param {string} [input.timestamp] ISO-8601 timestamp; defaults to now. Pass
+ *   `citationTimestamp(bomJson)` so repeated renders of one BOM agree.
+ * @returns {Object|null} A citation object, or null when the required oneOf/anyOf pairs are not satisfied
+ */
+export function createCitation({
+  pointers,
+  expressions,
+  attributedTo,
+  process,
+  bomRef,
+  note,
+  timestamp,
+} = {}) {
+  const hasPointers = Array.isArray(pointers) && pointers.length > 0;
+  const hasExpressions = Array.isArray(expressions) && expressions.length > 0;
+  // oneOf: exactly one targeting mechanism.
+  if (hasPointers === hasExpressions) {
+    return null;
+  }
+  // anyOf: at least one attribution target.
+  if (!attributedTo && !process) {
+    return null;
+  }
+  // A citation left without a timestamp is completed by `attachCitations` from
+  // the document's own metadata.timestamp, so two renders of one BOM agree.
+  const citation = timestamp ? { timestamp } : {};
+  if (hasPointers) {
+    citation.pointers = [...pointers];
+  } else {
+    citation.expressions = [...expressions];
+  }
+  if (attributedTo) {
+    citation.attributedTo = attributedTo;
+  }
+  if (process) {
+    citation.process = process;
+  }
+  if (bomRef) {
+    citation["bom-ref"] = bomRef;
+  }
+  if (note) {
+    citation.note = note;
+  }
+  return citation;
+}
+
+/**
+ * Compute a stable identity for a citation so duplicate attributions can be
+ * merged without producing near-identical entries. Two citations are considered
+ * equivalent when they attribute the same target (entity/process) to the same
+ * field selector(s).
+ *
+ * @param {Object} citation A citation object
+ * @returns {string} Identity key
+ */
+function citationIdentity(citation) {
+  const target = citation.attributedTo || citation.process || "";
+  const selectors = (citation.pointers || citation.expressions || []).join(
+    "\n",
+  );
+  return `${target}\u0000${selectors}`;
+}
+
+/**
+ * Merge two citation arrays, dropping exact duplicates. When two citations share
+ * an identity but differ in note/bom-ref, the first one wins and the second is
+ * discarded to keep the array small and stable.
+ *
+ * @param {Object[]} existing Citations already present on the BOM
+ * @param {Object[]} additions Citations produced by a collector
+ * @returns {Object[]} De-duplicated citation array
+ */
+export function mergeCitations(existing = [], additions = []) {
+  const seen = new Set();
+  const merged = [];
+  for (const citation of [...(existing || []), ...(additions || [])]) {
+    if (!citation || typeof citation !== "object") {
+      continue;
+    }
+    const key = citation["bom-ref"] || citationIdentity(citation);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    merged.push(citation);
+  }
+  return merged;
+}
+
+/**
+ * Collect the bom-refs of all tool components recorded under metadata.tools.
+ * Tool components are the natural attribution target for data that cdxgen
+ * itself produced or resolved.
+ *
+ * @param {Object} bomJson CycloneDX BOM
+ * @returns {string[]} bom-ref strings, in document order
+ */
+export function collectToolBomRefs(bomJson) {
+  const refs = [];
+  const tools = bomJson?.metadata?.tools;
+  const pushComponent = (component) => {
+    if (component?.["bom-ref"]) {
+      refs.push(component["bom-ref"]);
+    }
+  };
+  if (Array.isArray(tools)) {
+    tools.forEach(pushComponent);
+  } else if (tools && Array.isArray(tools.components)) {
+    tools.components.forEach(pushComponent);
+  }
+  return refs;
+}
+
+/**
+ * Resolve the bom-ref of the cdxgen tool component, if present. This is the
+ * canonical attribution target for inventory that cdxgen collected itself.
+ *
+ * @param {Object} bomJson CycloneDX BOM
+ * @returns {string|undefined} bom-ref of the cdxgen tool, or undefined
+ */
+export function findCdxgenToolBomRef(bomJson) {
+  const refs = collectToolBomRefs(bomJson);
+  return refs.find((ref) => ref.includes("cdxgen"));
+}
+
+/**
+ * The timestamp every citation on a document shares. Deriving it from the
+ * document rather than the clock keeps two renders of one BOM identical, the
+ * same rule the annotator follows.
+ *
+ * @param {Object} bomJson CycloneDX BOM
+ * @returns {string} ISO-8601 timestamp
+ */
+export function citationTimestamp(bomJson) {
+  return bomJson?.metadata?.timestamp || new Date().toISOString();
+}
+
+/**
+ * Attach a citations array to the BOM root, but only when the spec version can
+ * carry it. At 1.6 and below the field is not allowed and the downgrade path
+ * strips it; this guard keeps callers from emitting data that would immediately
+ * be removed.
+ *
+ * @param {Object} bomJson CycloneDX BOM (mutated)
+ * @param {Object[]} citations Citations to attach
+ * @param {Object} options CLI options (for specVersion)
+ * @returns {Object} The mutated BOM
+ */
+export function attachCitations(bomJson, citations, options = {}) {
+  if (!bomJson) {
+    return bomJson;
+  }
+  const specVersion = options.specVersion || bomJson.specVersion;
+  if (!specVersion || Number(specVersion) < 1.7) {
+    return bomJson;
+  }
+  const documentTimestamp = citationTimestamp(bomJson);
+  for (const citation of citations || []) {
+    if (citation && !citation.timestamp) {
+      citation.timestamp = documentTimestamp;
+    }
+  }
+  const merged = mergeCitations(bomJson.citations, citations);
+  if (merged.length) {
+    bomJson.citations = merged;
+  } else {
+    delete bomJson.citations;
+  }
+  return bomJson;
+}
+
+/**
+ * Build a citation that attributes the BOM's component inventory to the cdxgen
+ * tool. This is the baseline provenance statement: cdxgen collected the
+ * components, so the inventory is attributed to cdxgen's tool component.
+ *
+ * @param {Object} bomJson CycloneDX BOM (read for the tool bom-ref)
+ * @param {Object} [context] Extra context
+ * @param {string} [context.note] Optional note appended to the attribution
+ * @returns {Object|null} A citation, or null when no cdxgen tool is referenced
+ */
+export function buildInventoryCitation(bomJson, context = {}) {
+  const attributedTo = findCdxgenToolBomRef(bomJson);
+  if (!attributedTo) {
+    return null;
+  }
+  return createCitation({
+    expressions: ["$.components"],
+    attributedTo,
+    note:
+      context.note ||
+      `Component inventory collected by cdxgen ${CDXGEN_VERSION_JSON.version}.`,
+  });
+}