@cyclonedx/cdxgen 12.3.3 → 12.4.1

package/lib/helpers/hostTopology.poku.js

@@ -0,0 +1,363 @@
+import { assert, describe, it } from "poku";
+
+import {
+  applyHostInventoryTopology,
+  getHostViewSummary,
+  isMergedHostViewBom,
+  mergeHostInventoryBoms,
+} from "./hostTopology.js";
+
+function makeProperty(name, value) {
+  return { name, value };
+}
+
+function makeHbomComponent(name, hardwareClass, properties = []) {
+  return {
+    type: "device",
+    name,
+    properties: [
+      makeProperty("cdx:hbom:hardwareClass", hardwareClass),
+      ...properties,
+    ],
+  };
+}
+
+function makeOsqueryComponent(
+  name,
+  queryCategory,
+  properties = [],
+  extra = {},
+) {
+  return {
+    type: extra.type || "data",
+    name,
+    version: extra.version || "",
+    "bom-ref": extra.bomRef || `osquery:${queryCategory}:${name}`,
+    properties: [
+      makeProperty("cdx:osquery:category", queryCategory),
+      ...properties,
+    ],
+  };
+}
+
+describe("host topology helpers", () => {
+  it("adds strict HBOM topology dependencies for standalone hardware BOMs", () => {
+    const bomJson = applyHostInventoryTopology({
+      bomFormat: "CycloneDX",
+      specVersion: "1.7",
+      metadata: {
+        component: {
+          name: "host-a",
+          type: "device",
+          properties: [
+            makeProperty("cdx:hbom:platform", "linux"),
+            makeProperty("cdx:hbom:architecture", "amd64"),
+          ],
+        },
+      },
+      components: [
+        makeHbomComponent("wlp2s0", "network-interface", [
+          makeProperty("cdx:hbom:driver", "iwlwifi"),
+        ]),
+        makeHbomComponent("CT1000P3PSSD8", "storage"),
+      ],
+      dependencies: [],
+    });
+
+    assert.ok(bomJson.metadata.component["bom-ref"]);
+    assert.ok(bomJson.components.every((component) => component["bom-ref"]));
+    assert.strictEqual(getHostViewSummary(bomJson).mode, "hbom-topology");
+    assert.strictEqual(getHostViewSummary(bomJson).runtimeAnchorCount, 0);
+    assert.strictEqual(
+      bomJson.dependencies.find(
+        (dependency) =>
+          dependency.ref === bomJson.metadata.component["bom-ref"],
+      )?.dependsOn?.length,
+      2,
+    );
+  });
+
+  it("merges OBOM runtime data and links hardware to runtime components without guesswork", () => {
+    const hbomJson = {
+      bomFormat: "CycloneDX",
+      specVersion: "1.7",
+      metadata: {
+        component: {
+          name: "host-b",
+          type: "device",
+          properties: [
+            makeProperty("cdx:hbom:platform", "linux"),
+            makeProperty("cdx:hbom:architecture", "amd64"),
+            makeProperty("cdx:hbom:secureBootDbSha1", "db-cert-1"),
+          ],
+        },
+      },
+      components: [
+        makeHbomComponent("enp1s0", "network-interface", [
+          makeProperty("cdx:hbom:driver", "r8169"),
+          makeProperty("cdx:hbom:speedMbps", "100"),
+        ]),
+        makeHbomComponent("CT1000P3PSSD8", "storage", [
+          makeProperty("cdx:hbom:deviceNode", "/dev/nvme0n1"),
+          makeProperty("cdx:hbom:mountPoint", "/home"),
+        ]),
+      ],
+      dependencies: [],
+      properties: [],
+    };
+    const obomData = {
+      parentComponent: {
+        type: "operating-system",
+        name: "Ubuntu",
+        version: "24.04",
+        "bom-ref": "pkg:generic/ubuntu@24.04",
+      },
+      bomJson: {
+        bomFormat: "CycloneDX",
+        specVersion: "1.7",
+        metadata: {
+          tools: {
+            components: [
+              {
+                type: "application",
+                name: "osquery",
+                version: "5.12.0",
+                "bom-ref": "pkg:generic/osquery@5.12.0",
+              },
+            ],
+          },
+        },
+        components: [
+          makeOsqueryComponent("192.168.1.23", "interface_addresses", [
+            makeProperty("interface", "enp1s0"),
+            makeProperty("address", "192.168.1.23"),
+          ]),
+          makeOsqueryComponent("r8169", "kernel_modules", [], {
+            type: "data",
+          }),
+          makeOsqueryComponent("iwlwifi", "kernel_modules", [], {
+            type: "data",
+          }),
+          makeOsqueryComponent("/home", "mount_hardening", [
+            makeProperty("device", "/dev/nvme0n1"),
+            makeProperty("path", "/home"),
+            makeProperty("flags", "rw,nosuid,nodev"),
+          ]),
+          makeOsqueryComponent("nvme-home", "logical_drives", [
+            makeProperty("device_id", "/dev/nvme0n1"),
+            makeProperty("description", "home"),
+          ]),
+          makeOsqueryComponent("db-cert", "secureboot_certificates", [
+            makeProperty("sha1", "db-cert-1"),
+            makeProperty("subject", "CN=Platform DB"),
+          ]),
+        ],
+        dependencies: [
+          {
+            ref: "pkg:generic/ubuntu@24.04",
+            dependsOn: [
+              "osquery:interface_addresses:192.168.1.23",
+              "osquery:kernel_modules:r8169",
+            ],
+          },
+        ],
+      },
+    };
+
+    const mergedBomJson = mergeHostInventoryBoms(hbomJson, obomData);
+    const networkComponent = mergedBomJson.components.find(
+      (component) => component.name === "enp1s0",
+    );
+    const networkDependency = mergedBomJson.dependencies.find(
+      (dependency) => dependency.ref === networkComponent["bom-ref"],
+    );
+    const storageComponent = mergedBomJson.components.find(
+      (component) => component.name === "CT1000P3PSSD8",
+    );
+    const storageDependency = mergedBomJson.dependencies.find(
+      (dependency) => dependency.ref === storageComponent["bom-ref"],
+    );
+    const hostDependency = mergedBomJson.dependencies.find(
+      (dependency) =>
+        dependency.ref === mergedBomJson.metadata.component["bom-ref"],
+    );
+    const summary = getHostViewSummary(mergedBomJson);
+
+    assert.strictEqual(isMergedHostViewBom(mergedBomJson), true);
+    assert.ok(networkComponent["bom-ref"]);
+    assert.ok(networkDependency);
+    assert.deepStrictEqual(networkDependency.dependsOn, [
+      "osquery:interface_addresses:192.168.1.23",
+      "osquery:kernel_modules:r8169",
+    ]);
+    assert.deepStrictEqual(storageDependency.dependsOn, [
+      "osquery:logical_drives:nvme-home",
+      "osquery:mount_hardening:/home",
+    ]);
+    assert.ok(
+      hostDependency.dependsOn.includes(
+        "osquery:secureboot_certificates:db-cert",
+      ),
+    );
+    assert.strictEqual(
+      networkComponent.properties.find(
+        (property) =>
+          property.name === "cdx:hostview:interface_addresses:count",
+      )?.value,
+      "1",
+    );
+    assert.strictEqual(
+      networkComponent.properties.find(
+        (property) => property.name === "cdx:hostview:kernel_modules:count",
+      )?.value,
+      "1",
+    );
+    assert.strictEqual(
+      storageComponent.properties.find(
+        (property) => property.name === "cdx:hostview:mount_hardening:count",
+      )?.value,
+      "1",
+    );
+    assert.strictEqual(
+      storageComponent.properties.find(
+        (property) => property.name === "cdx:hostview:runtime-storage:count",
+      )?.value,
+      "1",
+    );
+    assert.strictEqual(
+      mergedBomJson.metadata.component.properties.find(
+        (property) =>
+          property.name === "cdx:hostview:secureboot_certificates:count",
+      )?.value,
+      "1",
+    );
+    assert.strictEqual(summary.mode, "hbom-obom-merged");
+    assert.strictEqual(summary.runtimeAnchorCount, 1);
+    assert.strictEqual(summary.runtimeComponentCount, 6);
+    assert.strictEqual(summary.topologyLinkCount, 5);
+    assert.deepStrictEqual(summary.linkedRuntimeCategories, [
+      "interface_addresses",
+      "kernel_modules",
+      "mount_hardening",
+      "runtime-storage",
+      "secureboot_certificates",
+    ]);
+  });
+
+  it("links host trust metadata to secure boot certificates only when exact identifiers match", () => {
+    const mergedBomJson = mergeHostInventoryBoms(
+      {
+        bomFormat: "CycloneDX",
+        specVersion: "1.7",
+        metadata: {
+          component: {
+            name: "host-trust",
+            type: "device",
+            properties: [
+              makeProperty("cdx:hbom:platform", "linux"),
+              makeProperty(
+                "cdx:hbom:secureBootSubjectKeyId",
+                "trust-anchor-42",
+              ),
+            ],
+          },
+        },
+        components: [],
+        dependencies: [],
+        properties: [],
+      },
+      {
+        bomJson: {
+          bomFormat: "CycloneDX",
+          specVersion: "1.7",
+          metadata: {},
+          components: [
+            makeOsqueryComponent("db-anchor", "secureboot_certificates", [
+              makeProperty("subject_key_id", "trust-anchor-42"),
+              makeProperty("issuer", "CN=Firmware CA"),
+            ]),
+          ],
+          dependencies: [],
+          properties: [],
+        },
+      },
+    );
+
+    const hostDependency = mergedBomJson.dependencies.find(
+      (dependency) =>
+        dependency.ref === mergedBomJson.metadata.component["bom-ref"],
+    );
+    const summary = getHostViewSummary(mergedBomJson);
+
+    assert.ok(hostDependency);
+    assert.deepStrictEqual(hostDependency.dependsOn, [
+      "osquery:secureboot_certificates:db-anchor",
+    ]);
+    assert.strictEqual(
+      mergedBomJson.metadata.component.properties.find(
+        (property) =>
+          property.name === "cdx:hostview:secureboot_certificates:count",
+      )?.value,
+      "1",
+    );
+    assert.ok(
+      summary.linkedRuntimeCategories.includes("secureboot_certificates"),
+    );
+    assert.strictEqual(summary.topologyLinkCount, 1);
+  });
+
+  it("does not create runtime links when there is no exact identifier match", () => {
+    const hbomJson = {
+      bomFormat: "CycloneDX",
+      specVersion: "1.7",
+      metadata: {
+        component: {
+          name: "host-c",
+          type: "device",
+          properties: [makeProperty("cdx:hbom:platform", "linux")],
+        },
+      },
+      components: [
+        makeHbomComponent("enp1s0", "network-interface", [
+          makeProperty("cdx:hbom:driver", "r8169"),
+        ]),
+      ],
+      dependencies: [],
+      properties: [],
+    };
+    const obomData = {
+      bomJson: {
+        metadata: {},
+        components: [
+          makeOsqueryComponent("192.168.1.24", "interface_addresses", [
+            makeProperty("interface", "eth9"),
+          ]),
+          makeOsqueryComponent("iwlwifi", "kernel_modules"),
+        ],
+        dependencies: [],
+        properties: [],
+      },
+    };
+
+    const mergedBomJson = mergeHostInventoryBoms(hbomJson, obomData);
+    const networkComponent = mergedBomJson.components.find(
+      (component) => component.name === "enp1s0",
+    );
+    const summary = getHostViewSummary(mergedBomJson);
+
+    assert.strictEqual(
+      mergedBomJson.dependencies.some(
+        (dependency) => dependency.ref === networkComponent["bom-ref"],
+      ),
+      false,
+    );
+    assert.strictEqual(
+      networkComponent.properties.some((property) =>
+        property.name.startsWith("cdx:hostview:"),
+      ),
+      false,
+    );
+    assert.strictEqual(summary.topologyLinkCount, 0);
+    assert.strictEqual(summary.linkedHardwareComponentCount, 0);
+  });
+});

