@cyclonedx/cdxgen 12.3.3 → 12.4.1

package/lib/helpers/asarutils.poku.js

@@ -0,0 +1,443 @@
+import { createHash } from "node:crypto";
+import * as nodeFs from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import esmock from "esmock";
+import { assert, describe, it } from "poku";
+import sinon from "sinon";
+
+import {
+  createAsarFixture,
+  writeElectronAsarIntegrityPlist,
+} from "../../test/helpers/asar-fixture-builder.js";
+import {
+  cleanupAsarTempDir,
+  extractAsarToTempDir,
+  listAsarEntries,
+  parseAsarArchive,
+  readAsarArchiveHeaderSync,
+  rewriteExtractedArchivePaths,
+} from "./asarutils.js";
+import { safeRmSync } from "./utils.js";
+
+const baseTempDir = mkdtempSync(join(tmpdir(), "cdxgen-asar-poku-"));
+
+function align4(value) {
+  return value + ((4 - (value % 4)) % 4);
+}
+
+function makeStringPickle(value) {
+  const valueBuffer = Buffer.from(value, "utf8");
+  const alignedStringLength = align4(valueBuffer.length);
+  const payloadLength = 4 + alignedStringLength;
+  const buffer = Buffer.alloc(4 + payloadLength);
+  buffer.writeUInt32LE(payloadLength, 0);
+  buffer.writeInt32LE(valueBuffer.length, 4);
+  valueBuffer.copy(buffer, 8);
+  return buffer;
+}
+
+function makeSizePickle(value) {
+  const buffer = Buffer.alloc(8);
+  buffer.writeUInt32LE(4, 0);
+  buffer.writeUInt32LE(value, 4);
+  return buffer;
+}
+
+function rewriteArchiveHeaderSync(archivePath, transformHeader) {
+  const archiveBuffer = readFileSync(archivePath);
+  const headerPickleSize = archiveBuffer.readUInt32LE(4);
+  const headerBuffer = archiveBuffer.subarray(8, 8 + headerPickleSize);
+  const headerStringLength = headerBuffer.readInt32LE(4);
+  const headerString = headerBuffer.toString("utf8", 8, 8 + headerStringLength);
+  const nextHeader = transformHeader(JSON.parse(headerString));
+  const nextHeaderPickle = makeStringPickle(JSON.stringify(nextHeader));
+  writeFileSync(
+    archivePath,
+    Buffer.concat([
+      makeSizePickle(nextHeaderPickle.length),
+      nextHeaderPickle,
+      archiveBuffer.subarray(8 + headerPickleSize),
+    ]),
+  );
+}
+
+process.on("exit", () => {
+  safeRmSync(baseTempDir, { force: true, recursive: true });
+});
+
+describe("extractAsarToTempDir()", () => {
+  it("returns undefined when dry-run blocks ASAR extraction", async () => {
+    const safeExtractArchive = sinon.stub().resolves(false);
+    const { extractAsarToTempDir: extractAsarToTempDirMocked } = await esmock(
+      "./asarutils.js",
+      {
+        "./utils.js": {
+          DEBUG_MODE: false,
+          getTmpDir: sinon.stub().returns("/tmp"),
+          isDryRun: false,
+          recordActivity: sinon.stub(),
+          safeCopyFileSync: sinon.stub(),
+          safeExtractArchive,
+          safeMkdirSync: sinon.stub(),
+          safeMkdtempSync: sinon.stub().returns("/tmp/asar-deps-test"),
+          safeRmSync: sinon.stub(),
+          safeWriteSync: sinon.stub(),
+        },
+      },
+    );
+
+    const extractedDir = await extractAsarToTempDirMocked("/tmp/sample.asar");
+
+    assert.strictEqual(extractedDir, undefined);
+    sinon.assert.calledOnce(safeExtractArchive);
+  });
+});
+
+describe("parseAsarArchive()", () => {
+  it("catalogs file inventory, hashes, evidence, and security-sensitive properties", async () => {
+    const archivePath = join(baseTempDir, "fixture.asar");
+    createAsarFixture(archivePath, {
+      corruptIntegrityPaths: ["config/settings.json"],
+      executablePaths: ["scripts/postinstall.js"],
+      symlinks: {
+        "config-link": "config/settings.json",
+      },
+      unpackedPaths: ["native/addon.node"],
+    });
+
+    const analysis = await parseAsarArchive(archivePath, {});
+    const entryList = listAsarEntries(archivePath);
+
+    assert.ok(entryList.entries.some((entry) => entry.path === "config-link"));
+    assert.strictEqual(analysis.parentComponent.name, "Sample Electron App");
+    assert.strictEqual(
+      analysis.parentComponent.purl,
+      "pkg:npm/sample-electron-app@1.2.3",
+    );
+    assert.strictEqual(
+      analysis.summary.integrityMismatchCount,
+      1,
+      "expected one mismatched declared integrity hash",
+    );
+    assert.ok(analysis.summary.capabilities.includes("fileAccess"));
+    assert.ok(analysis.summary.capabilities.includes("network"));
+    assert.ok(analysis.summary.capabilities.includes("hardware"));
+    assert.ok(analysis.summary.capabilities.includes("dynamicFetch"));
+    assert.ok(analysis.summary.capabilities.includes("dynamicImport"));
+    assert.strictEqual(analysis.summary.hasEval, true);
+    const archiveProps = analysis.parentComponent.properties;
+    assert.strictEqual(
+      archiveProps.find((property) => property.name === "cdx:asar:hasEval")
+        ?.value,
+      "true",
+    );
+    assert.strictEqual(
+      archiveProps.find(
+        (property) => property.name === "cdx:asar:hasNativeAddons",
+      )?.value,
+      "true",
+    );
+    assert.strictEqual(
+      archiveProps.find(
+        (property) => property.name === "cdx:asar:hasIntegrityMismatch",
+      )?.value,
+      "true",
+    );
+
+    const mainFileComponent = analysis.components.find((component) =>
+      component.properties?.some(
+        (property) =>
+          property.name === "cdx:asar:path" && property.value === "src/main.js",
+      ),
+    );
+    assert.ok(mainFileComponent, "expected src/main.js file component");
+    assert.ok(mainFileComponent.hashes?.length, "expected SHA-256 hash");
+    assert.strictEqual(
+      mainFileComponent.evidence?.occurrences?.[0]?.location,
+      `${archivePath}#/src/main.js`,
+    );
+    assert.strictEqual(
+      mainFileComponent.properties.find(
+        (property) => property.name === "cdx:asar:js:hasDynamicFetch",
+      )?.value,
+      "true",
+    );
+    assert.strictEqual(
+      mainFileComponent.properties.find(
+        (property) => property.name === "cdx:asar:js:capability:hardware",
+      )?.value,
+      "true",
+    );
+
+    const unpackedComponent = analysis.components.find((component) =>
+      component.properties?.some(
+        (property) =>
+          property.name === "cdx:asar:path" &&
+          property.value === "native/addon.node",
+      ),
+    );
+    assert.ok(unpackedComponent, "expected native addon component");
+    assert.strictEqual(
+      unpackedComponent.properties.find(
+        (property) => property.name === "cdx:asar:unpacked",
+      )?.value,
+      "true",
+    );
+  });
+
+  it("extracts ASAR archives and rewrites extracted source paths back to archive paths", async () => {
+    const archivePath = join(baseTempDir, "fixture-extract.asar");
+    createAsarFixture(archivePath, {
+      unpackedPaths: ["native/addon.node"],
+    });
+
+    const extractedDir = await extractAsarToTempDir(archivePath);
+    assert.ok(extractedDir, "expected extraction temp dir");
+    assert.ok(existsSync(join(extractedDir, "src", "main.js")));
+    assert.ok(existsSync(join(extractedDir, "native", "addon.node")));
+
+    const component = {
+      evidence: {
+        identity: {
+          methods: [
+            {
+              confidence: 1,
+              technique: "manifest-analysis",
+              value: join(extractedDir, "package.json"),
+            },
+          ],
+        },
+        occurrences: [
+          {
+            location: join(extractedDir, "src", "main.js"),
+          },
+        ],
+      },
+      properties: [
+        {
+          name: "SrcFile",
+          value: join(
+            extractedDir,
+            "node_modules",
+            "sketchy-addon",
+            "package.json",
+          ),
+        },
+      ],
+    };
+    rewriteExtractedArchivePaths(component, extractedDir, archivePath);
+    assert.strictEqual(
+      component.properties[0].value,
+      `${archivePath}#/node_modules/sketchy-addon/package.json`,
+    );
+    assert.strictEqual(
+      component.evidence.identity.methods[0].value,
+      `${archivePath}#/package.json`,
+    );
+    assert.strictEqual(
+      component.evidence.occurrences[0].location,
+      `${archivePath}#/src/main.js`,
+    );
+
+    cleanupAsarTempDir(extractedDir);
+    assert.ok(!existsSync(extractedDir), "expected extracted temp dir cleanup");
+  });
+
+  it("verifies Electron ASAR signing metadata and emits a crypto component", async () => {
+    const appDir = join(baseTempDir, "Signed.app");
+    const archivePath = join(
+      appDir,
+      "Contents",
+      "Resources",
+      "app & signed.asar",
+    );
+    mkdirSync(join(appDir, "Contents", "Resources"), { recursive: true });
+    createAsarFixture(archivePath);
+    const { headerString } = readAsarArchiveHeaderSync(archivePath);
+    const headerHash = createHash("sha256")
+      .update(headerString, "utf8")
+      .digest("hex");
+    writeElectronAsarIntegrityPlist(join(appDir, "Contents", "Info.plist"), {
+      "Resources/app & signed.asar": {
+        algorithm: "SHA256",
+        hash: headerHash,
+      },
+    });
+
+    const analysis = await parseAsarArchive(archivePath, { specVersion: 1.7 });
+    const signingComponent = analysis.components.find(
+      (component) =>
+        component.type === "cryptographic-asset" &&
+        component.properties?.some(
+          (property) =>
+            property.name === "cdx:asar:signingVerified" &&
+            property.value === "true",
+        ),
+    );
+    assert.strictEqual(
+      analysis.parentComponent.properties.find(
+        (property) => property.name === "cdx:asar:hasSigningMetadata",
+      )?.value,
+      "true",
+    );
+    assert.strictEqual(
+      analysis.parentComponent.properties.find(
+        (property) => property.name === "cdx:asar:signingVerified",
+      )?.value,
+      "true",
+    );
+    assert.strictEqual(
+      analysis.parentComponent.properties.find(
+        (property) => property.name === "cdx:asar:signingScope",
+      )?.value,
+      "header-only",
+    );
+    assert.ok(signingComponent, "expected ASAR signing crypto component");
+    assert.strictEqual(
+      signingComponent.properties.find(
+        (property) => property.name === "cdx:asar:signingScope",
+      )?.value,
+      "header-only",
+    );
+    assert.ok(
+      analysis.dependencies.some(
+        (dependency) =>
+          dependency.ref === analysis.parentComponent["bom-ref"] &&
+          dependency.dependsOn.includes(signingComponent["bom-ref"]),
+      ),
+      "expected parent archive to depend on the signing component",
+    );
+  });
+
+  it("rejects ASAR headers with oversized file entries", async () => {
+    const archivePath = join(baseTempDir, "fixture-oversized.asar");
+    createAsarFixture(archivePath, {
+      extraEntries: {
+        "huge.bin": {
+          content: "x",
+          size: 256 * 1024 * 1024 + 1,
+        },
+      },
+    });
+
+    await assert.rejects(
+      () => parseAsarArchive(archivePath, {}),
+      /Invalid ASAR file entry/,
+    );
+  });
+
+  it("rejects ASAR entries with offsets beyond the safe read limit", async () => {
+    const archivePath = join(baseTempDir, "fixture-offset.asar");
+    createAsarFixture(archivePath, {
+      extraEntries: {
+        "too-far.bin": {
+          content: "x",
+          offset: Number.MAX_SAFE_INTEGER + 10,
+          size: 1,
+        },
+      },
+    });
+
+    await assert.rejects(
+      () => parseAsarArchive(archivePath, {}),
+      /offset exceeds the safe read limit/,
+    );
+  });
+
+  it("rejects ASAR headers with excessive nesting depth", async () => {
+    const archivePath = join(baseTempDir, "fixture-deep.asar");
+    const deeplyNestedPath = `${Array.from({ length: 260 }, (_, index) => `d${index}`).join("/")}/payload.txt`;
+    createAsarFixture(archivePath, {
+      extraEntries: {
+        [deeplyNestedPath]: {
+          content: "payload",
+        },
+      },
+    });
+
+    await assert.rejects(
+      () => parseAsarArchive(archivePath, {}),
+      /nesting exceeds 256 levels/,
+    );
+  });
+
+  it("rejects ASAR headers with conflicting entry kinds", async () => {
+    const archivePath = join(baseTempDir, "fixture-conflicting-kinds.asar");
+    createAsarFixture(archivePath);
+    rewriteArchiveHeaderSync(archivePath, (header) => {
+      header.files["bad-link"] = {
+        files: {},
+        link: "src/main.js",
+      };
+      return header;
+    });
+
+    await assert.rejects(
+      () => parseAsarArchive(archivePath, {}),
+      /Invalid ASAR symlink entry/,
+    );
+  });
+
+  it("rejects symlinks that escape the extraction root", async () => {
+    const archivePath = join(baseTempDir, "fixture-link-escape.asar");
+    createAsarFixture(archivePath, {
+      symlinks: {
+        "escape-link": "../../outside.txt",
+      },
+    });
+
+    const extractedDir = await extractAsarToTempDir(archivePath);
+    assert.strictEqual(extractedDir, undefined);
+  });
+
+  it("rejects circular symlink chains during extraction", async () => {
+    const archivePath = join(baseTempDir, "fixture-link-cycle.asar");
+    createAsarFixture(archivePath, {
+      symlinks: {
+        a: "b",
+        b: "a",
+      },
+    });
+
+    const extractedDir = await extractAsarToTempDir(archivePath);
+    assert.strictEqual(extractedDir, undefined);
+  });
+
+  it("reuses one packed-entry file descriptor per parse and extraction pass", async () => {
+    const archivePath = join(baseTempDir, "fixture-open-reuse.asar");
+    createAsarFixture(archivePath, {
+      unpackedPaths: ["native/addon.node"],
+    });
+    const openSync = sinon.spy((...args) => nodeFs.openSync(...args));
+    const closeSync = sinon.spy((...args) => nodeFs.closeSync(...args));
+    const {
+      cleanupAsarTempDir: cleanupAsarTempDirMocked,
+      extractAsarToTempDir: extractAsarToTempDirMocked,
+      parseAsarArchive: parseAsarArchiveMocked,
+    } = await esmock("./asarutils.js", {
+      "node:fs": {
+        ...nodeFs,
+        closeSync,
+        openSync,
+      },
+    });
+
+    await parseAsarArchiveMocked(archivePath, {});
+    const extractedDir = await extractAsarToTempDirMocked(archivePath);
+
+    assert.ok(extractedDir, "expected extraction temp dir");
+    assert.strictEqual(openSync.callCount, 4);
+    assert.strictEqual(closeSync.callCount, 4);
+
+    cleanupAsarTempDirMocked(extractedDir);
+  });
+});

