@cdxgen/cdxgen 13.4.0 → 13.5.0

package/lib/inventory/hbom.js

@@ -1,4 +1,6 @@
-import { basename } from "node:path";
+import { createHash } from "node:crypto";
+import { basename, win32 } from "node:path";
+import process from "node:process";
 
 import {
   isDryRun,
@@ -40,6 +42,18 @@ function getConfiguredHbomPathAllowlist() {
   );
 }
 
+// A Windows plan can be inspected from any host (`getCommandPlan`), where
+// node:path would not split a path on its backslashes.
+function isWindowsStyleCommand(command) {
+  return command.includes("\\") || /^[A-Za-z]:/u.test(command);
+}
+
+function getHbomCommandName(command) {
+  return isWindowsStyleCommand(command)
+    ? win32.basename(command)
+    : basename(command);
+}
+
 function isAllowedHbomCommand(command, allowlistValue = undefined) {
   const normalizedCommand = `${command ?? ""}`.trim();
   if (!normalizedCommand) {
@@ -51,7 +65,10 @@ function isAllowedHbomCommand(command, allowlistValue = undefined) {
   if (!allowlistEntries.length) {
     return true;
   }
-  const commandName = basename(normalizedCommand);
+  // Exact and case-sensitive on purpose: cdx-hbom applies the same allowlist
+  // again when it spawns, so a looser preflight would pass here and then run
+  // nothing, which silently degrades the BOM.
+  const commandName = getHbomCommandName(normalizedCommand);
   return allowlistEntries.some(
     (entry) => entry === normalizedCommand || entry === commandName,
   );
@@ -61,9 +78,27 @@ function formatHbomCommandTarget(command, args = []) {
   return `${command}${args.length ? ` ${args.join(" ")}` : ""}`;
 }
 
+// Windows plan entries carry a multi-kilobyte PowerShell script as their last
+// argument. Like the cdx-hbom trace and evidence, the preflight names it by
+// digest so a blocked run does not print every script.
+function summarizeHbomPlanArgs(planEntry) {
+  const args = [...(planEntry.args || [])];
+  if (planEntry.parser !== "windows-envelope" || !args.length) {
+    return args;
+  }
+  const digest = createHash("sha256")
+    .update(String(args.at(-1)))
+    .digest("hex")
+    .slice(0, 12);
+  return ["-Command", planEntry.id, "script", `sha256:${digest}`];
+}
+
 function buildHbomPlanActivities(planEntry, normalizedOptions) {
   const baseArgs = [...(planEntry.args || [])];
-  const baseTarget = formatHbomCommandTarget(planEntry.command, baseArgs);
+  const baseTarget = formatHbomCommandTarget(
+    planEntry.command,
+    summarizeHbomPlanArgs(planEntry),
+  );
   const activities = [
     {
       args: baseArgs,
@@ -115,7 +150,7 @@ function collectDisallowedHbomCommands(
     }
     const existingEntry = disallowedCommands.get(requestedCommand) ?? {
       command: requestedCommand,
-      commandName: basename(requestedCommand),
+      commandName: getHbomCommandName(requestedCommand),
       ids: new Set(),
       targets: new Set(),
     };
@@ -214,6 +249,28 @@ function createHbomAllowlistPreflightError(
   return new Error(messageLines.join("\n"));
 }
 
+/**
+ * Whether cdx-hbom spawns no command for these collector options.
+ *
+ * Only the Linux collector reads `includeCommandEnrichment: false` as "run no
+ * commands", and even there the privileged dmidecode step still runs. The
+ * Darwin collector ignores the option, and the Windows collector always runs
+ * its `windows-cim-platform` batch, so those plans are checked in full.
+ *
+ * @param {object} normalizedOptions Collector options from normalizeHbomOptions
+ * @returns {boolean} `true` when the allowlist has nothing to check
+ */
+function collectorSpawnsNoCommands(normalizedOptions) {
+  const targetPlatform = `${normalizedOptions.platform ?? process.platform}`
+    .trim()
+    .toLowerCase();
+  return (
+    normalizedOptions.includeCommandEnrichment === false &&
+    normalizedOptions.includePrivilegedEnrichment !== true &&
+    targetPlatform === "linux"
+  );
+}
+
 async function enforceSecureModeHbomAllowlists(hbomModule, normalizedOptions) {
   if (isDryRun || normalizedOptions?.isDryRun || !isSecureMode) {
     return;
@@ -249,7 +306,7 @@ async function enforceSecureModeHbomAllowlists(hbomModule, normalizedOptions) {
         : [];
   } else if (
     hasCommandAllowlist &&
-    normalizedOptions.includeCommandEnrichment !== false
+    !collectorSpawnsNoCommands(normalizedOptions)
   ) {
     traceActivities = hbomModule
       .getCommandPlan(normalizedOptions)
@@ -259,7 +316,7 @@ async function enforceSecureModeHbomAllowlists(hbomModule, normalizedOptions) {
   }
 
   const disallowedCommands =
-    hasCommandAllowlist && normalizedOptions.includeCommandEnrichment !== false
+    hasCommandAllowlist && !collectorSpawnsNoCommands(normalizedOptions)
       ? collectDisallowedHbomCommands(traceActivities, commandAllowlistValue)
       : [];
   const disallowedPaths = hasPathAllowlist
@@ -398,8 +455,11 @@ export function normalizeHbomOptions(options = {}) {
     timeoutValue === undefined || timeoutValue === null || timeoutValue === ""
       ? undefined
       : Number.parseInt(`${timeoutValue}`, 10);
+  // yargs negates `--no-command-enrichment` into `commandEnrichment: false`
+  // and never sets `noCommandEnrichment`, so the CLIs rely on this spelling.
   const includeCommandEnrichment =
-    options.includeCommandEnrichment ?? !options.noCommandEnrichment;
+    options.includeCommandEnrichment ??
+    (options.commandEnrichment !== false && !options.noCommandEnrichment);
   const allowPartial = options.allowPartial ?? !options.strict;
 
   return {

package/lib/inventory/hbomAnalysis.js

@@ -174,6 +174,22 @@ export function isHbomLikeBom(bomJson) {
   );
 }
 
+/**
+ * Explain how the permission-denied enrichments of an HBOM can be recovered.
+ *
+ * Windows never uses sudo: the elevated-only batch needs an already-elevated
+ * session, and a network logon is denied every WMI query.
+ *
+ * @param {string|undefined} platform `cdx:hbom:platform` of the HBOM
+ * @returns {string} Guidance for the platform; the Linux wording for any other platform
+ */
+export function getHbomPrivilegeGuidance(platform) {
+  if (`${platform ?? ""}`.toLowerCase() === "windows") {
+    return "Some Windows enrichments were denied. Run HBOM from a local session (a non-administrator over SSH or WinRM is denied every WMI query) and, for the TPM, BitLocker, storage-reliability and Secure Boot data, from an elevated (Run as administrator) prompt with --privileged. HBOM never prompts for elevation.";
+  }
+  return "Some Linux enrichments can likely succeed only with --privileged and a target environment that allows non-interactive sudo.";
+}
+
 /**
  * Return a component's `cdx:hbom:hardwareClass` property value.
  *

package/lib/inventory/hostTopology.js

@@ -276,6 +276,7 @@ function isFilesystemIdentity(value) {
 function createRuntimeIndexes(runtimeComponents) {
   const interfaceAddressesByName = new Map();
   const kernelModulesByName = new Map();
+  const logicalDrivesByDeviceId = new Map();
   const mountPathsByDevice = new Map();
   const mountPathsByPath = new Map();
   const runtimeByStorageIdentity = new Map();
@@ -306,6 +307,13 @@ function createRuntimeIndexes(runtimeComponents) {
         component["bom-ref"],
       );
     }
+    if (runtimeCategory === "logical_drives") {
+      appendMapEntry(
+        logicalDrivesByDeviceId,
+        toNormalizedIdentity(getPropertyValue(component, "device_id")),
+        component["bom-ref"],
+      );
+    }
     if (runtimeCategory === "mount_hardening") {
       appendMapEntry(
         mountPathsByDevice,
@@ -339,6 +347,7 @@ function createRuntimeIndexes(runtimeComponents) {
   return {
     interfaceAddressesByName,
     kernelModulesByName,
+    logicalDrivesByDeviceId,
     mountPathsByDevice,
     mountPathsByPath,
     runtimeByStorageIdentity,
@@ -532,6 +541,14 @@ function createDependencyEdgeList(
           "mount_hardening",
           Array.from(indexes.mountPathsByPath.get(mountPath) || []),
         );
+        // The Windows osquery pack has no mount_hardening; a volume's drive
+        // letter (C:) is the device_id of its logical drive.
+        addCategoryRefs(
+          linkedRefs,
+          linkedCategoryRefs,
+          "logical_drives",
+          Array.from(indexes.logicalDrivesByDeviceId.get(mountPath) || []),
+        );
       }
       const explicitFilesystemIdentity = isFilesystemIdentity(component.version)
         ? toNormalizedIdentity(component.version)
@@ -788,6 +805,10 @@ export function mergeHostInventoryBoms(hbomJson, obomData) {
   if (obomData.parentComponent?.name && obomData.parentComponent?.type) {
     runtimeComponents.unshift(obomData.parentComponent);
   }
+  // trimComponents keys a component without a purl or bom-ref on name and
+  // version, which would fold hardware that shares a name (every Windows
+  // volume without a drive letter is named "Volume") into one component.
+  ensureBomRefs(hbomJson);
   const mergedBomJson = {
     ...hbomJson,
     components: trimComponents([

package/lib/inventory/osPackagePurl.js

@@ -0,0 +1,244 @@
+// The one place that decides what purl an operating-system package gets.
+//
+// A package found by `cdxgen -t docker <image>` and by `obom` run inside that
+// image must be the same package, so the OBOM rows, the file-to-package
+// resolver and the container scan all name a deb, an rpm or an apk package with
+// the vendor and the qualifiers set here and in getDistroInfo(): `arch`,
+// `distro`, `distro_name` and, when the package has one, `epoch`. A pacman
+// package has the vendor and only the `arch` qualifier the alpm type defines.
+// Homebrew, MacPorts and snap packages have no distro, so their purl is the
+// name and the version; a flatpak adds the `arch` and `branch` of its ref.
+//
+// None of these purls has a subpath. A subpath names a path inside a package;
+// the dpkg directory or the source rpm of a row is not one.
+
+import { getDistroInfo, isCleanDistroQualifier } from "./osinfo.js";
+import { tryBuildPurl } from "./purl.js";
+
+/**
+ * The purl types an OS scan builds from what a package manager reports.
+ * deb, rpm, apk and alpm belong to a distro; brew, macports, snap and flatpak
+ * belong to none. brew, macports, snap and flatpak are not purl-spec types;
+ * cdx-purl builds them as it builds `pkg:chocolatey`.
+ */
+export const OS_PACKAGE_PURL_TYPES = new Set([
+  "deb",
+  "rpm",
+  "apk",
+  "alpm",
+  "brew",
+  "macports",
+  "snap",
+  "flatpak",
+]);
+
+/**
+ * Whether a purl type is one of the OS package managers handled here.
+ *
+ * @param {string|undefined} type Purl type
+ * @returns {boolean} true for the types in OS_PACKAGE_PURL_TYPES
+ */
+export function isOsPackagePurlType(type) {
+  return OS_PACKAGE_PURL_TYPES.has(type);
+}
+
+/**
+ * Whether a value names an architecture. rpm says `(none)` and trivy says
+ * `None` for a package that has none, such as an rpm's `gpg-pubkey` key record;
+ * neither is an architecture, and neither belongs in a purl.
+ *
+ * @param {string|undefined|null} arch Architecture as a package manager reports it
+ * @returns {boolean} true for a real architecture
+ */
+export function isRealArchitecture(arch) {
+  const value = `${arch ?? ""}`.trim().toLowerCase();
+  return value !== "" && value !== "(none)" && value !== "none";
+}
+
+function isDigits(text) {
+  if (!text) {
+    return false;
+  }
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 48 || code > 57) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// An epoch is a non-negative integer, and 0 is the same as none. Anything else
+// ("", "(none)", "null") is no epoch.
+function normaliseEpoch(value) {
+  const text = `${value ?? ""}`.trim();
+  if (!isDigits(text)) {
+    return undefined;
+  }
+  const digits = text.replace(/^0+/, "");
+  return digits || undefined;
+}
+
+// dpkg writes a version as [epoch:]upstream[-revision]. A colon is only ever an
+// epoch's separator when what comes before it is all digits.
+function debVersionEpoch(version) {
+  const colon = version.indexOf(":");
+  if (colon <= 0) {
+    return undefined;
+  }
+  const prefix = version.slice(0, colon);
+  return isDigits(prefix) ? prefix : undefined;
+}
+
+/**
+ * The epoch of an OS package, as the `epoch` qualifier carries it.
+ *
+ * An rpm keeps its epoch in a field of its own. A deb keeps it in its version
+ * (`2:93`), so the version is read first. Epoch 0 and no epoch are the same,
+ * and apk and Homebrew packages have none.
+ *
+ * @param {{type: string, version?: string, epoch?: string|number}} pkg Package
+ * @returns {string|undefined} The epoch without leading zeros, or undefined
+ */
+export function osPackageEpoch(pkg) {
+  switch (pkg?.type) {
+    case "rpm":
+      return normaliseEpoch(pkg.epoch);
+    case "deb": {
+      const fromVersion = debVersionEpoch(`${pkg.version ?? ""}`);
+      return fromVersion === undefined
+        ? normaliseEpoch(pkg.epoch)
+        : normaliseEpoch(fromVersion);
+    }
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * The version an OS package carries on its component and in its purl.
+ *
+ * - rpm: `[epoch:]version-release`, the form the container scan writes. The
+ *   purl spec keeps the epoch out of an rpm version, but the container scan
+ *   puts it in the version as well as in the `epoch` qualifier, and an OBOM must
+ *   name the package the same way.
+ * - deb: the version exactly as dpkg reports it, epoch included.
+ * - macports: `version_revision`, the form `port installed` prints.
+ * - apk, alpm, brew, snap and flatpak: the version as it is. A pacman version
+ *   already holds its epoch and release (`1:1.3.2-4`).
+ *
+ * @param {{type: string, version?: string, release?: string, epoch?: string|number, revision?: string|number}} pkg Package
+ * @returns {string} The version, or an empty string when the package has none
+ */
+export function osPackageVersion(pkg) {
+  const version = `${pkg?.version ?? ""}`;
+  if (!version) {
+    return "";
+  }
+  switch (pkg.type) {
+    case "rpm": {
+      const release = `${pkg.release ?? ""}`;
+      const evr = release ? `${version}-${release}` : version;
+      const epoch = osPackageEpoch(pkg);
+      return epoch ? `${epoch}:${evr}` : evr;
+    }
+    case "deb": {
+      if (debVersionEpoch(version) !== undefined) {
+        return version;
+      }
+      const epoch = normaliseEpoch(pkg.epoch);
+      return epoch ? `${epoch}:${version}` : version;
+    }
+    case "macports": {
+      // Revision 0 is a real revision: `port installed` prints `@3.6.0_0`.
+      const revision = `${pkg.revision ?? ""}`.trim();
+      return isDigits(revision) ? `${version}_${revision}` : version;
+    }
+    default:
+      return version;
+  }
+}
+
+/**
+ * Build the purl of an OS package.
+ *
+ * deb, rpm and apk purls take their vendor (`ubuntu`, `almalinux`, `alpine`,
+ * `wolfi`) and the `distro` and `distro_name` qualifiers from the distro, plus
+ * `arch` and `epoch` from the package. alpm purls take the vendor (`arch`,
+ * `manjaro`) and `arch` only: that is all the alpm type defines, and an Arch
+ * system is rolling, with no release to name. A qualifier with no value is
+ * left out. brew, macports and snap purls carry neither vendor nor qualifiers;
+ * a flatpak purl carries the `arch` and `branch` of the flatpak ref.
+ *
+ * @param {Object} pkg The package
+ * @param {string} pkg.type One of OS_PACKAGE_PURL_TYPES
+ * @param {string} pkg.name Package name; a flatpak's application ID
+ * @param {string} [pkg.version] deb: the dpkg version. rpm: the version tag only. apk: version-rN. macports: the version without its revision.
+ * @param {string} [pkg.release] rpm release tag
+ * @param {string|number} [pkg.epoch] rpm epoch tag
+ * @param {string|number} [pkg.revision] MacPorts revision
+ * @param {string} [pkg.arch] Package architecture
+ * @param {string} [pkg.branch] flatpak branch (`stable`, `48`)
+ * @param {{namespace?: string, distroId?: string, distroName?: string}} [distro]
+ *   What getDistroInfo() reports; read from the host's os-release when left out
+ * @returns {string|null} The purl, or null when the parts do not form a valid one
+ */
+export function buildOsPackagePurl(pkg, distro) {
+  const type = pkg?.type;
+  const name = `${pkg?.name ?? ""}`;
+  if (!isOsPackagePurlType(type) || !name) {
+    return null;
+  }
+  const version = osPackageVersion(pkg) || null;
+  switch (type) {
+    case "brew":
+    case "macports":
+    case "snap":
+      return tryBuildPurl({ type, name, version });
+    case "flatpak": {
+      const qualifiers = {};
+      if (isRealArchitecture(pkg.arch)) {
+        qualifiers.arch = `${pkg.arch}`.trim();
+      }
+      const branch = `${pkg.branch ?? ""}`.trim();
+      if (branch) {
+        qualifiers.branch = branch;
+      }
+      return tryBuildPurl({
+        type,
+        name,
+        version,
+        qualifiers: Object.keys(qualifiers).length ? qualifiers : null,
+      });
+    }
+    default:
+      break;
+  }
+  const { namespace, distroId, distroName } = distro || getDistroInfo();
+  if (!namespace) {
+    return null;
+  }
+  const qualifiers = {};
+  if (isRealArchitecture(pkg.arch)) {
+    qualifiers.arch = `${pkg.arch}`.trim();
+  }
+  if (type !== "alpm") {
+    if (isCleanDistroQualifier(distroId)) {
+      qualifiers.distro = distroId;
+    }
+    if (isCleanDistroQualifier(distroName)) {
+      qualifiers.distro_name = distroName;
+    }
+    const epoch = osPackageEpoch(pkg);
+    if (epoch) {
+      qualifiers.epoch = epoch;
+    }
+  }
+  return tryBuildPurl({
+    type,
+    namespace,
+    name,
+    version,
+    qualifiers: Object.keys(qualifiers).length ? qualifiers : null,
+  });
+}