package/lib/helpers/inventoryStats.js

@@ -0,0 +1,69 @@
+function toProperties(propertiesOrObject) {
+  if (Array.isArray(propertiesOrObject)) {
+    return propertiesOrObject;
+  }
+  if (Array.isArray(propertiesOrObject?.properties)) {
+    return propertiesOrObject.properties;
+  }
+  return [];
+}
+
+export function getPropertyValue(propertiesOrObject, propertyName) {
+  return toProperties(propertiesOrObject).find(
+    (property) => property?.name === propertyName,
+  )?.value;
+}
+
+function hasPropertyValue(propertiesOrObject, propertyName, valuePredicate) {
+  const propertyValue = getPropertyValue(propertiesOrObject, propertyName);
+  if (typeof valuePredicate === "function") {
+    return valuePredicate(propertyValue);
+  }
+  return propertyValue === valuePredicate;
+}
+
+function isFileComponent(component) {
+  return component?.type === "file";
+}
+
+function isCryptographicAssetComponent(component) {
+  return component?.type === "cryptographic-asset";
+}
+
+export function getUnpackagedExecutableComponents(components = []) {
+  return (components || []).filter(
+    (component) =>
+      isFileComponent(component) &&
+      hasPropertyValue(component, "internal:is_executable", "true"),
+  );
+}
+
+export function getUnpackagedSharedLibraryComponents(components = []) {
+  return (components || []).filter(
+    (component) =>
+      isFileComponent(component) &&
+      hasPropertyValue(component, "internal:is_shared_library", "true"),
+  );
+}
+
+export function getSourceDerivedCryptoComponents(components = []) {
+  return (components || []).filter(
+    (component) =>
+      isCryptographicAssetComponent(component) &&
+      hasPropertyValue(component, "cdx:crypto:sourceType", (propertyValue) =>
+        propertyValue?.startsWith("js-ast:"),
+      ),
+  );
+}
+
+export function getContainerFileInventoryStats(components = []) {
+  const unpackagedExecutables = getUnpackagedExecutableComponents(components);
+  const unpackagedSharedLibraries =
+    getUnpackagedSharedLibraryComponents(components);
+  return {
+    unpackagedExecutables,
+    unpackagedSharedLibraries,
+    unpackagedExecutableCount: unpackagedExecutables.length,
+    unpackagedSharedLibraryCount: unpackagedSharedLibraries.length,
+  };
+}

