@cyclonedx/cdxgen 12.2.1 → 12.3.0

package/lib/helpers/display.poku.js

@@ -1,8 +1,15 @@
 import { readFileSync } from "node:fs";
 
-import { it } from "poku";
+import esmock from "esmock";
+import { assert, it } from "poku";
+import sinon from "sinon";
 
-import { printDependencyTree } from "./display.js";
+import {
+  buildDependencyTreeLegendLines,
+  buildDependencyTreeLines,
+  printDependencyTree,
+} from "./display.js";
+import { REGISTRY_PROVENANCE_ICON } from "./provenanceUtils.js";
 
 it("print tree test", () => {
   const bomJson = JSON.parse(
@@ -10,3 +17,156 @@ it("print tree test", () => {
   );
   printDependencyTree(bomJson);
 });
+
+it("prints a provenance icon for registry-backed components", async () => {
+  const rows = [];
+  const consoleLogStub = sinon.stub(console, "log");
+  try {
+    const { printTable } = await esmock("./display.js", {
+      "./table.js": {
+        createStream: () => ({
+          end() {
+            // intentional no-op for stream stub
+          },
+          write(row) {
+            rows.push(row);
+          },
+        }),
+        table: sinon.stub().returns(""),
+      },
+      "./utils.js": {
+        isSecureMode: false,
+        safeExistsSync: sinon.stub(),
+        toCamel: sinon.stub(),
+      },
+    });
+
+    printTable(
+      {
+        components: [
+          {
+            group: "",
+            name: "left-pad",
+            properties: [
+              {
+                name: "cdx:npm:provenanceUrl",
+                value:
+                  "https://registry.npmjs.org/-/npm/v1/attestations/left-pad",
+              },
+            ],
+            type: "library",
+            version: "1.3.0",
+          },
+          {
+            group: "",
+            name: "lodash",
+            properties: [],
+            type: "library",
+            version: "4.17.21",
+          },
+        ],
+        dependencies: [],
+      },
+      undefined,
+      undefined,
+      "Found 1 trusted component.",
+    );
+
+    assert.strictEqual(rows[1][1], `${REGISTRY_PROVENANCE_ICON} left-pad`);
+    assert.strictEqual(rows[2][1], "lodash");
+    sinon.assert.calledWithExactly(
+      consoleLogStub,
+      "Found 1 trusted component.",
+    );
+    sinon.assert.calledWithExactly(
+      consoleLogStub,
+      `Legend: ${REGISTRY_PROVENANCE_ICON} = registry provenance or trusted publishing evidence`,
+    );
+    sinon.assert.calledWithExactly(
+      consoleLogStub,
+      `${REGISTRY_PROVENANCE_ICON} 1 component(s) include registry provenance or trusted publishing metadata.`,
+    );
+  } finally {
+    consoleLogStub.restore();
+  }
+});
+
+it("renders shared dependencies once while including dangling trees", () => {
+  const treeLines = buildDependencyTreeLines([
+    {
+      ref: "pkg:root/a@1.0.0",
+      dependsOn: ["pkg:shared/c@1.0.0"],
+    },
+    {
+      ref: "pkg:root/b@1.0.0",
+      dependsOn: ["pkg:shared/c@1.0.0"],
+    },
+    {
+      ref: "pkg:shared/c@1.0.0",
+      dependsOn: ["pkg:leaf/d@1.0.0"],
+    },
+    {
+      ref: "pkg:cycle/e@1.0.0",
+      dependsOn: ["pkg:cycle/f@1.0.0"],
+    },
+    {
+      ref: "pkg:cycle/f@1.0.0",
+      dependsOn: ["pkg:cycle/e@1.0.0"],
+    },
+  ]);
+
+  assert.deepStrictEqual(treeLines, [
+    "pkg:root/a@1.0.0",
+    "└── pkg:shared/c@1.0.0",
+    "    └── pkg:leaf/d@1.0.0",
+    "pkg:root/b@1.0.0",
+    "└── ⤴ pkg:shared/c@1.0.0",
+    "pkg:cycle/e@1.0.0",
+    "└── pkg:cycle/f@1.0.0",
+    "    └── ↺ pkg:cycle/e@1.0.0",
+  ]);
+  assert.deepStrictEqual(buildDependencyTreeLegendLines(treeLines), [
+    "Legend: ⤴ = already shown; ↺ = cycle",
+  ]);
+});
+
+it("omits empty providers while marking shared provides with an icon", () => {
+  const treeLines = buildDependencyTreeLines(
+    [
+      {
+        ref: "pkg:npm/app@1.0.0",
+        provides: ["crypto/aes", "crypto/sha256"],
+      },
+      {
+        ref: "pkg:npm/helper@1.0.0",
+        provides: ["crypto/sha256"],
+      },
+      {
+        ref: "pkg:npm/unused@1.0.0",
+      },
+    ],
+    "provides",
+  );
+
+  assert.deepStrictEqual(treeLines, [
+    "pkg:npm/app@1.0.0",
+    "├── crypto/aes",
+    "└── crypto/sha256",
+    "pkg:npm/helper@1.0.0",
+    "└── ⤴ crypto/sha256",
+  ]);
+  assert.deepStrictEqual(buildDependencyTreeLegendLines(treeLines), [
+    "Legend: ⤴ = already shown",
+  ]);
+});
+
+it("returns no legend lines when the dependency tree has no markers", () => {
+  assert.deepStrictEqual(
+    buildDependencyTreeLegendLines([
+      "pkg:root/a@1.0.0",
+      "└── pkg:shared/c@1.0.0",
+      "    └── pkg:leaf/d@1.0.0",
+    ]),
+    [],
+  );
+});

package/lib/helpers/exportUtils.js

@@ -0,0 +1,123 @@
+import path from "node:path";
+
+const SUPPORTED_EXPORT_FORMATS = new Set(["cyclonedx", "spdx"]);
+const EXPORT_FORMAT_ALIASES = {
+  cdx: "cyclonedx",
+  cyclonedx: "cyclonedx",
+  spdx: "spdx",
+  "spdx-json": "spdx",
+  spdx3: "spdx",
+  "spdx3-json": "spdx",
+};
+
+/**
+ * Normalize the requested export formats.
+ *
+ * @param {string|string[]|undefined|null} format Raw format value
+ * @returns {string[]} Normalized export formats
+ */
+export function normalizeOutputFormats(format) {
+  if (format === undefined || format === null || format === "") {
+    return [];
+  }
+  const values = Array.isArray(format) ? format : [format];
+  const normalized = new Set();
+  for (const value of values) {
+    if (!value) {
+      continue;
+    }
+    for (const token of `${value}`.split(",")) {
+      const normalizedToken = EXPORT_FORMAT_ALIASES[token.trim().toLowerCase()];
+      if (normalizedToken && SUPPORTED_EXPORT_FORMATS.has(normalizedToken)) {
+        normalized.add(normalizedToken);
+      }
+    }
+  }
+  return Array.from(normalized);
+}
+
+/**
+ * Derive the SPDX output path from a base output path.
+ *
+ * @param {string} outputPath Output path
+ * @returns {string} SPDX output path
+ */
+export function deriveSpdxOutputPath(outputPath) {
+  if (!outputPath) {
+    return "bom.spdx.json";
+  }
+  if (outputPath.endsWith(".spdx.json")) {
+    return outputPath;
+  }
+  if (outputPath.endsWith(".cdx.json")) {
+    return outputPath.replace(/\.cdx\.json$/u, ".spdx.json");
+  }
+  if (outputPath.endsWith(".json")) {
+    return outputPath.replace(/\.json$/u, ".spdx.json");
+  }
+  return `${outputPath}.spdx.json`;
+}
+
+/**
+ * Derive the CycloneDX output path from a base output path.
+ *
+ * @param {string} outputPath Output path
+ * @returns {string} CycloneDX output path
+ */
+export function deriveCycloneDxOutputPath(outputPath) {
+  if (!outputPath) {
+    return "bom.json";
+  }
+  if (outputPath.endsWith(".spdx.json")) {
+    return outputPath.replace(/\.spdx\.json$/u, ".cdx.json");
+  }
+  return outputPath;
+}
+
+/**
+ * Determine the final output plan for the requested export formats.
+ *
+ * @param {object} options CLI options
+ * @returns {{ formats: Set<string>, outputs: Record<string, string>, explicitFormat: boolean }} Output plan
+ */
+export function createOutputPlan(options) {
+  const explicitFormat =
+    options?.format !== undefined &&
+    options?.format !== null &&
+    options?.format !== "";
+  const requestedFormats = normalizeOutputFormats(options?.format);
+  const outputPath = options?.output || "bom.json";
+  const formats = new Set(
+    requestedFormats.length
+      ? requestedFormats
+      : [outputPath.endsWith(".spdx.json") ? "spdx" : "cyclonedx"],
+  );
+  const outputs = {};
+  if (formats.has("cyclonedx")) {
+    outputs.cyclonedx =
+      outputPath.endsWith(".spdx.json") && formats.size > 1
+        ? deriveCycloneDxOutputPath(outputPath)
+        : outputPath;
+  }
+  if (formats.has("spdx")) {
+    if (!formats.has("cyclonedx") || outputPath.endsWith(".spdx.json")) {
+      outputs.spdx =
+        outputPath === "bom.json"
+          ? deriveSpdxOutputPath(outputPath)
+          : outputPath;
+    } else {
+      outputs.spdx = deriveSpdxOutputPath(outputPath);
+    }
+  }
+  return { formats, outputs, explicitFormat };
+}
+
+/**
+ * Return the output directory for a planned export path.
+ *
+ * @param {string} outputPath Output path
+ * @returns {string} Output directory
+ */
+export function getOutputDirectory(outputPath) {
+  return path.dirname(outputPath);
+}

package/lib/helpers/exportUtils.poku.js

@@ -0,0 +1,60 @@
+import { assert, describe, it } from "poku";
+
+import {
+  createOutputPlan,
+  deriveCycloneDxOutputPath,
+  deriveSpdxOutputPath,
+  normalizeOutputFormats,
+} from "./exportUtils.js";
+
+describe("exportUtils", () => {
+  it("normalizes comma-separated export formats", () => {
+    assert.deepStrictEqual(normalizeOutputFormats("cyclonedx,spdx-json"), [
+      "cyclonedx",
+      "spdx",
+    ]);
+  });
+
+  it("normalizes repeated format flags", () => {
+    assert.deepStrictEqual(normalizeOutputFormats(["cyclonedx", "spdx"]), [
+      "cyclonedx",
+      "spdx",
+    ]);
+  });
+
+  it("derives SPDX and CycloneDX sibling paths", () => {
+    assert.strictEqual(
+      deriveSpdxOutputPath("/tmp/bom.cdx.json"),
+      "/tmp/bom.spdx.json",
+    );
+    assert.strictEqual(
+      deriveCycloneDxOutputPath("/tmp/bom.spdx.json"),
+      "/tmp/bom.cdx.json",
+    );
+  });
+
+  it("chooses SPDX automatically for .spdx.json outputs", () => {
+    const plan = createOutputPlan({ output: "/tmp/app.spdx.json" });
+    assert.strictEqual(plan.formats.has("spdx"), true);
+    assert.strictEqual(plan.formats.has("cyclonedx"), false);
+    assert.strictEqual(plan.outputs.spdx, "/tmp/app.spdx.json");
+  });
+
+  it("creates sibling outputs for dual exports", () => {
+    const plan = createOutputPlan({
+      format: "cyclonedx,spdx",
+      output: "/tmp/app.cdx.json",
+    });
+    assert.strictEqual(plan.outputs.cyclonedx, "/tmp/app.cdx.json");
+    assert.strictEqual(plan.outputs.spdx, "/tmp/app.spdx.json");
+  });
+
+  it("creates sibling outputs for repeated format flags", () => {
+    const plan = createOutputPlan({
+      format: ["cyclonedx", "spdx"],
+      output: "/tmp/app.cdx.json",
+    });
+    assert.strictEqual(plan.outputs.cyclonedx, "/tmp/app.cdx.json");
+    assert.strictEqual(plan.outputs.spdx, "/tmp/app.spdx.json");
+  });
+});

package/lib/helpers/formulationParsers.js

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
 import process from "node:process";
 
 import { v4 as uuidv4 } from "uuid";
@@ -16,8 +18,67 @@ import {
   gitTreeHashes,
   listFiles,
 } from "./envcontext.js";
+import { scanTextForHiddenUnicode } from "./unicodeScan.js";
 import { getAllFiles } from "./utils.js";
 
+const README_PATTERNS = [
+  "**/README*.{adoc,asciidoc,markdown,md,mdx,rst,txt}",
+  "**/readme*.{adoc,asciidoc,markdown,md,mdx,rst,txt}",
+];
+
+function buildReadmeSecurityComponents(discoveryPath, options) {
+  const matchedFiles = [];
+  for (const pattern of README_PATTERNS) {
+    const found = getAllFiles(discoveryPath, pattern, options);
+    if (found?.length) {
+      matchedFiles.push(...found);
+    }
+  }
+  const components = [];
+  for (const filePath of [...new Set(matchedFiles)]) {
+    let raw;
+    try {
+      raw = readFileSync(filePath, { encoding: "utf-8" });
+    } catch {
+      continue;
+    }
+    const scan = scanTextForHiddenUnicode(raw, { syntax: "markdown" });
+    if (!scan.hasHiddenUnicode) {
+      continue;
+    }
+    const properties = [
+      { name: "SrcFile", value: filePath },
+      { name: "cdx:file:kind", value: "readme" },
+      { name: "cdx:file:hasHiddenUnicode", value: "true" },
+      {
+        name: "cdx:file:hiddenUnicodeCodePoints",
+        value: scan.codePoints.join(","),
+      },
+      {
+        name: "cdx:file:hiddenUnicodeLineNumbers",
+        value: scan.lineNumbers.join(","),
+      },
+    ];
+    if (scan.inComments) {
+      properties.push({
+        name: "cdx:file:hiddenUnicodeInComments",
+        value: "true",
+      });
+      properties.push({
+        name: "cdx:file:hiddenUnicodeCommentCodePoints",
+        value: scan.commentCodePoints.join(","),
+      });
+    }
+    components.push({
+      "bom-ref": `file:${filePath}`,
+      name: basename(filePath),
+      properties,
+      type: "file",
+    });
+  }
+  return components;
+}
+
 /**
  * The parser registry. Pre-populated with the five built-in CI system parsers.
  *
@@ -291,6 +352,14 @@ export function addFormulationSection(filePath, options, context = {}) {
     components = components.concat(ciComponents);
   }
 
+  const readmeSecurityComponents = buildReadmeSecurityComponents(
+    discoveryPath,
+    options,
+  );
+  if (readmeSecurityComponents.length) {
+    components = components.concat(readmeSecurityComponents);
+  }
+
   // ── Environment variables ─────────────────────────────────────────────────
   let environmentVars = gitBranch?.length
     ? [{ name: "GIT_BRANCH", value: gitBranch }]

package/lib/helpers/formulationParsers.poku.js

@@ -0,0 +1,44 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { assert, describe, it } from "poku";
+
+import { addFormulationSection } from "./formulationParsers.js";
+
+function getProp(obj, name) {
+  return obj?.properties?.find((property) => property.name === name)?.value;
+}
+
+describe("addFormulationSection()", () => {
+  it("adds README file components when hidden Unicode is detected", () => {
+    const tmpDir = mkdtempSync(path.join(os.tmpdir(), "cdxgen-formulation-"));
+    writeFileSync(
+      path.join(tmpDir, "README.md"),
+      "# Demo\n<!-- hidden \u200B comment -->\nContent",
+    );
+
+    try {
+      const result = addFormulationSection(tmpDir, { specVersion: 1.7 });
+      const formulation = result.formulation[0];
+      const readmeComponent = formulation.components.find(
+        (component) => getProp(component, "cdx:file:kind") === "readme",
+      );
+      assert.ok(readmeComponent, "expected README formulation component");
+      assert.strictEqual(
+        getProp(readmeComponent, "cdx:file:hasHiddenUnicode"),
+        "true",
+      );
+      assert.strictEqual(
+        getProp(readmeComponent, "cdx:file:hiddenUnicodeInComments"),
+        "true",
+      );
+      assert.match(
+        getProp(readmeComponent, "cdx:file:hiddenUnicodeCodePoints"),
+        /U\+200B/,
+      );
+    } finally {
+      rmSync(tmpDir, { force: true, recursive: true });
+    }
+  });
+});

package/lib/helpers/gtfobins.js

@@ -0,0 +1,189 @@
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+import { dirNameStr, safeExistsSync } from "./utils.js";
+
+const GTFOBINS_INDEX_FILE = join(dirNameStr, "data", "gtfobins-index.json");
+const GTFOBINS_REFERENCE_PREFIX = "https://gtfobins.github.io/gtfobins/";
+const PRIVILEGED_CONTEXTS = ["sudo", "suid", "capabilities"];
+const CONTAINER_ESCAPE_HELPERS = new Set([
+  "chroot",
+  "ctr",
+  "docker",
+  "kubectl",
+  "mount",
+  "nsenter",
+  "tar",
+  "unshare",
+]);
+const DIRECT_ALIASES = new Map([["nodejs", "node"]]);
+const VERSIONED_ALIASES = [
+  { pattern: /^python(?:\d+(?:\.\d+)*)?$/i, target: "python" },
+  { pattern: /^perl(?:\d+(?:\.\d+)*)?$/i, target: "perl" },
+  { pattern: /^ruby(?:\d+(?:\.\d+)*)?$/i, target: "ruby" },
+  { pattern: /^php(?:\d+(?:\.\d+)*)?$/i, target: "php" },
+  { pattern: /^lua(?:\d+(?:\.\d+)*)?$/i, target: "lua" },
+  { pattern: /^node(?:\d+(?:\.\d+)*)?$/i, target: "node" },
+];
+
+const GTFOBINS_INDEX = loadGtfoBinsIndex();
+
+function loadGtfoBinsIndex() {
+  if (!safeExistsSync(GTFOBINS_INDEX_FILE)) {
+    return { entries: {}, source: GTFOBINS_REFERENCE_PREFIX, sourceRef: "" };
+  }
+  try {
+    return JSON.parse(readFileSync(GTFOBINS_INDEX_FILE, "utf8"));
+  } catch {
+    return { entries: {}, source: GTFOBINS_REFERENCE_PREFIX, sourceRef: "" };
+  }
+}
+
+function resolveCandidateName(candidate) {
+  if (!candidate || typeof candidate !== "string") {
+    return undefined;
+  }
+  const trimmed = basename(candidate.trim());
+  if (!trimmed) {
+    return undefined;
+  }
+  const normalized = trimmed.toLowerCase();
+  if (GTFOBINS_INDEX.entries?.[trimmed]) {
+    return { canonicalName: trimmed, matchSource: "basename" };
+  }
+  if (GTFOBINS_INDEX.entries?.[normalized]) {
+    return { canonicalName: normalized, matchSource: "basename" };
+  }
+  const directAlias = DIRECT_ALIASES.get(normalized);
+  if (directAlias && GTFOBINS_INDEX.entries?.[directAlias]) {
+    return { canonicalName: directAlias, matchSource: "alias" };
+  }
+  for (const aliasRule of VERSIONED_ALIASES) {
+    if (
+      aliasRule.pattern.test(normalized) &&
+      GTFOBINS_INDEX.entries?.[aliasRule.target]
+    ) {
+      return { canonicalName: aliasRule.target, matchSource: "alias" };
+    }
+  }
+  return undefined;
+}
+
+function deriveRiskTags(entry, canonicalName) {
+  const functions = new Set(entry?.functions || []);
+  const contexts = new Set(entry?.contexts || []);
+  const riskTags = new Set();
+  const hasExecPrimitive =
+    functions.has("shell") ||
+    functions.has("command") ||
+    functions.has("reverse-shell") ||
+    functions.has("bind-shell");
+  const hasNetworkPrimitive =
+    functions.has("upload") ||
+    functions.has("download") ||
+    functions.has("reverse-shell") ||
+    functions.has("bind-shell");
+  if (functions.has("privilege-escalation")) {
+    riskTags.add("privilege-escalation");
+  }
+  if (
+    contexts.has("sudo") ||
+    contexts.has("suid") ||
+    contexts.has("capabilities")
+  ) {
+    riskTags.add("privilege-escalation");
+  }
+  if (hasExecPrimitive && hasNetworkPrimitive) {
+    riskTags.add("lateral-movement");
+  }
+  if (functions.has("upload") || functions.has("file-read")) {
+    riskTags.add("data-exfiltration");
+  }
+  if (functions.has("file-write") || functions.has("library-load")) {
+    riskTags.add("persistence");
+  }
+  if (
+    CONTAINER_ESCAPE_HELPERS.has(canonicalName) &&
+    (hasExecPrimitive ||
+      functions.has("privilege-escalation") ||
+      functions.has("library-load"))
+  ) {
+    riskTags.add("container-escape");
+  }
+  return Array.from(riskTags).sort();
+}
+
+export function getGtfoBinsMetadata(name, linkedName) {
+  const directMatch = resolveCandidateName(name);
+  if (directMatch) {
+    const entry = GTFOBINS_INDEX.entries[directMatch.canonicalName];
+    return {
+      canonicalName: directMatch.canonicalName,
+      contexts: entry.contexts,
+      functions: entry.functions,
+      matchSource: directMatch.matchSource,
+      mitreTechniques: entry.mitreTechniques,
+      privilegedContexts: entry.contexts.filter((context) =>
+        PRIVILEGED_CONTEXTS.includes(context),
+      ),
+      reference: `${GTFOBINS_REFERENCE_PREFIX}${encodeURIComponent(directMatch.canonicalName)}/`,
+      riskTags: deriveRiskTags(entry, directMatch.canonicalName),
+      source: GTFOBINS_INDEX.source,
+      sourceRef: GTFOBINS_INDEX.sourceRef,
+    };
+  }
+  const linkedMatch = resolveCandidateName(linkedName);
+  if (!linkedMatch) {
+    return undefined;
+  }
+  const entry = GTFOBINS_INDEX.entries[linkedMatch.canonicalName];
+  return {
+    canonicalName: linkedMatch.canonicalName,
+    contexts: entry.contexts,
+    functions: entry.functions,
+    matchSource: "symlink",
+    mitreTechniques: entry.mitreTechniques,
+    privilegedContexts: entry.contexts.filter((context) =>
+      PRIVILEGED_CONTEXTS.includes(context),
+    ),
+    reference: `${GTFOBINS_REFERENCE_PREFIX}${encodeURIComponent(linkedMatch.canonicalName)}/`,
+    riskTags: deriveRiskTags(entry, linkedMatch.canonicalName),
+    source: GTFOBINS_INDEX.source,
+    sourceRef: GTFOBINS_INDEX.sourceRef,
+  };
+}
+
+export function createGtfoBinsProperties(name, linkedName) {
+  const metadata = getGtfoBinsMetadata(name, linkedName);
+  if (!metadata) {
+    return [];
+  }
+  const properties = [
+    { name: "cdx:gtfobins:matched", value: "true" },
+    { name: "cdx:gtfobins:name", value: metadata.canonicalName },
+    { name: "cdx:gtfobins:matchSource", value: metadata.matchSource },
+    { name: "cdx:gtfobins:functions", value: metadata.functions.join(",") },
+    { name: "cdx:gtfobins:contexts", value: metadata.contexts.join(",") },
+    { name: "cdx:gtfobins:reference", value: metadata.reference },
+    { name: "cdx:gtfobins:sourceRef", value: metadata.sourceRef || "" },
+  ];
+  if (metadata.mitreTechniques.length) {
+    properties.push({
+      name: "cdx:gtfobins:mitreTechniques",
+      value: metadata.mitreTechniques.join(","),
+    });
+  }
+  if (metadata.privilegedContexts.length) {
+    properties.push({
+      name: "cdx:gtfobins:privilegedContexts",
+      value: metadata.privilegedContexts.join(","),
+    });
+  }
+  if (metadata.riskTags.length) {
+    properties.push({
+      name: "cdx:gtfobins:riskTags",
+      value: metadata.riskTags.join(","),
+    });
+  }
+  return properties;
+}