@cdxgen/cdxgen 13.6.0 → 13.7.0

package/lib/inventory/cyclonedx20RenderHardware.js

@@ -0,0 +1,203 @@
+/**
+ * Hardware components at 2.0 (cdxgen/cdxgen#4755). What each `cdx:hbom:*`
+ * property means in the 2.0 draft is owned by @cdxgen/cdx-hbom, whose
+ * optional `./cdx20` export provides `toCdx20HardwareComponent(component,
+ * {partyRefId, includeSensitiveIdentifiers, identifierPolicy})`. The caller
+ * loads it (lib/inventory/hbomLoader.js: hardwareRenderContext) and passes
+ * it, with those options, to renderCycloneDx20 in the render context, so the
+ * render stays a pure function of its arguments.
+ *
+ * The renderer converts the component as usual and then takes only these
+ * members from the mapper's result, each checked against the pinned schema:
+ *
+ * - `identifiers`: only groups asserted by the party the renderer passed
+ *   (the one its own identifiers use, which it declares when referenced).
+ *   Their identities are appended to that party's group, or added as a new
+ *   group, so a purl identity is never replaced. Only identities with a
+ *   scheme from the identityScheme enum (or a custom `{name}`) and a
+ *   non-empty value are taken.
+ * - `classification` (#/$defs/cyclonedx-physical-2.0/$defs/classification):
+ *   `category`, `subcategory`, and `codes` that are taxonomyCode objects
+ *   (`{standard, value}`); a bare string code is dropped and counted.
+ * - a manufacturer party, when the generic conversion produced none.
+ *
+ * Every `cdx:hbom:*` property stays: the hbom audit rules read them.
+ */
+
+import { thoughtLog } from "../core/logger.js";
+import {
+  clone,
+  countDrop,
+  isNonEmptyString,
+  isObjectRecord,
+  uniqueByValue,
+} from "./cyclonedx20Common.js";
+import { identifierPartyRefId } from "./cyclonedx20RenderEvidence.js";
+import { IDENTITY_SCHEME_ENUM } from "./cyclonedx20Tables.js";
+
+const TAXONOMY_CODE_FIELDS = Object.freeze(["description", "url"]);
+
+/** True when the 1.x component carries at least one cdx:hbom:* property. */
+export function isHardwareComponent(component) {
+  return (
+    Array.isArray(component?.properties) ? component.properties : []
+  ).some(
+    (property) =>
+      typeof property?.name === "string" &&
+      property.name.startsWith("cdx:hbom:"),
+  );
+}
+
+function isValidIdentity(identity) {
+  if (!isObjectRecord(identity) || !isNonEmptyString(identity.value)) {
+    return false;
+  }
+  const { scheme } = identity;
+  return (
+    (typeof scheme === "string" && IDENTITY_SCHEME_ENUM.has(scheme)) ||
+    (isObjectRecord(scheme) && isNonEmptyString(scheme.name))
+  );
+}
+
+function appendIdentifiers(converted, groups, partyRefId, stats) {
+  for (const group of Array.isArray(groups) ? groups : []) {
+    if (!isObjectRecord(group) || group.party !== partyRefId) {
+      // Any other party would have no declaration in this document.
+      countDrop(stats, "hardware identifier (undeclared party)");
+      continue;
+    }
+    const identities = (Array.isArray(group.identities) ? group.identities : [])
+      .filter((identity) => {
+        const valid = isValidIdentity(identity);
+        if (!valid) {
+          countDrop(stats, "hardware identity (not a 2.0 identity)");
+        }
+        return valid;
+      })
+      .map((identity) => ({
+        scheme: clone(identity.scheme),
+        value: identity.value,
+      }));
+    if (!identities.length) {
+      continue;
+    }
+    converted.identifiers = Array.isArray(converted.identifiers)
+      ? converted.identifiers
+      : [];
+    const existing = converted.identifiers.find(
+      (entry) => entry.party === group.party,
+    );
+    if (existing) {
+      existing.identities = uniqueByValue([
+        ...existing.identities,
+        ...identities,
+      ]);
+    } else {
+      converted.identifiers.push({ party: group.party, identities });
+    }
+  }
+}
+
+function taxonomyCode(code, stats) {
+  if (
+    !isObjectRecord(code) ||
+    !isNonEmptyString(code.standard) ||
+    !isNonEmptyString(code.value)
+  ) {
+    countDrop(stats, "hardware classification code (not a taxonomyCode)");
+    return undefined;
+  }
+  const converted = { standard: code.standard, value: code.value };
+  for (const field of TAXONOMY_CODE_FIELDS) {
+    if (typeof code[field] === "string") {
+      converted[field] = code[field];
+    }
+  }
+  return converted;
+}
+
+function setClassification(converted, classification, stats) {
+  if (!isObjectRecord(classification) || converted.classification) {
+    return;
+  }
+  const result = {};
+  if (isNonEmptyString(classification.category)) {
+    result.category = classification.category;
+  }
+  if (typeof classification.subcategory === "string") {
+    result.subcategory = classification.subcategory;
+  }
+  const codes = uniqueByValue(
+    (Array.isArray(classification.codes) ? classification.codes : [])
+      .map((code) => taxonomyCode(code, stats))
+      .filter(Boolean),
+  );
+  if (codes.length) {
+    result.codes = codes;
+  }
+  if (Object.keys(result).length) {
+    converted.classification = result;
+  }
+}
+
+function addManufacturerParty(converted, parties) {
+  const hasManufacturer = (converted.parties || []).some((party) =>
+    (party?.roles || []).some((role) => role?.role === "manufacturer"),
+  );
+  if (hasManufacturer) {
+    return;
+  }
+  const mapped = (Array.isArray(parties) ? parties : []).find(
+    (party) =>
+      (party?.roles || []).some((role) => role?.role === "manufacturer") &&
+      isNonEmptyString(party?.organization?.name),
+  );
+  if (mapped) {
+    converted.parties = [
+      ...(converted.parties || []),
+      {
+        roles: [{ role: "manufacturer" }],
+        organization: { name: mapped.organization.name },
+      },
+    ];
+  }
+}
+
+/**
+ * Add the hardware mapper's 2.0 members to a converted hardware component.
+ * Without a mapper, or for a component without cdx:hbom:* properties, the
+ * converted component is returned unchanged. The mapper gets a clone of the
+ * 1.x component, the asserting party refId the generic identifiers use (so
+ * its identifiers resolve to the party the renderer declares) and the
+ * identifier options of the render context (`stats.hardwareOptions`).
+ *
+ * @param {object} component The 1.x component
+ * @param {object} converted Its generic 2.0 conversion, extended in place
+ * @param {object} stats Render counters with the optional `hardwareMapper`
+ * @returns {object} The converted component
+ */
+export function applyHardwareMapping(component, converted, stats) {
+  const mapper = stats.hardwareMapper;
+  if (typeof mapper !== "function" || !isHardwareComponent(component)) {
+    return converted;
+  }
+  const partyRefId = identifierPartyRefId(stats.claims);
+  let mapped;
+  try {
+    mapped = mapper(clone(component), {
+      ...stats.hardwareOptions,
+      partyRefId,
+    });
+  } catch (error) {
+    countDrop(stats, "hardware mapping (mapper failed)");
+    thoughtLog(`CycloneDX 2.0 hardware mapping failed: ${error?.message}`);
+    return converted;
+  }
+  if (!isObjectRecord(mapped)) {
+    return converted;
+  }
+  appendIdentifiers(converted, mapped.identifiers, partyRefId, stats);
+  setClassification(converted, mapped.classification, stats);
+  addManufacturerParty(converted, mapped.parties);
+  return converted;
+}

