@cdxgen/cdxgen 13.5.0 → 13.7.0

package/lib/inventory/cyclonedx20.js

@@ -0,0 +1,152 @@
+/**
+ * CycloneDX 2.0 rendering and reading.
+ *
+ * cdxgen assembles every BOM in the CycloneDX 1.x shape and converts to the
+ * requested spec version at the end of the pipeline (see
+ * lib/stages/postgen/specVersionCompat.js). The 2.0 draft is a structural
+ * rewrite rather than an additive change, so the conversion lives here, as two
+ * pure functions plus small helpers, instead of inside the compat walker:
+ *
+ * - `renderCycloneDx20(internalBom, context)` turns the 1.x-shaped internal
+ *   model into a 2.0 document. It never mutates its input, and its output
+ *   depends only on the model and the optional context (the cdx-hbom
+ *   hardware mapper, see hbomLoader.js: hardwareRenderContext).
+ *   `renderCycloneDx20WithReport(internalBom, context)` does the same and
+ *   also returns the counts of everything the render could not carry.
+ * - `readCycloneDx20(bom20)` turns a 2.0 document into the internal 1.x-shaped
+ *   model, reporting everything it could not carry in `losses`.
+ * - `loadBomForAnalysis(bomJson)` is the single entry point every BOM reader
+ *   uses; it returns the document as is for 1.x and calls readCycloneDx20 for
+ *   2.0, so no reader learns the 2.0 shape.
+ * - `getInternalBom(bomNSData)` and `refreshRenderedBom(bomNSData, options)`
+ *   are the generation-side half: postProcess keeps the 1.x model on
+ *   `bomNSData.internalBomJson` at 2.0, and the writer re-renders once after
+ *   the last mutation.
+ *
+ * Every field name below is quoted from the pinned draft schema
+ * (data/cyclonedx-2.0-bundled.schema.json, CycloneDX/specification 2.0-dev at
+ * ea8c3605829d1da13339a0790b6da73548e42a6b); citations give the `$defs` path.
+ */
+
+import { thoughtLog } from "../core/logger.js";
+import { isCycloneDx20SpecVersion } from "./bomUtils.js";
+import { isObjectRecord } from "./cyclonedx20Common.js";
+import { readCycloneDx20 } from "./cyclonedx20Read.js";
+import { isMarkedInternalModel } from "./cyclonedx20ReadContext.js";
+import { renderCycloneDx20 } from "./cyclonedx20Render.js";
+import { CDX20_INTERNAL_SECTIONS_KEY } from "./cyclonedx20Tables.js";
+
+export { readCycloneDx20 } from "./cyclonedx20Read.js";
+export {
+  renderCycloneDx20,
+  renderCycloneDx20WithReport,
+} from "./cyclonedx20Render.js";
+export {
+  CDX20_INTERNAL_SECTIONS_KEY,
+  CDXGEN_PARTY_REF_ID,
+  DEPENDENCY_TRACK_CDX20_ERROR,
+} from "./cyclonedx20Tables.js";
+
+/**
+ * Load any CycloneDX BOM for analysis: the document as is for 1.x, the
+ * internal 1.x-shaped model for 2.0.
+ *
+ * A document whose specVersion is 2.0 or later, or which has a specFormat, is
+ * read as 2.0, and the reader reports stray 1.x members such as
+ * `components` as losses. A model the 2.0 reader or the 2.0 compatibility
+ * pass produced carries the internal model mark (markInternalModel) and is
+ * returned as is; cdxgen hands that model to the evidence analysis in memory
+ * (evinse's `inputBomJson`), because the mark does not survive JSON. The
+ * internal sections key is never trusted on a 1.x document: the returned
+ * copy leaves it out, so it cannot reach a 2.0 render.
+ *
+ * @param {object} bomJson Parsed CycloneDX BOM
+ * @returns {{internalBom: object, specVersion: string, losses: Array<{pointer: string, reason: string}>}}
+ * @throws {Error} With a short message when the 2.0 reader fails on the
+ *   document
+ */
+export function loadBomForAnalysis(bomJson) {
+  if (!isObjectRecord(bomJson)) {
+    return { internalBom: bomJson, specVersion: "1.5", losses: [] };
+  }
+  const specVersion = `${bomJson.specVersion ?? ""}`.trim() || "1.5";
+  if (isMarkedInternalModel(bomJson)) {
+    return { internalBom: bomJson, specVersion, losses: [] };
+  }
+  if (
+    isCycloneDx20SpecVersion(specVersion) ||
+    bomJson.specFormat !== undefined
+  ) {
+    let read;
+    try {
+      read = readCycloneDx20(bomJson);
+    } catch (err) {
+      throw new Error(
+        `Unable to read the CycloneDX 2.0 document: ${err?.message || err}`,
+        { cause: err },
+      );
+    }
+    return {
+      internalBom: read.internalBom,
+      specVersion: "2.0",
+      losses: read.losses,
+    };
+  }
+  if (Object.hasOwn(bomJson, CDX20_INTERNAL_SECTIONS_KEY)) {
+    thoughtLog(
+      `Ignoring the ${CDX20_INTERNAL_SECTIONS_KEY} member of a CycloneDX ${specVersion} document; only the 2.0 reader sets it.`,
+    );
+    const { [CDX20_INTERNAL_SECTIONS_KEY]: _ignored, ...internalBom } = bomJson;
+    return { internalBom, specVersion, losses: [] };
+  }
+  return { internalBom: bomJson, specVersion, losses: [] };
+}
+
+/**
+ * The one-line notice a reader prints when loading a 2.0 document lost
+ * data: the number of losses, with the details left to thoughtLog.
+ *
+ * @param {Array<{pointer: string, reason: string}>} losses Reader losses
+ * @returns {string} The notice
+ */
+export function formatReadLossNotice(losses) {
+  const count = losses?.length || 0;
+  return `CycloneDX 2.0 input: reading it into the 1.x model reported ${count} loss${count === 1 ? "" : "es"}; those parts were not analysed. Set CDXGEN_THINK_MODE=true to list them.`;
+}
+
+/**
+ * Return the 1.x-shaped model of a generation run. At 1.x the rendered BOM is
+ * the internal model, so this always yields something readers can walk.
+ *
+ * @param {{bomJson?: object, internalBomJson?: object}} bomNSData
+ * @returns {object} The 1.x-shaped BOM
+ */
+export function getInternalBom(bomNSData) {
+  return bomNSData?.internalBomJson ?? bomNSData?.bomJson;
+}
+
+/**
+ * Re-render the 2.0 document after a post-postProcess mutation of the
+ * internal model, with the render context postProcess used
+ * (`bomNSData.renderContext`). A no-op at 1.x, which keeps those versions
+ * byte-identical.
+ *
+ * @param {{bomJson?: object, internalBomJson?: object, renderContext?: object}} bomNSData
+ * @param {object} options CLI options carrying `specVersion`
+ * @returns {{bomJson?: object, internalBomJson?: object}} The same bomNSData
+ */
+export function refreshRenderedBom(bomNSData, options) {
+  if (
+    !bomNSData?.internalBomJson ||
+    !isCycloneDx20SpecVersion(
+      options?.specVersion ?? bomNSData.bomJson?.specVersion,
+    )
+  ) {
+    return bomNSData;
+  }
+  bomNSData.bomJson = renderCycloneDx20(
+    bomNSData.internalBomJson,
+    bomNSData.renderContext,
+  );
+  return bomNSData;
+}

