@cyclonedx/cdxgen 12.2.1 → 12.3.0

package/lib/helpers/spdxUtils.js

@@ -0,0 +1,97 @@
+import { PackageURL } from "packageurl-js";
+
+import { isSpdxJsonLd } from "./bomUtils.js";
+
+const toArray = (value) => {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (value !== undefined && value !== null) {
+    return [value];
+  }
+  return [];
+};
+
+const toCycloneDxLikeComponent = (spdxElement) => {
+  const purl = spdxElement?.software_packageUrl;
+  let group = "";
+  let name = spdxElement?.name || spdxElement?.spdxId || "unnamed-component";
+  let version = spdxElement?.software_packageVersion || "";
+  if (purl) {
+    try {
+      const purlObj = PackageURL.fromString(purl);
+      group = purlObj.namespace || "";
+      name = purlObj.name || name;
+      version = purlObj.version || version;
+    } catch (_err) {
+      // Keep SPDX element values when purl parsing fails.
+    }
+  }
+  return {
+    type: spdxElement?.type === "software_File" ? "file" : "library",
+    group,
+    name,
+    version,
+    purl,
+    "bom-ref": purl || spdxElement?.spdxId || name,
+    description: spdxElement?.description,
+  };
+};
+
+export const toCycloneDxLikeBom = (bomJson) => {
+  if (!isSpdxJsonLd(bomJson)) {
+    return bomJson;
+  }
+  const graphElements = toArray(bomJson?.["@graph"]);
+  const packageElements = graphElements.filter((element) =>
+    ["software_Package", "software_File"].includes(element?.type),
+  );
+  const components = packageElements.map(toCycloneDxLikeComponent);
+  const spdxIdToRef = new Map();
+  for (let index = 0; index < packageElements.length; index++) {
+    const spdxId = packageElements[index]?.spdxId;
+    if (spdxId) {
+      spdxIdToRef.set(spdxId, components[index]["bom-ref"]);
+    }
+  }
+  const dependencyMap = new Map();
+  for (const component of components) {
+    dependencyMap.set(component["bom-ref"], new Set());
+  }
+  for (const element of graphElements) {
+    if (
+      element?.type !== "Relationship" ||
+      element?.relationshipType !== "dependsOn"
+    ) {
+      continue;
+    }
+    if (!element?.from || typeof element.from !== "string") {
+      continue;
+    }
+    const fromRef = spdxIdToRef.get(element.from) || element.from;
+    const toRefs = toArray(element?.to).map(
+      (toRef) => spdxIdToRef.get(toRef) || toRef,
+    );
+    if (!dependencyMap.has(fromRef)) {
+      dependencyMap.set(fromRef, new Set());
+    }
+    const dependsOnSet = dependencyMap.get(fromRef);
+    for (const toRef of toRefs) {
+      if (toRef) {
+        dependsOnSet.add(toRef);
+      }
+    }
+  }
+  const dependencies = [];
+  for (const [ref, dependsOnSet] of dependencyMap.entries()) {
+    dependencies.push({
+      ref,
+      dependsOn: Array.from(dependsOnSet).sort(),
+    });
+  }
+  return {
+    ...bomJson,
+    components,
+    dependencies,
+  };
+};

package/lib/helpers/spdxUtils.poku.js