package/lib/inventory/cyclonedx20RenderPatents.js

@@ -0,0 +1,174 @@
+/**
+ * Render-side conversion of 1.x patents, patent families and patent
+ * assertions (#/$defs/cyclonedx-patent-2.0). The members are the same; the
+ * 1.x `bom-ref` becomes `refId`, and organizations and contacts take the
+ * 2.0 common shapes.
+ */
+
+import {
+  clone,
+  copyDefined,
+  countDrop,
+  countUnmapped,
+  isNonEmptyString,
+  isObjectRecord,
+} from "./cyclonedx20Common.js";
+import { toCommonContact, toCommonEntity } from "./cyclonedx20Parties.js";
+
+const PATENT_FIELDS = [
+  "patentNumber",
+  "applicationNumber",
+  "jurisdiction",
+  "priorityApplication",
+  "publicationNumber",
+  "abstract",
+  "filingDate",
+  "grantDate",
+  "patentExpirationDate",
+  "patentLegalStatus",
+  "externalReferences",
+];
+const PATENT_HANDLED = new Set([...PATENT_FIELDS, "bom-ref", "patentAssignee"]);
+
+const PATENT_FAMILY_FIELDS = [
+  "familyId",
+  "priorityApplication",
+  "members",
+  "externalReferences",
+];
+const PATENT_FAMILY_HANDLED = new Set([...PATENT_FAMILY_FIELDS, "bom-ref"]);
+
+const ASSERTION_FIELDS = ["assertionType", "patentRefs", "notes"];
+const ASSERTION_HANDLED = new Set([...ASSERTION_FIELDS, "bom-ref", "asserter"]);
+
+/** Start a converted object with the 1.x `bom-ref` as its `refId`. */
+function withRefId(source) {
+  return isNonEmptyString(source["bom-ref"])
+    ? { refId: source["bom-ref"] }
+    : {};
+}
+
+/**
+ * A 1.x organizationalEntity or organizationalContact as its 2.0 common
+ * shape, for the members whose schema is a oneOf of the two. Only a contact
+ * has `email` or `phone`, only an organization `url`, `address` or
+ * `contact`. With neither (a bare name) the value matches both branches of
+ * the oneOf and so validates as neither; it is counted under `label` and
+ * undefined is returned.
+ */
+function toCommonEntityOrContact(value, label, stats) {
+  if (!isObjectRecord(value)) {
+    countDrop(stats, `${label} (not an object)`);
+    return undefined;
+  }
+  const isContact =
+    (value.email !== undefined || value.phone !== undefined) &&
+    value.url === undefined &&
+    value.address === undefined &&
+    value.contact === undefined;
+  const converted = isContact
+    ? toCommonContact(value, stats)
+    : toCommonEntity(value, stats);
+  if (
+    !converted ||
+    Object.keys(converted).every((key) => key === "refId" || key === "name")
+  ) {
+    countDrop(stats, `${label} (neither an organization nor a contact)`);
+    return undefined;
+  }
+  return converted;
+}
+
+/**
+ * Convert 1.x definitions.patents: patents and patent families.
+ *
+ * @param {object[]} patents 1.x patents and patent families
+ * @param {object} stats Render counters
+ * @returns {object[]|undefined} 2.0 patents
+ */
+export function convertPatents(patents, stats) {
+  if (!Array.isArray(patents)) {
+    if (patents !== undefined) {
+      countDrop(stats, "definitions.patents (not a list)");
+    }
+    return undefined;
+  }
+  const converted = [];
+  for (const patent of patents) {
+    if (!isObjectRecord(patent)) {
+      countDrop(stats, "definitions.patents (not an object)");
+      continue;
+    }
+    const out = withRefId(patent);
+    if (patent.familyId !== undefined) {
+      copyDefined(out, patent, PATENT_FAMILY_FIELDS);
+      countUnmapped(
+        stats,
+        "definitions.patents",
+        patent,
+        PATENT_FAMILY_HANDLED,
+      );
+    } else {
+      copyDefined(out, patent, PATENT_FIELDS);
+      if (Array.isArray(patent.patentAssignee)) {
+        const assignees = patent.patentAssignee
+          .map((assignee) =>
+            toCommonEntityOrContact(
+              assignee,
+              "definitions.patents.patentAssignee",
+              stats,
+            ),
+          )
+          .filter(Boolean);
+        if (assignees.length) {
+          out.patentAssignee = assignees;
+        }
+      }
+      countUnmapped(stats, "definitions.patents", patent, PATENT_HANDLED);
+    }
+    converted.push(out);
+  }
+  return converted.length ? converted : undefined;
+}
+
+/**
+ * Convert 1.x patentAssertions
+ * (#/$defs/cyclonedx-patent-2.0/$defs/patentAssertions): the asserter is an
+ * organization, a contact or a refLinkType string.
+ *
+ * @param {object[]} assertions 1.x patent assertions
+ * @param {object} stats Render counters
+ * @returns {object[]|undefined} 2.0 patent assertions, or undefined when
+ *   none is left
+ */
+export function convertPatentAssertions(assertions, stats) {
+  if (!Array.isArray(assertions)) {
+    return clone(assertions);
+  }
+  const converted = [];
+  for (const assertion of assertions) {
+    if (!isObjectRecord(assertion)) {
+      countDrop(stats, "patentAssertions (not an object)");
+      continue;
+    }
+    // `asserter` is required.
+    const asserter =
+      typeof assertion.asserter === "string"
+        ? assertion.asserter
+        : toCommonEntityOrContact(
+            assertion.asserter,
+            "patentAssertions.asserter",
+            stats,
+          );
+    if (!asserter) {
+      countDrop(stats, "patentAssertions (no asserter)");
+      continue;
+    }
+    const out = withRefId(assertion);
+    copyDefined(out, assertion, ASSERTION_FIELDS);
+    out.asserter = asserter;
+    countUnmapped(stats, "patentAssertions", assertion, ASSERTION_HANDLED);
+    converted.push(out);
+  }
+  return converted.length ? converted : undefined;
+}