package/lib/helpers/auditCategories.js

@@ -1,5 +1,17 @@
+export const HBOM_AUDIT_CATEGORIES = Object.freeze([
+  "hbom-security",
+  "hbom-performance",
+  "hbom-compliance",
+]);
+
+export const HOST_TOPOLOGY_AUDIT_CATEGORIES = Object.freeze(["host-topology"]);
+
+export const DEFAULT_HBOM_AUDIT_CATEGORIES = HBOM_AUDIT_CATEGORIES.join(",");
+
 export const BOM_AUDIT_CATEGORY_ALIASES = Object.freeze({
   "ai-inventory": ["ai-agent", "mcp-server"],
+  hbom: [...HBOM_AUDIT_CATEGORIES],
+  host: [...HBOM_AUDIT_CATEGORIES, ...HOST_TOPOLOGY_AUDIT_CATEGORIES],
 });
 
 function uniqueNonEmptyCategories(categories) {

package/lib/helpers/auditCategories.poku.js

@@ -0,0 +1,32 @@
+import { assert, describe, it } from "poku";
+
+import {
+  expandBomAuditCategories,
+  validateBomAuditCategories,
+} from "./auditCategories.js";
+
+describe("auditCategories", () => {
+  it("keeps host-topology as a direct category", () => {
+    assert.deepStrictEqual(expandBomAuditCategories("host-topology"), [
+      "host-topology",
+    ]);
+  });
+
+  it("expands the host alias to the HBOM packs plus host-topology", () => {
+    assert.deepStrictEqual(expandBomAuditCategories("host"), [
+      "hbom-security",
+      "hbom-performance",
+      "hbom-compliance",
+      "host-topology",
+    ]);
+  });
+
+  it("accepts host-topology during validation", () => {
+    const validation = validateBomAuditCategories("host-topology", [
+      { category: "host-topology" },
+      { category: "hbom-security" },
+    ]);
+    assert.deepStrictEqual(validation.categories, ["host-topology"]);
+    assert.deepStrictEqual(validation.expandedCategories, ["host-topology"]);
+  });
+});

package/lib/helpers/bomUtils.js

@@ -1,8 +1,16 @@
 const SPDX_CONTEXT_PREFIX = "https://spdx.org/rdf/";
 const CYCLONEDX_FORMAT = "CycloneDX";
+const LEGACY_CYCLONEDX_ROOT_KEY = "bomFormat";
+const MODERN_CYCLONEDX_ROOT_KEY = "specFormat";
 const BOM_FORMAT_CYCLONEDX = "cyclonedx";
 const BOM_FORMAT_SPDX = "spdx";
 const BOM_FORMAT_UNKNOWN = "unknown";
+const CYCLONEDX_SPEC_VERSION_PATTERN = /^(\d+)(?:\.(\d+))?$/u;
+const CYCLONEDX_FORMAT_KEYS = new Set([
+  LEGACY_CYCLONEDX_ROOT_KEY,
+  MODERN_CYCLONEDX_ROOT_KEY,
+  "specVersion",
+]);
 
 export const isSpdxJsonLd = (bomJson) =>
   Boolean(
@@ -11,8 +19,154 @@ export const isSpdxJsonLd = (bomJson) =>
       bomJson["@graph"].some((element) => element?.type === "SpdxDocument"),
   );
 
+const parseCycloneDxSpecVersion = (specVersion) => {
+  const match = `${specVersion ?? ""}`
+    .trim()
+    .match(CYCLONEDX_SPEC_VERSION_PATTERN);
+  if (!match) {
+    return undefined;
+  }
+  return {
+    major: Number.parseInt(match[1], 10),
+    minor: Number.parseInt(match[2] || "0", 10),
+    minorText: match[2] || "0",
+  };
+};
+
+export const normalizeCycloneDxSpecVersion = (specVersion) => {
+  const parsed = parseCycloneDxSpecVersion(specVersion);
+  if (!parsed) {
+    return undefined;
+  }
+  return Number(`${parsed.major}.${parsed.minor}`);
+};
+
+export const toCycloneDxSpecVersionString = (specVersion) => {
+  const parsed = parseCycloneDxSpecVersion(specVersion);
+  if (!parsed) {
+    return undefined;
+  }
+  if (typeof specVersion === "string" && parsed.minorText !== "0") {
+    return `${parsed.major}.${parsed.minorText}`;
+  }
+  return `${parsed.major}.${parsed.minor}`;
+};
+
+export const isCycloneDxSpecVersionAtLeast = (specVersion, minimumVersion) => {
+  const parsedSpecVersion = parseCycloneDxSpecVersion(specVersion);
+  const parsedMinimumVersion = parseCycloneDxSpecVersion(minimumVersion);
+  if (!parsedSpecVersion || !parsedMinimumVersion) {
+    return false;
+  }
+  if (parsedSpecVersion.major !== parsedMinimumVersion.major) {
+    return parsedSpecVersion.major > parsedMinimumVersion.major;
+  }
+  return parsedSpecVersion.minor >= parsedMinimumVersion.minor;
+};
+
+export const isCycloneDx20SpecVersion = (specVersion) =>
+  isCycloneDxSpecVersionAtLeast(specVersion, 2);
+
+export const getCycloneDxRootFormatKey = (specVersionOrBom) => {
+  const specVersion =
+    specVersionOrBom && typeof specVersionOrBom === "object"
+      ? specVersionOrBom.specVersion
+      : specVersionOrBom;
+  return isCycloneDx20SpecVersion(specVersion)
+    ? MODERN_CYCLONEDX_ROOT_KEY
+    : LEGACY_CYCLONEDX_ROOT_KEY;
+};
+
+export const getCycloneDxFormat = (bomJson) =>
+  bomJson?.specFormat || bomJson?.bomFormat;
+
+export const hasCycloneDxFormat = (bomJson) =>
+  getCycloneDxFormat(bomJson) === CYCLONEDX_FORMAT;
+
 export const isCycloneDxBom = (bomJson) =>
-  bomJson?.bomFormat === CYCLONEDX_FORMAT && Boolean(bomJson?.specVersion);
+  hasCycloneDxFormat(bomJson) &&
+  normalizeCycloneDxSpecVersion(bomJson?.specVersion) !== undefined;
+
+const rewriteCycloneDxRootFields = (
+  bomJson,
+  rootKey,
+  specVersion,
+  preserveLegacyBomFormat,
+) => {
+  const remainingEntries = Object.entries(bomJson).filter(
+    ([key]) => !CYCLONEDX_FORMAT_KEYS.has(key),
+  );
+  for (const key of Object.keys(bomJson)) {
+    delete bomJson[key];
+  }
+  if (rootKey === LEGACY_CYCLONEDX_ROOT_KEY) {
+    bomJson.bomFormat = CYCLONEDX_FORMAT;
+    if (specVersion !== undefined) {
+      bomJson.specVersion = specVersion;
+    }
+  } else if (preserveLegacyBomFormat) {
+    bomJson.bomFormat = CYCLONEDX_FORMAT;
+    if (specVersion !== undefined) {
+      bomJson.specVersion = specVersion;
+    }
+    bomJson.specFormat = CYCLONEDX_FORMAT;
+  } else {
+    bomJson.specFormat = CYCLONEDX_FORMAT;
+    if (specVersion !== undefined) {
+      bomJson.specVersion = specVersion;
+    }
+  }
+  for (const [key, value] of remainingEntries) {
+    bomJson[key] = value;
+  }
+};
+
+/**
+ * Mutates a CycloneDX BOM object so the appropriate root format key is present
+ * for the requested spec version, while preserving conventional serialized
+ * root-key ordering (`bomFormat`/`specFormat` and `specVersion` first). Only the currently
+ * supported CycloneDX major.minor version shape is accepted; multi-component
+ * future versions such as `2.0.1` intentionally return `undefined` from the
+ * normalizer rather than being silently truncated.
+ *
+ * @param {object} bomJson BOM JSON object to mutate.
+ * @param {string|number} specVersion Desired CycloneDX spec version.
+ * @param {object} options Root-key compatibility options.
+ * @returns {object} The same `bomJson` object, after in-place mutation.
+ */
+export const setCycloneDxFormat = (
+  bomJson,
+  specVersion,
+  { preserveLegacyBomFormat = false } = {},
+) => {
+  if (!bomJson || typeof bomJson !== "object" || Array.isArray(bomJson)) {
+    return bomJson;
+  }
+  const resolvedSpecVersion =
+    toCycloneDxSpecVersionString(specVersion ?? bomJson.specVersion) ||
+    bomJson.specVersion;
+  if (resolvedSpecVersion !== undefined) {
+    bomJson.specVersion = resolvedSpecVersion;
+  }
+  if (
+    getCycloneDxRootFormatKey(resolvedSpecVersion) === MODERN_CYCLONEDX_ROOT_KEY
+  ) {
+    rewriteCycloneDxRootFields(
+      bomJson,
+      MODERN_CYCLONEDX_ROOT_KEY,
+      resolvedSpecVersion,
+      preserveLegacyBomFormat,
+    );
+    return bomJson;
+  }
+  rewriteCycloneDxRootFields(
+    bomJson,
+    LEGACY_CYCLONEDX_ROOT_KEY,
+    resolvedSpecVersion,
+    false,
+  );
+  return bomJson;
+};
 
 export const detectBomFormat = (bomJson) => {
   if (isCycloneDxBom(bomJson)) {