@@ -0,0 +1,70 @@
+import { assert, describe, it } from "poku";
+
+import { toCycloneDxLikeBom } from "./spdxUtils.js";
+
+const sampleSpdx = {
+  "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
+  "@graph": [
+    { type: "CreationInfo", spdxId: "urn:demo#CreationInfo-main" },
+    { type: "SpdxDocument", spdxId: "urn:demo#SPDXRef-DOCUMENT" },
+    {
+      type: "software_Package",
+      spdxId: "urn:demo#SPDXRef-app",
+      name: "app",
+      software_packageUrl: "pkg:npm/@acme/app@1.2.3",
+      software_packageVersion: "1.2.3",
+    },
+    {
+      type: "software_Package",
+      spdxId: "urn:demo#SPDXRef-lib",
+      name: "lib",
+      software_packageUrl: "pkg:npm/lodash@4.17.21",
+      software_packageVersion: "4.17.21",
+    },
+    {
+      type: "Relationship",
+      spdxId: "urn:demo#Relationship-1",
+      relationshipType: "dependsOn",
+      from: "urn:demo#SPDXRef-app",
+      to: ["urn:demo#SPDXRef-lib"],
+    },
+  ],
+};
+
+describe("spdxUtils", () => {
+  it("returns non-SPDX BOMs unchanged", () => {
+    const cyclonedxBom = { bomFormat: "CycloneDX", components: [] };
+    assert.strictEqual(toCycloneDxLikeBom(cyclonedxBom), cyclonedxBom);
+  });
+
+  it("converts SPDX package and relationship graph into CycloneDX-like components/dependencies", () => {
+    const converted = toCycloneDxLikeBom(sampleSpdx);
+    assert.strictEqual(Array.isArray(converted.components), true);
+    assert.strictEqual(converted.components.length, 2);
+    assert.strictEqual(converted.components[0].name, "app");
+    assert.strictEqual(converted.components[0].version, "1.2.3");
+    assert.strictEqual(Array.isArray(converted.dependencies), true);
+    const appDependency = converted.dependencies.find(
+      (dep) => dep.ref === "pkg:npm/@acme/app@1.2.3",
+    );
+    assert.ok(appDependency);
+    assert.deepStrictEqual(appDependency.dependsOn, ["pkg:npm/lodash@4.17.21"]);
+  });
+
+  it("ignores invalid SPDX relationships where 'from' is not a string", () => {
+    const malformedSpdx = structuredClone(sampleSpdx);
+    malformedSpdx["@graph"].push({
+      type: "Relationship",
+      spdxId: "urn:demo#Relationship-2",
+      relationshipType: "dependsOn",
+      from: ["urn:demo#SPDXRef-app"],
+      to: ["urn:demo#SPDXRef-lib"],
+    });
+    const converted = toCycloneDxLikeBom(malformedSpdx);
+    const appDependency = converted.dependencies.find(
+      (dep) => dep.ref === "pkg:npm/@acme/app@1.2.3",
+    );
+    assert.ok(appDependency);
+    assert.deepStrictEqual(appDependency.dependsOn, ["pkg:npm/lodash@4.17.21"]);
+  });
+});

package/lib/helpers/unicodeScan.js