package/lib/helpers/inventoryStats.poku.js

@@ -0,0 +1,86 @@
+import { assert, describe, it } from "poku";
+
+import {
+  getContainerFileInventoryStats,
+  getPropertyValue,
+  getSourceDerivedCryptoComponents,
+  getUnpackagedExecutableComponents,
+  getUnpackagedSharedLibraryComponents,
+} from "./inventoryStats.js";
+
+describe("inventoryStats helpers", () => {
+  const components = [
+    {
+      type: "file",
+      name: "demo",
+      properties: [{ name: "internal:is_executable", value: "true" }],
+    },
+    {
+      type: "file",
+      name: "libdemo.so",
+      properties: [{ name: "internal:is_shared_library", value: "true" }],
+    },
+    {
+      type: "file",
+      name: "README.md",
+      properties: [{ name: "internal:is_executable", value: "false" }],
+    },
+    {
+      type: "cryptographic-asset",
+      name: "sha-512",
+      properties: [
+        { name: "cdx:crypto:sourceType", value: "js-ast:node:crypto" },
+      ],
+    },
+    {
+      type: "cryptographic-asset",
+      name: "cert.pem",
+      properties: [{ name: "cdx:crypto:sourceType", value: "certificate" }],
+    },
+  ];
+
+  it("getPropertyValue() reads properties from arrays and component objects", () => {
+    assert.strictEqual(
+      getPropertyValue(components[0], "internal:is_executable"),
+      "true",
+    );
+    assert.strictEqual(
+      getPropertyValue(components[0].properties, "internal:is_executable"),
+      "true",
+    );
+    assert.strictEqual(getPropertyValue({}, "missing"), undefined);
+  });
+
+  it("filters unpackaged executable and shared-library file components", () => {
+    assert.deepStrictEqual(
+      getUnpackagedExecutableComponents(components).map(
+        (component) => component.name,
+      ),
+      ["demo"],
+    );
+    assert.deepStrictEqual(
+      getUnpackagedSharedLibraryComponents(components).map(
+        (component) => component.name,
+      ),
+      ["libdemo.so"],
+    );
+  });
+
+  it("filters source-derived crypto components", () => {
+    assert.deepStrictEqual(
+      getSourceDerivedCryptoComponents(components).map(
+        (component) => component.name,
+      ),
+      ["sha-512"],
+    );
+  });
+
+  it("summarizes unpackaged container file inventory counts", () => {
+    assert.deepStrictEqual(getContainerFileInventoryStats(components), {
+      unpackagedExecutables: [components[0]],
+      unpackagedSharedLibraries: [components[1]],
+      unpackagedExecutableCount: 1,
+      unpackagedSharedLibraryCount: 1,
+    });
+  });
+});