package/lib/inventory/cyclonedx20RenderRefIds.js

@@ -0,0 +1,314 @@
+/**
+ * Reference integrity of a rendered CycloneDX 2.0 document: every refId is
+ * unique (the 2.0 refIdType rule "Every `refId` shall be unique within the
+ * document", which JSON Schema cannot check), and dependency and
+ * vulnerability references resolve to a declared refId or a BOM-Link.
+ */
+
+import { isDeepStrictEqual } from "node:util";
+
+import {
+  clone,
+  countDrop,
+  countRewrite,
+  isBomLink,
+  isObjectRecord,
+} from "./cyclonedx20Common.js";
+import { COMPONENT_ENTRY_ARRAY_KEYS } from "./cyclonedx20Tables.js";
+
+// Returned by the walk for a declaration-only entry that repeats an earlier
+// declaration; the enclosing array leaves it out.
+const REMOVE = Symbol("remove");
+
+// Slots outside component and party lists: a duplicate there has no
+// reference form.
+const PLAIN_SLOT = Object.freeze({});
+
+/** How many times each refId string is declared under the roots. */
+function countRefIds(roots) {
+  const counts = new Map();
+  const visit = (node) => {
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (!isObjectRecord(node)) {
+      return;
+    }
+    if (typeof node.refId === "string") {
+      counts.set(node.refId, (counts.get(node.refId) || 0) + 1);
+    }
+    for (const value of Object.values(node)) {
+      visit(value);
+    }
+  };
+  roots.forEach(({ value }) => {
+    visit(value);
+  });
+  return counts;
+}
+
+/**
+ * True when a reference to `earlier` loses nothing of `later`: every member
+ * of `later` except its refId has a deep-equal counterpart in `earlier`.
+ */
+function isCoveredBy(later, earlier) {
+  if (!isObjectRecord(earlier)) {
+    return false;
+  }
+  for (const [key, value] of Object.entries(later)) {
+    if (key !== "refId" && !isDeepStrictEqual(value, earlier[key])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** `${refId}-dup-<n>` for the smallest n not already taken. */
+function uniqueRefId(refId, taken) {
+  let index = 1;
+  while (taken.has(`${refId}-dup-${index}`)) {
+    index++;
+  }
+  const fresh = `${refId}-dup-${index}`;
+  taken.add(fresh);
+  return fresh;
+}
+
+/**
+ * The slot a member value sits in. Component entry lists, the inventory
+ * subject and an annotator component accept a componentReference
+ * (#/$defs/cyclonedx-component-2.0/$defs/componentEntry), party lists a
+ * partyReference (#/$defs/cyclonedx-party-2.0/$defs/partyChoice). The
+ * definitions registry lists components and parties but accepts no
+ * reference form (#/$defs/cyclonedx-definition-2.0/$defs/definitions).
+ */
+function memberSlot(key, value, ownKey, inDefinitions) {
+  const isList = Array.isArray(value);
+  if (inDefinitions && isList && (key === "components" || key === "parties")) {
+    return {
+      kind: key === "components" ? "component" : "party",
+      declarationOnly: true,
+    };
+  }
+  if (
+    (COMPONENT_ENTRY_ARRAY_KEYS.has(key) && isList) ||
+    key === "subject" ||
+    (key === "component" && ownKey === "annotator")
+  ) {
+    return { kind: "component", reference: true };
+  }
+  if (key === "parties" && isList) {
+    return { kind: "party", reference: true };
+  }
+  return PLAIN_SLOT;
+}
+
+/**
+ * Make every refId unique. The roots are walked in order, so the earliest
+ * root keeps a repeated refId; pass the inventories before metadata so the
+ * subject of a self-scan keeps its members when it repeats the refId of the
+ * tool. A later declaration with an already declared refId becomes:
+ *
+ * - a componentReference or partyReference `{ref}` when it sits in a slot
+ *   that accepts one and an earlier declaration of the same kind already
+ *   holds every member it has (nothing is lost);
+ * - nothing, in the definitions registry, under the same condition (counted
+ *   as already declared), and also when an inventory declares the refId
+ *   with other members (the members only the registry entry had are
+ *   counted as dropped);
+ * - unchanged, when neither it nor an earlier declaration sits in a
+ *   component or party slot (counted);
+ * - otherwise the same object under a new refId `<refId>-dup-<n>`, so no data
+ *   is lost and references to the refId keep resolving to the first
+ *   declaration.
+ *
+ * @param {Array<{section: string, value: *}>} roots Rendered sections, the
+ *   definitions root marked with `section: "definitions"`
+ * @param {object} stats Render counters
+ */
+export function dedupeRefIds(roots, stats) {
+  const counts = countRefIds(roots);
+  const taken = new Set(counts.keys());
+  const seen = new Map();
+  const declare = (node, slot, section) => {
+    const refId = node.refId;
+    const variants = seen.get(refId);
+    if (!variants) {
+      seen.set(refId, [
+        {
+          kind: slot.kind,
+          refId,
+          section,
+          snapshot: counts.get(refId) > 1 ? clone(node) : undefined,
+        },
+      ]);
+      return node;
+    }
+    const match = slot.kind
+      ? variants.find(
+          (variant) =>
+            variant.kind === slot.kind && isCoveredBy(node, variant.snapshot),
+        )
+      : undefined;
+    if (match && slot.declarationOnly) {
+      countRewrite(
+        stats,
+        `definitions ${slot.kind} (already declared in ${match.section === "inventories" ? "inventory" : match.section})`,
+      );
+      return REMOVE;
+    }
+    // A formula component the inventory declares too: 2.0 records no formula
+    // membership, so a second definition would only repeat the component
+    // under another refId. The inventory declaration stays, references keep
+    // resolving to it, and the members only this copy had are counted.
+    const inventoryVariant =
+      slot.declarationOnly &&
+      variants.find(
+        (variant) =>
+          variant.kind === slot.kind && variant.section === "inventories",
+      );
+    if (inventoryVariant) {
+      countDrop(
+        stats,
+        `definitions ${slot.kind} (already declared in inventory; members it adds dropped)`,
+      );
+      return REMOVE;
+    }
+    if (match && slot.reference) {
+      countRewrite(stats, "duplicate refId (rendered as a reference)");
+      return { ref: match.refId };
+    }
+    if (!slot.kind && !variants.some((variant) => variant.kind)) {
+      // Neither declaration sits where a componentReference or
+      // partyReference could name it (a formula and its workflow, say), so
+      // no reference can resolve to the wrong one. A document read from 2.0
+      // keeps its refIds as written; the repeat is counted.
+      countRewrite(stats, "duplicate refId (kept: no reference form)");
+      return node;
+    }
+    node.refId = uniqueRefId(refId, taken);
+    countRewrite(stats, "duplicate refId (kept under a new refId)");
+    variants.push({
+      kind: slot.kind,
+      refId: node.refId,
+      section,
+      snapshot: clone(node),
+    });
+    return node;
+  };
+  const visit = (node, slot, ownKey, section, inDefinitions) => {
+    if (Array.isArray(node)) {
+      let removed = false;
+      for (let index = 0; index < node.length; index++) {
+        node[index] = visit(node[index], slot, ownKey, section, false);
+        removed ||= node[index] === REMOVE;
+      }
+      if (removed) {
+        const kept = node.filter((entry) => entry !== REMOVE);
+        node.length = 0;
+        node.push(...kept);
+      }
+      return node;
+    }
+    if (!isObjectRecord(node)) {
+      return node;
+    }
+    if (typeof node.refId === "string") {
+      const declared = declare(node, slot, section);
+      if (declared !== node) {
+        return declared;
+      }
+    }
+    for (const [key, value] of Object.entries(node)) {
+      node[key] = visit(
+        value,
+        memberSlot(key, value, ownKey, inDefinitions),
+        key,
+        section,
+        false,
+      );
+    }
+    return node;
+  };
+  for (const { section, value } of roots) {
+    visit(value, PLAIN_SLOT, undefined, section, section === "definitions");
+  }
+}
+
+const resolves = (ref, declared) =>
+  typeof ref === "string" && (declared.has(ref) || isBomLink(ref));
+
+/**
+ * Keep only dependency references that resolve: an entry whose `ref` names
+ * nothing declared is dropped, and so is each such `dependsOn` and
+ * `provides` member. An emptied `dependsOn` stays, since an empty list says
+ * the component has no dependencies.
+ *
+ * @param {object[]|undefined} dependencies Rendered dependencies
+ * @param {Set<string>} declared Every declared refId
+ * @param {object} stats Render counters
+ * @returns {object[]|undefined} The dependencies left, or undefined
+ */
+export function resolveDependencyRefs(dependencies, declared, stats) {
+  if (!Array.isArray(dependencies)) {
+    return undefined;
+  }
+  const kept = [];
+  for (const dependency of dependencies) {
+    if (!resolves(dependency.ref, declared)) {
+      countDrop(stats, "dependency (undeclared ref)");
+      continue;
+    }
+    for (const key of ["dependsOn", "provides"]) {
+      if (!Array.isArray(dependency[key])) {
+        continue;
+      }
+      const refs = dependency[key].filter((ref) => resolves(ref, declared));
+      if (refs.length !== dependency[key].length) {
+        countDrop(
+          stats,
+          `dependency.${key} (undeclared ref)`,
+          dependency[key].length - refs.length,
+        );
+      }
+      dependency[key] = refs;
+    }
+    kept.push(dependency);
+  }
+  return kept.length ? kept : undefined;
+}
+
+/**
+ * Drop vulnerability `affects` entries whose `ref` resolves to nothing, and
+ * an `affects` list left empty.
+ *
+ * @param {object[]|undefined} vulnerabilities Rendered vulnerabilities
+ * @param {Set<string>} declared Every declared refId
+ * @param {object} stats Render counters
+ */
+export function resolveAffectsRefs(vulnerabilities, declared, stats) {
+  for (const vulnerability of vulnerabilities || []) {
+    if (
+      !isObjectRecord(vulnerability) ||
+      !Array.isArray(vulnerability.affects)
+    ) {
+      continue;
+    }
+    const affects = vulnerability.affects.filter((entry) =>
+      resolves(entry?.ref, declared),
+    );
+    if (affects.length !== vulnerability.affects.length) {
+      countDrop(
+        stats,
+        "vulnerability.affects (undeclared ref)",
+        vulnerability.affects.length - affects.length,
+      );
+    }
+    if (affects.length) {
+      vulnerability.affects = affects;
+    } else {
+      delete vulnerability.affects;
+    }
+  }
+}