package/lib/inventory/cyclonedx20Common.js

@@ -0,0 +1,286 @@
+/**
+ * Small shared helpers for the CycloneDX 2.0 renderer and reader: type
+ * guards, cloning, render counters and the environment-variable shape change.
+ */
+
+import { createHash } from "node:crypto";
+
+/** True for a plain object (not null, not an array). */
+export const isObjectRecord = (value) =>
+  Boolean(value && typeof value === "object" && !Array.isArray(value));
+
+/** True for a string with at least one character. */
+export const isNonEmptyString = (value) =>
+  typeof value === "string" && value.length > 0;
+
+/** structuredClone that passes `undefined` through. */
+export const clone = (value) =>
+  value === undefined ? undefined : structuredClone(value);
+
+// bomLinkElementType / bomLinkDocumentType values point into another document
+// (#/$defs/cyclonedx-common-2.0/$defs/bomLink), so they never resolve here.
+export const isBomLink = (value) =>
+  typeof value === "string" && value.startsWith("urn:cdx:");
+
+/**
+ * A fresh, empty set of render counters.
+ *
+ * @param {object} [shadows] 2.0 originals kept by readCycloneDx20 (see
+ *   takeShadow)
+ * @param {{toolRefId?: string, timestamp?: string}} [claims] What identity
+ *   claims are attributed with (see identityClaimContext)
+ * @returns {object} Render counters
+ */
+export function createRenderStats(shadows, claims) {
+  return {
+    claims: isObjectRecord(claims) ? claims : {},
+    customSchemes: new Set(),
+    droppedMethods: [],
+    drops: {},
+    rewrites: {},
+    formulaComponents: [],
+    formulaMembership: [],
+    shadows: isObjectRecord(shadows) ? shadows : {},
+    shadowUse: new Map(),
+  };
+}
+
+/**
+ * The key a 1.x value is shadowed under: the SHA-256 of its JSON. The
+ * reader and the renderer serialize the same object the same way, so an
+ * unchanged value finds its 2.0 original again.
+ *
+ * @param {*} value 1.x value
+ * @returns {string} Hex digest
+ */
+export function shadowKey(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+/**
+ * The 2.0 original readCycloneDx20 kept for this unchanged 1.x value, as a
+ * fresh clone, or undefined. Identical 1.x values kept for several originals
+ * get them back in document order. Never mutates the stored shadows.
+ *
+ * @param {object} stats Render counters from createRenderStats
+ * @param {string} kind Shadow namespace (component, metadata, …)
+ * @param {*} value 1.x value about to be rendered
+ * @returns {*} The 2.0 original or undefined
+ */
+export function takeShadow(stats, kind, value) {
+  const byKind = stats.shadows[kind];
+  if (!isObjectRecord(byKind) || value === undefined) {
+    return undefined;
+  }
+  const key = shadowKey(value);
+  const originals = byKind[key];
+  if (!Array.isArray(originals)) {
+    return undefined;
+  }
+  const useKey = `${kind}:${key}`;
+  const used = stats.shadowUse.get(useKey) || 0;
+  if (used >= originals.length) {
+    return undefined;
+  }
+  stats.shadowUse.set(useKey, used + 1);
+  return clone(originals[used]);
+}
+
+/**
+ * The single 2.0 original readCycloneDx20 kept for this unchanged 1.x value,
+ * as a fresh clone, or undefined. Unlike takeShadow nothing is consumed: the
+ * reader registers a key here only when every entry it read under that key
+ * had the same original, so the lookup does not depend on render order.
+ *
+ * @param {object} stats Render counters from createRenderStats
+ * @param {string} kind Shadow namespace (identity)
+ * @param {*} value 1.x value about to be rendered
+ * @returns {*} The 2.0 original or undefined
+ */
+export function peekShadow(stats, kind, value) {
+  const byKind = stats.shadows[kind];
+  if (!isObjectRecord(byKind) || value === undefined) {
+    return undefined;
+  }
+  const originals = byKind[shadowKey(value)];
+  return Array.isArray(originals) && originals.length === 1
+    ? clone(originals[0])
+    : undefined;
+}
+
+/** Count one dropped or rewritten value under a stable label. */
+export function countDrop(stats, label, count = 1) {
+  stats.drops[label] = (stats.drops[label] || 0) + count;
+}
+
+/**
+ * Count one value the render rewrote without losing data (a duplicate refId
+ * turned into a reference, a retargeted annotation subject).
+ */
+export function countRewrite(stats, label, count = 1) {
+  stats.rewrites[label] = (stats.rewrites[label] || 0) + count;
+}
+
+/**
+ * Count a 1.x JSF `signature` the render leaves out: it signs the 1.x
+ * serialization, so it cannot verify over the re-rendered 2.0 document, and
+ * 2.0 `signatures` hold JSS signatures
+ * (#/$defs/cyclonedx-common-2.0/$defs/signatures).
+ */
+export function countSignatureDrop(stats, path) {
+  countDrop(
+    stats,
+    `${path} (1.x JSF signature: does not verify after re-rendering)`,
+  );
+}
+
+/** Count every defined key of `source` that `handled` does not list. */
+export function countUnmapped(stats, prefix, source, handled) {
+  for (const [key, value] of Object.entries(source)) {
+    if (value !== undefined && !handled.has(key)) {
+      countDrop(stats, `${prefix}.${key}`);
+    }
+  }
+}
+
+/** Clone the listed fields of `source` that are defined onto `target`. */
+export function copyDefined(target, source, fields) {
+  for (const field of fields) {
+    if (source[field] !== undefined) {
+      target[field] = clone(source[field]);
+    }
+  }
+}
+
+/** Remove duplicate entries (by JSON value) for `uniqueItems` arrays. */
+export function uniqueByValue(values) {
+  const seen = new Set();
+  const unique = [];
+  for (const value of values) {
+    const key = JSON.stringify(value);
+    if (!seen.has(key)) {
+      seen.add(key);
+      unique.push(value);
+    }
+  }
+  return unique;
+}
+
+/** Split a 1.x `author` string the way specVersionCompat does. */
+export function authorStringToNames(authorValue) {
+  if (typeof authorValue !== "string") {
+    return [];
+  }
+  return authorValue
+    .split(",")
+    .map((name) => name.trim())
+    .filter(Boolean);
+}
+
+/** A 1.x scalar-or-array identifier field as a list of strings. */
+export function identifierValues(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return typeof value === "string" ? [value] : [];
+}
+
+/** Assign `value` to `out[key]` unless it is undefined. */
+export function setDefined(out, key, value) {
+  if (value !== undefined) {
+    out[key] = value;
+  }
+}
+
+/**
+ * Convert a 1.x `environmentVars` array of {name, value} entries into the 2.0
+ * map of names to values
+ * (#/$defs/cyclonedx-formulation-2.0/$defs/environmentVars). Reverse for read.
+ * Entries the map cannot hold are counted when `stats` is given.
+ */
+export function convertEnvironmentVars(value, stats) {
+  if (Array.isArray(value)) {
+    const mapped = {};
+    for (const entry of value) {
+      // A 1.x string entry becomes a name with a null value, which the 2.0
+      // map allows.
+      const name = typeof entry === "string" ? entry : entry?.name;
+      if (!isObjectRecord(entry) && typeof entry !== "string") {
+        countDropIf(stats, "environmentVars (not a name or {name, value})");
+      } else if (typeof name !== "string") {
+        countDropIf(stats, "environmentVars (no name)");
+      } else if (Object.hasOwn(mapped, name)) {
+        countDropIf(stats, "environmentVars (repeated name)");
+      } else {
+        mapped[name] = typeof entry?.value === "string" ? entry.value : null;
+      }
+    }
+    return mapped;
+  }
+  return clone(value);
+}
+
+function countDropIf(stats, label) {
+  if (stats) {
+    countDrop(stats, label);
+  }
+}
+
+/** Turn a 2.0 environmentVars map back into the 1.x {name, value} array. */
+export function reverseEnvironmentVars(value) {
+  if (!Array.isArray(value) && isObjectRecord(value)) {
+    return Object.entries(value).map(([name, val]) => ({
+      name,
+      value: val === null ? undefined : val,
+    }));
+  }
+  return value;
+}
+
+/** Every refId string declared anywhere under the given roots. */
+export function collectDeclaredRefIds(roots) {
+  const declared = new Set();
+  const visit = (node) => {
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (!isObjectRecord(node)) {
+      return;
+    }
+    if (typeof node.refId === "string") {
+      declared.add(node.refId);
+    }
+    for (const value of Object.values(node)) {
+      visit(value);
+    }
+  };
+  roots.forEach(visit);
+  return declared;
+}
+
+/**
+ * True when any `party` member (a refId string or a partyReference) or any
+ * `ref` member below `node` names `refId`. Restored 2.0 originals reference
+ * a derived party (see derivedPartyDeclarations) without passing through the
+ * converters, so its declaration follows the rendered document rather than a
+ * render flag.
+ */
+export function referencesParty(node, refId) {
+  if (Array.isArray(node)) {
+    return node.some((child) => referencesParty(child, refId));
+  }
+  if (!isObjectRecord(node)) {
+    return false;
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (
+      (key === "party" && (value === refId || value?.ref === refId)) ||
+      (key === "ref" && value === refId) ||
+      referencesParty(value, refId)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}

package/lib/inventory/cyclonedx20Derived.js

@@ -0,0 +1,159 @@
+/**
+ * The 2.0 sections the renderer derives from the 1.x-shaped internal model
+ * rather than converts: post-quantum migration risks (pqcMigration.js,
+ * #4592), and the coding-agent parties and behavioral blueprint
+ * (agentBlueprint.js, #4593).
+ *
+ * A model read from 2.0 carries its 2.0-only sections (risks, blueprints,
+ * parties) for 2.0 output. Derived entries in them are recognised by refId
+ * (`risk-pqc-*`, `blueprint-declared-agents`, agent parties `party-agent-*`
+ * of system kind `agent`). The renderer drops carried derived entries and
+ * derives them again from the model, so they follow edits to the model and
+ * are never declared twice. Every other carried entry is kept, first, and a
+ * derived entry never replaces a carried entry with the same refId.
+ *
+ * Only cdxgen's own analysis is derived: the sections are derived only when
+ * the model's `metadata.tools` lists cdxgen with a bom-ref, the rule
+ * identityClaimContext applies to cdxgen's identity claims. Another tool's
+ * BOM converted with `cdx-convert --to 2.0` gets no derived section.
+ */
+
+import { isDeepStrictEqual } from "node:util";
+
+import {
+  AGENT_BLUEPRINT_REF_ID,
+  AGENT_PARTY_REF_ID_PREFIX,
+  collectAgentBehaviour,
+} from "./agentBlueprint.js";
+import { clone, isObjectRecord } from "./cyclonedx20Common.js";
+import { identityClaimContext } from "./cyclonedx20RenderEvidence.js";
+import { collectPqcRisks, PQC_RISK_REF_ID_PREFIX } from "./pqcMigration.js";
+
+const startsWith = (value, prefix) =>
+  typeof value === "string" && value.startsWith(prefix);
+
+/** A risk entry renderCycloneDx20 derives (see collectPqcRisks). */
+export const isDerivedRisk = (risk) =>
+  startsWith(risk?.refId, PQC_RISK_REF_ID_PREFIX);
+
+/** The blueprint renderCycloneDx20 derives (see collectAgentBehaviour). */
+export const isDerivedBlueprint = (blueprint) =>
+  blueprint?.refId === AGENT_BLUEPRINT_REF_ID;
+
+/** An agent party renderCycloneDx20 derives (see collectAgentBehaviour). */
+export const isDerivedAgentParty = (party) =>
+  startsWith(party?.refId, AGENT_PARTY_REF_ID_PREFIX) &&
+  party?.system?.kind === "agent";
+
+/**
+ * Does the model's `metadata.tools` list cdxgen with a bom-ref? The same
+ * test decides whether cdxgen's identity claims are written.
+ *
+ * @param {object} internalBom The 1.x-shaped internal model
+ * @returns {boolean} True when cdxgen is a listed tool
+ */
+export function isCdxgenListedTool(internalBom) {
+  return identityClaimContext(internalBom).toolRefId !== undefined;
+}
+
+/**
+ * Derive the 2.0 sections of an internal model; all empty unless cdxgen is a
+ * listed tool (isCdxgenListedTool).
+ *
+ * @param {object} internalBom The 1.x-shaped internal model
+ * @returns {{risks: object[], agentParties: object[], blueprints: object[]}}
+ */
+export function deriveCycloneDx20Sections(internalBom) {
+  if (!isCdxgenListedTool(internalBom)) {
+    return { risks: [], agentParties: [], blueprints: [] };
+  }
+  const { parties, blueprint } = collectAgentBehaviour(internalBom);
+  return {
+    risks: collectPqcRisks(internalBom),
+    agentParties: parties,
+    blueprints: blueprint ? [blueprint] : [],
+  };
+}
+
+/** Carried entries that are not derived, then derived ones with new refIds. */
+function mergeByRefId(carried, derived, isDerived) {
+  const kept = (Array.isArray(carried) ? carried : []).filter(
+    (entry) => !isDerived(entry),
+  );
+  const refIds = new Set(kept.map((entry) => entry?.refId));
+  return [...kept, ...derived.filter((entry) => !refIds.has(entry.refId))];
+}
+
+/**
+ * Add the derived risks and blueprint to a rendered document whose carried
+ * 2.0 sections are already in place, and return the parties to declare: the
+ * carried parties without derived agent parties, then the derived ones.
+ *
+ * @param {object} out The document being rendered
+ * @param {object[]} carriedParties Parties carried from a 2.0 read
+ * @param {object} internalBom The internal model the document renders
+ * @returns {object[]} The parties to declare before the cdxgen party
+ */
+export function appendDerivedSections(out, carriedParties, internalBom) {
+  const derived = deriveCycloneDx20Sections(internalBom);
+  // For another tool's document cdxgen derives nothing, and entries that look
+  // derived are that tool's own, so they are kept.
+  const listed = isCdxgenListedTool(internalBom);
+  const derivedOnly = (isDerived) => (entry) => listed && isDerived(entry);
+  const risks = mergeByRefId(
+    (isObjectRecord(out.risks) ? out.risks : {}).risks,
+    derived.risks,
+    derivedOnly(isDerivedRisk),
+  );
+  const risksSection = isObjectRecord(out.risks) ? out.risks : {};
+  const { risks: _risks, ...riskMembers } = risksSection;
+  if (risks.length) {
+    out.risks = { ...riskMembers, risks };
+  } else if (Object.keys(riskMembers).length) {
+    out.risks = riskMembers;
+  } else {
+    delete out.risks;
+  }
+  const blueprints = mergeByRefId(
+    out.blueprints,
+    derived.blueprints,
+    derivedOnly(isDerivedBlueprint),
+  );
+  if (blueprints.length) {
+    out.blueprints = blueprints;
+  } else {
+    delete out.blueprints;
+  }
+  return mergeByRefId(
+    carriedParties,
+    derived.agentParties,
+    derivedOnly(isDerivedAgentParty),
+  );
+}
+
+/**
+ * Split the derived entries out of a list read from 2.0. An entry that is
+ * what the renderer derives again from the read model is dropped without a
+ * loss; a derived-looking entry that differs is dropped too (the renderer
+ * would replace it), and its index is returned so the reader reports the
+ * loss.
+ *
+ * @param {object[]} entries The 2.0 list (risks, blueprints, parties)
+ * @param {object[]} derived What the renderer derives from the read model
+ * @param {Function} isDerived Recogniser for derived entries
+ * @returns {{kept: object[], differing: number[]}} The entries to carry, and
+ *   the indexes of dropped entries that differ from the derivation
+ */
+export function splitDerivedEntries(entries, derived, isDerived) {
+  const byRefId = new Map(derived.map((entry) => [entry.refId, entry]));
+  const kept = [];
+  const differing = [];
+  (Array.isArray(entries) ? entries : []).forEach((entry, index) => {
+    if (!isDerived(entry)) {
+      kept.push(entry);
+    } else if (!isDeepStrictEqual(byRefId.get(entry.refId), entry)) {
+      differing.push(index);
+    }
+  });
+  return { kept: clone(kept), differing };
+}