package/lib/helpers/lolbas.js

@@ -42,6 +42,22 @@ const MATCH_FIELDS = [
   "program",
   "source",
 ];
+const CATEGORY_MATCH_FIELDS = {
+  appcompat_shims: ["executable", "path", "sdb_path"],
+  listening_ports: ["cmdline", "name", "path"],
+  process_open_handles_snapshot: ["cmdline", "name", "path"],
+  processes: ["cmdline", "name", "path"],
+  scheduled_tasks: ["action"],
+  services_snapshot: ["module_path", "path"],
+  startup_items: ["path"],
+  windows_run_keys: ["description", "name"],
+  wmi_cli_event_consumers: ["command_line_template", "command_line", "name"],
+  wmi_cli_event_consumers_snapshot: [
+    "command_line_template",
+    "command_line",
+    "name",
+  ],
+};
 const STANDALONE_COMMAND_PATTERN =
   /\b(bitsadmin|certutil|cmd|cmdkey|cmstp|cscript|ftp|installutil|msbuild|mshta|msiexec|odbcconf|powershell|pwsh|regsvr32|rundll32|wmic|wscript)\b/gi;
 const WINDOWS_EXECUTABLE_PATTERN =
@@ -173,7 +189,9 @@ export function getLolbasMetadata(candidate) {
  */
 export function createLolbasProperties(queryCategory, row) {
   const matches = new Map();
-  for (const field of MATCH_FIELDS) {
+  const matchFieldsForCategory =
+    CATEGORY_MATCH_FIELDS[queryCategory] || MATCH_FIELDS;
+  for (const field of matchFieldsForCategory) {
     const fieldValue = row?.[field];
     if (!fieldValue) {
       continue;

package/lib/helpers/lolbas.poku.js

@@ -36,4 +36,27 @@ describe("lolbas helpers", () => {
     assert.ok(propertyMap["cdx:lolbas:attackTechniques"].includes("T1059.001"));
     assert.ok(propertyMap["cdx:lolbas:matchFields"].includes("description"));
   });
+
+  it("ignores benign Windows service descriptions that only mention LOLBAS tools", () => {
+    const properties = createLolbasProperties("services_snapshot", {
+      description:
+        "This service can be queried via Powershell and configured with winrm.cmd.",
+      display_name: "Windows Remote Management",
+      module_path: "C:\\Windows\\System32\\WsmSvc.dll",
+      path: "C:\\Windows\\System32\\svchost.exe -k NetworkService -p",
+    });
+    assert.deepStrictEqual(properties, []);
+  });
+
+  it("keeps Windows service path matches when the executable field itself is LOLBAS", () => {
+    const properties = createLolbasProperties("services_snapshot", {
+      path: "C:\\Users\\Public\\evil\\powershell.exe -enc AAAA",
+    });
+    const propertyMap = Object.fromEntries(
+      properties.map((property) => [property.name, property.value]),
+    );
+    assert.strictEqual(propertyMap["cdx:lolbas:matched"], "true");
+    assert.ok(propertyMap["cdx:lolbas:names"].includes("powershell.exe"));
+    assert.ok(propertyMap["cdx:lolbas:matchFields"].includes("path"));
+  });
 });

package/lib/helpers/osqueryTransform.js

@@ -65,6 +65,53 @@ export function sanitizeOsQueryIdentity(value) {
     .replace(/[}]$/g, "");
 }
 
+export function sanitizeOsQueryBomRefValue(value, fallback = "unknown") {
+  const normalizedValue = String(value || "")
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!normalizedValue || normalizedValue === "null") {
+    return fallback;
+  }
+  return normalizedValue.replace(/[:@#\[\]=]/g, "-");
+}
+
+export function createOsQueryFallbackBomRef(
+  queryCategory,
+  componentType,
+  name,
+  version,
+  identityField,
+  identityValue,
+) {
+  const categoryRef = sanitizeOsQueryBomRefValue(queryCategory, "component");
+  const componentTypeRef = sanitizeOsQueryBomRefValue(
+    componentType,
+    "component",
+  );
+  const nameRef = sanitizeOsQueryBomRefValue(
+    name || queryCategory,
+    "component",
+  );
+  const versionRef = sanitizeOsQueryBomRefValue(version, "unknown");
+  const baseBomRef = `osquery:${categoryRef}:${componentTypeRef}:${nameRef}@${versionRef}`;
+  if (!identityField || !identityValue) {
+    return baseBomRef;
+  }
+  const identityFieldRef = sanitizeOsQueryBomRefValue(
+    identityField,
+    "identity",
+  );
+  const identityValueRef = sanitizeOsQueryBomRefValue(identityValue, "unknown");
+  return `${baseBomRef}[${identityFieldRef}=${identityValueRef}]`;
+}
+
+export function shouldCreateOsQueryPurl(componentType) {
+  return !["cryptographic-asset", "data", "device", "information"].includes(
+    componentType || "",
+  );
+}
+
 export function createOsQueryPurl(
   purlType,
   group,

package/lib/helpers/osqueryTransform.poku.js

@@ -1,12 +1,15 @@
 import { assert, describe, it } from "poku";
 
 import {
+  createOsQueryFallbackBomRef,
   createOsQueryPurl,
   deriveOsQueryDescription,
   deriveOsQueryName,
   deriveOsQueryPublisher,
   deriveOsQueryVersion,
+  sanitizeOsQueryBomRefValue,
   sanitizeOsQueryIdentity,
+  shouldCreateOsQueryPurl,
 } from "./osqueryTransform.js";
 
 describe("osqueryTransform helpers", () => {
@@ -46,4 +49,48 @@ describe("osqueryTransform helpers", () => {
     assert.ok(purl.startsWith("pkg:swid/microsoft/"));
     assert.ok(purl.includes("@22H2"));
   });
+
+  it("creates readable fallback bom-ref strings for non-package osquery rows", () => {
+    const bomRef = createOsQueryFallbackBomRef(
+      "authorized_keys_snapshot",
+      "data",
+      "root",
+      "ssh-ed25519",
+      "key_file",
+      "/root/.ssh/authorized_keys",
+    );
+    assert.strictEqual(
+      bomRef,
+      "osquery:authorized_keys_snapshot:data:root@ssh-ed25519[key_file=/root/.ssh/authorized_keys]",
+    );
+  });
+
+  it("omits the bracketed suffix when no extra identity field exists", () => {
+    const bomRef = createOsQueryFallbackBomRef(
+      "windows_run_keys",
+      "data",
+      "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\Updater",
+      undefined,
+    );
+    assert.strictEqual(
+      bomRef,
+      "osquery:windows_run_keys:data:HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\Updater@unknown",
+    );
+  });
+
+  it("sanitizes fallback bom-ref fragments without percent-encoding them", () => {
+    assert.strictEqual(
+      sanitizeOsQueryBomRefValue(" launchd: updater@[user]=#1\n"),
+      "launchd- updater--user---1",
+    );
+  });
+
+  it("limits purl generation to package-like osquery component types", () => {
+    assert.strictEqual(shouldCreateOsQueryPurl(undefined), true);
+    assert.strictEqual(shouldCreateOsQueryPurl("application"), true);
+    assert.strictEqual(shouldCreateOsQueryPurl("operating-system"), true);
+    assert.strictEqual(shouldCreateOsQueryPurl("data"), false);
+    assert.strictEqual(shouldCreateOsQueryPurl("device"), false);
+    assert.strictEqual(shouldCreateOsQueryPurl("cryptographic-asset"), false);
+  });
 });