@@ -0,0 +1,147 @@
+const BIDI_CHARS = /[\u202A-\u202E\u2066-\u2069]/gu;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: Hidden Unicode scanning must detect raw control ranges.
+const CONTROL_CHARS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/gu;
+const ZERO_WIDTH_CHARS = /[\u200B-\u200D\uFEFF]/gu;
+
+function formatCodePoint(char) {
+  return `U+${char.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")}`;
+}
+
+function findMatchesByPattern(text, pattern, kind) {
+  const matches = [];
+  for (const match of text.matchAll(pattern)) {
+    matches.push({
+      char: match[0],
+      codePoint: formatCodePoint(match[0]),
+      index: match.index,
+      kind,
+    });
+  }
+  return matches;
+}
+
+function lineNumberForIndex(text, index) {
+  return text.slice(0, index).split(/\r?\n/u).length;
+}
+
+function commentLineNumbers(text, syntax) {
+  const commentLines = new Set();
+  if (!text) {
+    return commentLines;
+  }
+  const lines = text.split(/\r?\n/u);
+  if (syntax === "yaml") {
+    lines.forEach((line, lineIndex) => {
+      if (line.trim().startsWith("#")) {
+        commentLines.add(lineIndex + 1);
+      }
+    });
+    return commentLines;
+  }
+  if (syntax === "markdown") {
+    let inHtmlComment = false;
+    lines.forEach((line, lineIndex) => {
+      const hasCommentStart = line.includes("<!--");
+      const hasCommentEnd = line.includes("-->");
+      if (inHtmlComment || hasCommentStart) {
+        commentLines.add(lineIndex + 1);
+      }
+      if (hasCommentStart && !hasCommentEnd) {
+        inHtmlComment = true;
+      } else if (hasCommentEnd) {
+        inHtmlComment = false;
+      }
+    });
+  }
+  return commentLines;
+}
+
+/**
+ * Find dangerous Unicode characters and return their details.
+ *
+ * @param {string} text string to inspect
+ * @returns {{ char: string, codePoint: string, index: number, kind: string }[]} matches
+ */
+export function findDangerousUnicodeMatches(text) {
+  if (!text || typeof text !== "string") {
+    return [];
+  }
+  const matches = [
+    ...findMatchesByPattern(text, BIDI_CHARS, "bidirectional-control"),
+    ...findMatchesByPattern(text, ZERO_WIDTH_CHARS, "zero-width"),
+    ...findMatchesByPattern(text, CONTROL_CHARS, "control"),
+  ];
+  matches.sort((left, right) => left.index - right.index);
+  return matches;
+}
+
+/**
+ * Scan a text blob for dangerous Unicode characters and summarize where they appear.
+ *
+ * @param {string} text text to inspect
+ * @param {{ syntax?: "markdown" | "text" | "yaml" }} [options] scan options
+ * @returns {{
+ *   codePoints: string[],
+ *   commentCodePoints: string[],
+ *   contexts: string[],
+ *   hasHiddenUnicode: boolean,
+ *   inComments: boolean,
+ *   lineNumbers: number[],
+ *   matches: { char: string, codePoint: string, index: number, kind: string, lineNumber: number, inComment: boolean }[],
+ * }} scan result
+ */
+export function scanTextForHiddenUnicode(text, options = {}) {
+  const matches = findDangerousUnicodeMatches(text);
+  if (!matches.length) {
+    return {
+      codePoints: [],
+      commentCodePoints: [],
+      contexts: [],
+      hasHiddenUnicode: false,
+      inComments: false,
+      lineNumbers: [],
+      matches: [],
+    };
+  }
+  const commentLines = commentLineNumbers(text, options.syntax || "text");
+  const enrichedMatches = matches.map((match) => {
+    const lineNumber = lineNumberForIndex(text, match.index);
+    return {
+      ...match,
+      inComment: commentLines.has(lineNumber),
+      lineNumber,
+    };
+  });
+  const commentCodePoints = [
+    ...new Set(
+      enrichedMatches
+        .filter((match) => match.inComment)
+        .map((match) => match.codePoint),
+    ),
+  ];
+  const contentCodePoints = [
+    ...new Set(
+      enrichedMatches
+        .filter((match) => !match.inComment)
+        .map((match) => match.codePoint),
+    ),
+  ];
+  const contexts = [];
+  if (commentCodePoints.length) {
+    contexts.push("comment");
+  }
+  if (contentCodePoints.length) {
+    contexts.push("content");
+  }
+  return {
+    codePoints: [...new Set(enrichedMatches.map((match) => match.codePoint))],
+    commentCodePoints,
+    contexts,
+    hasHiddenUnicode: true,
+    inComments: commentCodePoints.length > 0,
+    lineNumbers: [
+      ...new Set(enrichedMatches.map((match) => match.lineNumber)),
+    ].sort((left, right) => left - right),
+    matches: enrichedMatches,
+  };
+}

package/lib/helpers/unicodeScan.poku.js

@@ -0,0 +1,45 @@
+import { assert, describe, it } from "poku";
+
+import {
+  findDangerousUnicodeMatches,
+  scanTextForHiddenUnicode,
+} from "./unicodeScan.js";
+
+describe("findDangerousUnicodeMatches()", () => {
+  it("finds bidirectional and zero-width characters with code points", () => {
+    const matches = findDangerousUnicodeMatches("safe\u202Evalue\u200Bhidden");
+
+    assert.strictEqual(matches.length, 2);
+    assert.deepStrictEqual(
+      matches.map((match) => match.codePoint),
+      ["U+202E", "U+200B"],
+    );
+  });
+});
+
+describe("scanTextForHiddenUnicode()", () => {
+  it("tracks markdown comment context for hidden Unicode", () => {
+    const scan = scanTextForHiddenUnicode(
+      "Visible line\n<!-- sneaky \u200B marker -->\nTrailing line",
+      { syntax: "markdown" },
+    );
+
+    assert.strictEqual(scan.hasHiddenUnicode, true);
+    assert.strictEqual(scan.inComments, true);
+    assert.deepStrictEqual(scan.commentCodePoints, ["U+200B"]);
+    assert.deepStrictEqual(scan.lineNumbers, [2]);
+    assert.deepStrictEqual(scan.contexts, ["comment"]);
+  });
+
+  it("tracks yaml comment context for hidden Unicode", () => {
+    const scan = scanTextForHiddenUnicode(
+      "name: build\n# hidden \u202E comment\njobs:\n  test:\n    runs-on: ubuntu-latest",
+      { syntax: "yaml" },
+    );
+
+    assert.strictEqual(scan.hasHiddenUnicode, true);
+    assert.strictEqual(scan.inComments, true);
+    assert.deepStrictEqual(scan.commentCodePoints, ["U+202E"]);
+    assert.deepStrictEqual(scan.lineNumbers, [2]);
+  });
+});