@cyclonedx/cdxgen 12.3.3 → 12.4.1

package/bin/repl.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import fs from "node:fs";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import process from "node:process";
@@ -21,14 +21,35 @@ import {
   printTable,
   printVulnerabilities,
 } from "../lib/helpers/display.js";
-import { readBinary } from "../lib/helpers/protobom.js";
+import {
+  formatHbomHardwareClassSummary,
+  getHbomSummary,
+  isHbomLikeBom,
+} from "../lib/helpers/hbomAnalysis.js";
+import {
+  getPropertyValue,
+  getSourceDerivedCryptoComponents,
+  getUnpackagedExecutableComponents,
+  getUnpackagedSharedLibraryComponents,
+} from "../lib/helpers/inventoryStats.js";
+import {
+  importProtobomModule,
+  isProtoBomPath,
+} from "../lib/helpers/protobomLoader.js";
 import {
   getProvenanceComponents,
   getTrustedComponents,
 } from "../lib/helpers/provenanceUtils.js";
 import { toCycloneDxLikeBom } from "../lib/helpers/spdxUtils.js";
 import { table } from "../lib/helpers/table.js";
-import { getTmpDir } from "../lib/helpers/utils.js";
+import {
+  getTmpDir,
+  isDryRun,
+  safeExistsSync,
+  safeMkdirSync,
+  safeMkdtempSync,
+  safeWriteSync,
+} from "../lib/helpers/utils.js";
 import { getBomWithOras } from "../lib/managers/oci.js";
 import { validateBom } from "../lib/validator/bomValidator.js";
 
@@ -55,7 +76,7 @@ const cdxArt = `
 
 console.log(cdxArt);
 
-if (process.env?.CDXGEN_NODE_OPTIONS) {
+if (process.env.CDXGEN_NODE_OPTIONS) {
   process.env.NODE_OPTIONS = `${process.env.NODE_OPTIONS || ""} ${process.env.CDXGEN_NODE_OPTIONS}`;
 }
 
@@ -63,6 +84,23 @@ if (process.env?.CDXGEN_NODE_OPTIONS) {
 let sbom;
 const getInteractiveBom = () => toCycloneDxLikeBom(sbom);
 
+function getContainerRegistryHost(reference) {
+  const trimmedReference = `${reference || ""}`.trim().toLowerCase();
+  if (!trimmedReference) {
+    return undefined;
+  }
+  const slashIndex = trimmedReference.indexOf("/");
+  if (slashIndex <= 0) {
+    return undefined;
+  }
+  return trimmedReference.slice(0, slashIndex).replace(/:\d+$/, "");
+}
+
+function isSupportedSbomRegistryReference(reference) {
+  const registryHost = getContainerRegistryHost(reference);
+  return registryHost === "ghcr.io" || registryHost === "docker.io";
+}
+
 function unescapeAnnotationText(value) {
   return String(value || "")
     .replace(/<br>/g, "\n")
@@ -143,11 +181,15 @@ function printAuditTable(title, rows) {
   );
 }
 
-function getPropertyValue(propertiesOrObject, propertyName) {
-  const properties = Array.isArray(propertiesOrObject)
-    ? propertiesOrObject
-    : propertiesOrObject?.properties;
-  return properties?.find((property) => property.name === propertyName)?.value;
+function printKeyValueTable(title, entries) {
+  const rows = [["Field", "Value"]];
+  entries.forEach(([field, value]) => {
+    if (value === undefined || value === null || value === "") {
+      return;
+    }
+    rows.push([field, `${value}`]);
+  });
+  printAuditTable(title, rows);
 }
 
 function isLikelyObom(bom) {
@@ -158,6 +200,10 @@ function isLikelyObom(bom) {
   );
 }
 
+function isLikelyHbom(bom) {
+  return isHbomLikeBom(bom);
+}
+
 function isLikelyCargoBom(bom) {
   const formulation = Array.isArray(bom?.formulation)
     ? bom.formulation
@@ -221,11 +267,94 @@ function getCargoFormulationEntries(bom) {
   return matchingEntries;
 }
 
+const HBOM_FIRMWARE_PROPERTIES = Object.freeze([
+  "cdx:hbom:protocol",
+  "cdx:hbom:flags",
+  "cdx:hbom:guids",
+  "cdx:hbom:instanceIds",
+  "cdx:hbom:createdEpoch",
+  "cdx:hbom:firmwareDate",
+]);
+
+const HBOM_BUS_SECURITY_PROPERTIES = Object.freeze([
+  "cdx:hbom:securityLevel",
+  "cdx:hbom:iommuProtection",
+  "cdx:hbom:policy",
+  "cdx:hbom:authorized",
+  "cdx:hbom:usbVersion",
+  "cdx:hbom:usbClassName",
+  "cdx:hbom:usbInterfaceClasses",
+  "cdx:hbom:pciClass",
+  "cdx:hbom:pciClassCode",
+  "cdx:hbom:displayConnectorType",
+  "cdx:hbom:contentProtection",
+  "cdx:hbom:drmNode",
+]);
+
+const HBOM_POWER_PROPERTIES = Object.freeze([
+  "cdx:hbom:designCapacityPercent",
+  "cdx:hbom:energyNow",
+  "cdx:hbom:energyFull",
+  "cdx:hbom:energyFullDesign",
+  "cdx:hbom:chargeNow",
+  "cdx:hbom:chargeFull",
+  "cdx:hbom:chargeFullDesign",
+  "cdx:hbom:powerNow",
+  "cdx:hbom:voltageNow",
+  "cdx:hbom:currentNow",
+  "cdx:hbom:warningLevel",
+]);
+
+function getInteractiveHbomOrWarn(replContext) {
+  const interactiveBom = getInteractiveBom();
+  if (!interactiveBom) {
+    console.log(
+      "⚠ No BOM is loaded. Use .import command to import an existing BOM",
+    );
+    replContext.displayPrompt();
+    return undefined;
+  }
+  if (!isLikelyHbom(interactiveBom)) {
+    console.log(
+      "This BOM does not look like an HBOM. Import an HBOM generated with 'cdxgen -t hbom' to use this view.",
+    );
+    replContext.displayPrompt();
+    return undefined;
+  }
+  return interactiveBom;
+}
+
+function filterHbomComponentsByProperties(
+  bom,
+  propertyNames,
+  hardwareClasses = [],
+) {
+  return (bom?.components || []).filter((component) => {
+    const hardwareClass = getPropertyValue(component, "cdx:hbom:hardwareClass");
+    if (hardwareClasses.includes(hardwareClass)) {
+      return true;
+    }
+    return propertyNames.some((propertyName) =>
+      Boolean(getPropertyValue(component, propertyName)),
+    );
+  });
+}
+
+function getDiagnosticDisplayDetail(diagnostic) {
+  return (
+    diagnostic.installHint ||
+    diagnostic.privilegeHint ||
+    diagnostic.message ||
+    diagnostic.code ||
+    "-"
+  );
+}
+
 let historyFile;
 const historyConfigDir = join(homedir(), ".config", ".cdxgen");
-if (!process.env.CDXGEN_REPL_HISTORY && !fs.existsSync(historyConfigDir)) {
+if (!process.env.CDXGEN_REPL_HISTORY && !safeExistsSync(historyConfigDir)) {
   try {
-    fs.mkdirSync(historyConfigDir, { recursive: true });
+    safeMkdirSync(historyConfigDir, { recursive: true });
     historyFile = join(historyConfigDir, ".repl_history");
   } catch (_e) {
     // ignore
@@ -234,10 +363,15 @@ if (!process.env.CDXGEN_REPL_HISTORY && !fs.existsSync(historyConfigDir)) {
   historyFile = join(historyConfigDir, ".repl_history");
 }
 
-export const importSbom = (sbomOrPath) => {
-  if (sbomOrPath?.endsWith(".json") && fs.existsSync(sbomOrPath)) {
+export const importSbom = async (sbomOrPath) => {
+  const importTarget = String(sbomOrPath || "").trim();
+  if (!importTarget) {
+    console.log("⚠ An SBOM path or image reference is required.");
+    return;
+  }
+  if (importTarget.endsWith(".json") && safeExistsSync(importTarget)) {
     try {
-      sbom = JSON.parse(fs.readFileSync(sbomOrPath, "utf-8"));
+      sbom = JSON.parse(readFileSync(importTarget, "utf-8"));
       let bomType = "SBOM";
       if (isSpdxJsonLd(sbom)) {
         bomType = "SPDX";
@@ -245,8 +379,13 @@ export const importSbom = (sbomOrPath) => {
       if (sbom?.vulnerabilities && Array.isArray(sbom.vulnerabilities)) {
         bomType = "VDR";
       }
-      console.log(`✅ ${bomType} imported successfully from ${sbomOrPath}`);
+      console.log(`✅ ${bomType} imported successfully from ${importTarget}`);
       printSummary(sbom);
+      if (isLikelyHbom(sbom)) {
+        console.log(
+          "💭 HBOM detected. Try .hbomsummary, .hbomevidence, .hbomdiagnostics, or .hbomtips",
+        );
+      }
       if (isLikelyObom(sbom)) {
         console.log(
           "💭 OBOM detected. Try .osinfocategories, .obomtips, .processes, or .services_snapshot",
@@ -263,56 +402,66 @@ export const importSbom = (sbomOrPath) => {
         );
       }
     } catch (e) {
-      console.log(`⚠ Unable to import the BOM from ${sbomOrPath} due to ${e}`);
+      console.log(
+        `⚠ Unable to import the BOM from ${importTarget} due to ${e}`,
+      );
     }
-  } else if (
-    (sbomOrPath?.endsWith(".cdx") || sbomOrPath?.endsWith(".proto")) &&
-    fs.existsSync(sbomOrPath)
-  ) {
-    sbom = readBinary(sbomOrPath, true);
+  } else if (isProtoBomPath(importTarget) && safeExistsSync(importTarget)) {
+    const { readBinary } = await importProtobomModule(
+      "cdxi",
+      "protobuf BOM input",
+    );
+    sbom = readBinary(importTarget, true);
     printSummary(sbom);
-  } else if (
-    sbomOrPath.startsWith("ghcr.io") ||
-    sbomOrPath.startsWith("docker.io")
-  ) {
+  } else if (isSupportedSbomRegistryReference(importTarget)) {
     try {
-      sbom = getBomWithOras(sbomOrPath);
+      sbom = getBomWithOras(importTarget);
       if (sbom) {
         printSummary(sbom);
       } else {
         console.log(
-          `cyclonedx sbom attachment was not found within ${sbomOrPath}`,
+          `cyclonedx sbom attachment was not found within ${importTarget}`,
         );
       }
     } catch (e) {
-      console.log(`⚠ Unable to import the BOM from ${sbomOrPath} due to ${e}`);
+      console.log(
+        `⚠ Unable to import the BOM from ${importTarget} due to ${e}`,
+      );
     }
   } else {
-    console.log(`⚠ ${sbomOrPath} is invalid.`);
+    console.log(`⚠ ${importTarget} is invalid.`);
   }
 };
 // Load any sbom passed from the command line
 if (process.argv.length > 2) {
-  importSbom(process.argv[process.argv.length - 1]);
+  await importSbom(process.argv[process.argv.length - 1]);
   console.log("💭 Type .print to view the BOM as a table");
   console.log("💭 Type .trusted to list components with trusted publishing.");
   console.log(
     "💭 Type .provenance to list components with registry provenance evidence.",
   );
+  if (isLikelyHbom(sbom)) {
+    console.log(
+      "💭 Type .hbomsummary to review the host profile, evidence coverage, hardware-class mix, and collector diagnostics.",
+    );
+  }
   if (getAuditAnnotations().length) {
     console.log(
       "💭 Type .auditfindings to review cdx-audit and bom-audit annotations.",
     );
   }
-} else if (fs.existsSync("bom.json")) {
+} else if (safeExistsSync("bom.json")) {
   // If the current directory has a bom.json load it
-  importSbom("bom.json");
+  await importSbom("bom.json");
 } else {
   console.log("💭 Use .create <path> to create an SBOM for the given path.");
   console.log("💭 Use .import <json> to import an existing BOM.");
   console.log(
     "💭 For OBOM investigations, try .obomtips after importing an OBOM.",
   );
+  console.log(
+    "💭 For HBOM investigations, try .hbomtips after importing an HBOM.",
+  );
   console.log("💭 Type .exit or press ctrl+d to close.");
 }
 
@@ -333,7 +482,7 @@ cdxgenRepl.defineCommand("create", {
   help: "create an SBOM for the given path",
   async action(sbomOrPath) {
     this.clearBufferedCommand();
-    const tempDir = fs.mkdtempSync(join(getTmpDir(), "cdxgen-repl-"));
+    const tempDir = safeMkdtempSync(join(getTmpDir(), "cdxgen-repl-"));
     const bomFile = join(tempDir, "bom.json");
     const bomNSData = await createBom(sbomOrPath, {
       multiProject: true,
@@ -350,6 +499,11 @@ cdxgenRepl.defineCommand("create", {
       console.log(
         "💭 Type .provenance to list components with registry provenance evidence.",
       );
+      if (isLikelyHbom(sbom)) {
+        console.log(
+          "💭 Type .hbomsummary or .hbomdiagnostics for focused hardware inventory and collector-diagnostic summaries.",
+        );
+      }
       if (getAuditAnnotations().length) {
         console.log(
           "💭 Type .auditfindings to review cdx-audit and bom-audit annotations.",
@@ -368,9 +522,9 @@ cdxgenRepl.defineCommand("create", {
 });
 cdxgenRepl.defineCommand("import", {
   help: "import an existing BOM",
-  action(sbomOrPath) {
+  async action(sbomOrPath) {
     this.clearBufferedCommand();
-    importSbom(sbomOrPath);
+    await importSbom(sbomOrPath);
     this.displayPrompt();
   },
 });
@@ -387,6 +541,293 @@ cdxgenRepl.defineCommand("summary", {
     this.displayPrompt();
   },
 });
+cdxgenRepl.defineCommand("hbomsummary", {
+  help: "summarize HBOM host metadata, evidence coverage, and hardware-class mix",
+  action() {
+    const interactiveBom = getInteractiveBom();
+    if (!interactiveBom) {
+      console.log(
+        "⚠ No BOM is loaded. Use .import command to import an existing BOM",
+      );
+      this.displayPrompt();
+      return;
+    }
+    if (!isLikelyHbom(interactiveBom)) {
+      console.log(
+        "This BOM does not look like an HBOM. Import an HBOM generated with 'cdxgen -t hbom' to use this view.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    const hbomSummary = getHbomSummary(interactiveBom);
+    printKeyValueTable("HBOM summary", [
+      ["Host", hbomSummary.metadataName],
+      ["Component type", hbomSummary.metadataType],
+      ["Manufacturer", hbomSummary.manufacturer],
+      ["Platform", hbomSummary.platform],
+      ["Architecture", hbomSummary.architecture],
+      ["Collector profile", hbomSummary.collectorProfile],
+      ["Identifier policy", hbomSummary.identifierPolicy],
+      ["Component count", hbomSummary.componentCount],
+      ["Hardware class count", hbomSummary.hardwareClassCount],
+      [
+        "Top hardware classes",
+        formatHbomHardwareClassSummary(hbomSummary.hardwareClassCounts),
+      ],
+      ["Command evidence count", hbomSummary.evidenceCommandCount],
+      ["Observed file count", hbomSummary.evidenceFileCount],
+    ]);
+    this.displayPrompt();
+  },
+});
+cdxgenRepl.defineCommand("hbomclasses", {
+  help: "show HBOM component counts by hardware class",
+  action() {
+    const interactiveBom = getInteractiveBom();
+    if (!interactiveBom) {
+      console.log(
+        "⚠ No BOM is loaded. Use .import command to import an existing BOM",
+      );
+      this.displayPrompt();
+      return;
+    }
+    if (!isLikelyHbom(interactiveBom)) {
+      console.log(
+        "This BOM does not look like an HBOM. Import an HBOM generated with 'cdxgen -t hbom' to use this view.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    const hbomSummary = getHbomSummary(interactiveBom);
+    if (!hbomSummary.hardwareClassCounts.length) {
+      console.log(
+        "No HBOM hardware classes were found on the loaded BOM. Check whether the document includes cdx:hbom:hardwareClass properties.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    printAuditTable("HBOM hardware classes", [
+      ["Hardware class", "Count"],
+      ...hbomSummary.hardwareClassCounts.map(({ hardwareClass, count }) => [
+        hardwareClass,
+        `${count}`,
+      ]),
+    ]);
+    this.displayPrompt();
+  },
+});
+cdxgenRepl.defineCommand("hbomevidence", {
+  help: "show HBOM collector profile plus command and observed-file evidence",
+  action() {
+    const interactiveBom = getInteractiveBom();
+    if (!interactiveBom) {
+      console.log(
+        "⚠ No BOM is loaded. Use .import command to import an existing BOM",
+      );
+      this.displayPrompt();
+      return;
+    }
+    if (!isLikelyHbom(interactiveBom)) {
+      console.log(
+        "This BOM does not look like an HBOM. Import an HBOM generated with 'cdxgen -t hbom' to use this view.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    const hbomSummary = getHbomSummary(interactiveBom);
+    printKeyValueTable("HBOM evidence overview", [
+      ["Collector profile", hbomSummary.collectorProfile],
+      ["Command evidence count", hbomSummary.evidenceCommandCount],
+      ["Observed file count", hbomSummary.evidenceFileCount],
+    ]);
+    if (hbomSummary.evidenceCommands.length) {
+      printAuditTable("HBOM command evidence", [
+        ["Command #", "Evidence"],
+        ...hbomSummary.evidenceCommands.map((command, index) => [
+          `${index + 1}`,
+          command,
+        ]),
+      ]);
+    }
+    if (hbomSummary.evidenceFiles.length) {
+      printAuditTable("HBOM observed files", [
+        ["File #", "Path"],
+        ...hbomSummary.evidenceFiles.map((filePath, index) => [
+          `${index + 1}`,
+          filePath,
+        ]),
+      ]);
+    }
+    this.displayPrompt();
+  },
+});
+cdxgenRepl.defineCommand("hbomdiagnostics", {
+  help: "show parsed HBOM command diagnostics, issue counts, and install or privilege guidance",
+  action() {
+    const interactiveBom = getInteractiveHbomOrWarn(this);
+    if (!interactiveBom) {
+      return;
+    }
+    const hbomSummary = getHbomSummary(interactiveBom);
+    if (!hbomSummary.commandDiagnosticCount) {
+      console.log(
+        "No HBOM command diagnostics were found. This usually means the collector completed without recording missing-command or permission-denied enrichments.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    printKeyValueTable("HBOM diagnostic overview", [
+      ["Diagnostic count", hbomSummary.commandDiagnosticCount],
+      ["Actionable diagnostics", hbomSummary.actionableDiagnosticCount],
+      ["Missing commands", hbomSummary.missingCommandCount],
+      ["Permission denied", hbomSummary.permissionDeniedCount],
+      ["Partial support", hbomSummary.partialSupportCount],
+      ["Timeouts", hbomSummary.timeoutCount],
+      ["Other command errors", hbomSummary.commandErrorCount],
+      ["Diagnostic issues", hbomSummary.diagnosticIssues.join(", ")],
+      ["Missing command IDs", hbomSummary.missingCommandIds.join(", ")],
+      ["Permission-denied IDs", hbomSummary.permissionDeniedIds.join(", ")],
+      ["Install hint count", hbomSummary.installHintCount],
+      ["Privilege hint count", hbomSummary.privilegeHintCount],
+      [
+        "Requires privileged rerun",
+        hbomSummary.requiresPrivilegedEnrichment ? "yes" : "no",
+      ],
+    ]);
+    printAuditTable("HBOM command diagnostics", [
+      ["Issue", "Diagnostic ID", "Command", "Hint / Message"],
+      ...hbomSummary.commandDiagnostics.map((diagnostic) => [
+        diagnostic.issue || "unknown",
+        diagnostic.id || "-",
+        diagnostic.command || "-",
+        getDiagnosticDisplayDetail(diagnostic),
+      ]),
+    ]);
+    this.displayPrompt();
+  },
+});
+cdxgenRepl.defineCommand("hbomfirmware", {
+  help: "show firmware, board, TPM, and update-managed HBOM components plus host firmware provenance",
+  action() {
+    const interactiveBom = getInteractiveHbomOrWarn(this);
+    if (!interactiveBom) {
+      return;
+    }
+    const metadataComponent = interactiveBom.metadata?.component;
+    const firmwareComponents = filterHbomComponentsByProperties(
+      interactiveBom,
+      HBOM_FIRMWARE_PROPERTIES,
+      ["firmware", "board", "tpm"],
+    );
+    const metadataEntries = [
+      [
+        "Board vendor",
+        getPropertyValue(metadataComponent, "cdx:hbom:boardVendor"),
+      ],
+      ["Board name", getPropertyValue(metadataComponent, "cdx:hbom:boardName")],
+      [
+        "BIOS vendor",
+        getPropertyValue(metadataComponent, "cdx:hbom:biosVendor"),
+      ],
+      [
+        "BIOS version",
+        getPropertyValue(metadataComponent, "cdx:hbom:biosVersion"),
+      ],
+      [
+        "Firmware date",
+        getPropertyValue(metadataComponent, "cdx:hbom:firmwareDate"),
+      ],
+      [
+        "Device-tree revision",
+        getPropertyValue(metadataComponent, "cdx:hbom:deviceTreeRevision"),
+      ],
+    ];
+    const hasMetadataProvenance = metadataEntries.some(([, value]) =>
+      Boolean(value),
+    );
+    if (!firmwareComponents.length && !hasMetadataProvenance) {
+      console.log(
+        "No focused firmware or board provenance pivots were found. Import an HBOM from a host that exposes board, TPM, or firmware-management metadata to use this view.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    if (hasMetadataProvenance) {
+      printKeyValueTable("HBOM host firmware provenance", metadataEntries);
+    }
+    if (firmwareComponents.length) {
+      printTable(
+        { components: firmwareComponents, dependencies: [] },
+        undefined,
+        undefined,
+        `Found ${firmwareComponents.length} firmware, board, TPM, or update-managed component(s).`,
+      );
+    }
+    this.displayPrompt();
+  },
+});
+cdxgenRepl.defineCommand("hbombuses", {
+  help: "show bus, connector, USB, PCI, and external-expansion HBOM components with security or topology metadata",
+  action() {
+    const interactiveBom = getInteractiveHbomOrWarn(this);
+    if (!interactiveBom) {
+      return;
+    }
+    const busComponents = filterHbomComponentsByProperties(
+      interactiveBom,
+      HBOM_BUS_SECURITY_PROPERTIES,
+      [
+        "bus",
+        "usb-device",
+        "pci-device",
+        "display-adapter",
+        "display-connector",
+      ],
+    );
+    if (!busComponents.length) {
+      console.log(
+        "No bus or connector components with focused security or topology metadata were found.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    printTable(
+      { components: busComponents, dependencies: [] },
+      undefined,
+      undefined,
+      `Found ${busComponents.length} bus, USB, PCI, or display-link component(s) with bus-security or topology pivots.`,
+    );
+    this.displayPrompt();
+  },
+});
+cdxgenRepl.defineCommand("hbompower", {
+  help: "show HBOM power and battery components with detailed design-capacity and runtime telemetry",
+  action() {
+    const interactiveBom = getInteractiveHbomOrWarn(this);
+    if (!interactiveBom) {
+      return;
+    }
+    const powerComponents = filterHbomComponentsByProperties(
+      interactiveBom,
+      HBOM_POWER_PROPERTIES,
+      ["power"],
+    );
+    if (!powerComponents.length) {
+      console.log(
+        "No focused power or battery telemetry components were found on the loaded HBOM.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    printTable(
+      { components: powerComponents, dependencies: [] },
+      undefined,
+      undefined,
+      `Found ${powerComponents.length} power or battery component(s) with detailed runtime telemetry.`,
+    );
+    this.displayPrompt();
+  },
+});
 cdxgenRepl.defineCommand("exit", {
   help: "exit",
   action() {
@@ -447,7 +888,7 @@ cdxgenRepl.defineCommand("search", {
           console.log(e);
         }
       } else {
-        console.log("⚠ Specify the search string. Eg: .search <search string>");
+        console.log('⚠ Specify the search string. Eg: .search "search string"');
       }
     } else {
       console.log(
@@ -596,6 +1037,90 @@ cdxgenRepl.defineCommand("cryptos", {
     this.displayPrompt();
   },
 });
+cdxgenRepl.defineCommand("sourcecryptos", {
+  help: "show source-derived cryptographic assets detected from JS AST analysis",
+  action() {
+    const interactiveBom = getInteractiveBom();
+    if (!interactiveBom?.components) {
+      console.log("⚠ No BOM is loaded. Use .import command to import an SBOM");
+      this.displayPrompt();
+      return;
+    }
+    const sourceCryptoComponents = getSourceDerivedCryptoComponents(
+      interactiveBom.components,
+    );
+    if (!sourceCryptoComponents.length) {
+      console.log(
+        "No source-derived crypto assets found. Generate a CBOM or SBOM with source crypto analysis to use this view.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    printTable(
+      { components: sourceCryptoComponents, dependencies: [] },
+      ["cryptographic-asset"],
+      undefined,
+      `Found ${sourceCryptoComponents.length} source-derived cryptographic asset component(s).`,
+    );
+    this.displayPrompt();
+  },
+});
+cdxgenRepl.defineCommand("unpackagedbins", {
+  help: "show executable file components that were not matched to OS package ownership",
+  action() {
+    const interactiveBom = getInteractiveBom();
+    if (!interactiveBom?.components) {
+      console.log("⚠ No BOM is loaded. Use .import command to import an SBOM");
+      this.displayPrompt();
+      return;
+    }
+    const unpackagedExecutables = getUnpackagedExecutableComponents(
+      interactiveBom.components,
+    );
+    if (!unpackagedExecutables.length) {
+      console.log(
+        "No unpackaged executable file components found. Import a container or rootfs BOM with native file inventory to use this view.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    printTable(
+      { components: unpackagedExecutables, dependencies: [] },
+      ["file"],
+      undefined,
+      `Found ${unpackagedExecutables.length} executable file component(s) that were not traced to OS package ownership.`,
+    );
+    this.displayPrompt();
+  },
+});
+cdxgenRepl.defineCommand("unpackagedlibs", {
+  help: "show shared library file components that were not matched to OS package ownership",
+  action() {
+    const interactiveBom = getInteractiveBom();
+    if (!interactiveBom?.components) {
+      console.log("⚠ No BOM is loaded. Use .import command to import an SBOM");
+      this.displayPrompt();
+      return;
+    }
+    const unpackagedSharedLibraries = getUnpackagedSharedLibraryComponents(
+      interactiveBom.components,
+    );
+    if (!unpackagedSharedLibraries.length) {
+      console.log(
+        "No unpackaged shared library file components found. Import a container or rootfs BOM with native file inventory to use this view.",
+      );
+      this.displayPrompt();
+      return;
+    }
+    printTable(
+      { components: unpackagedSharedLibraries, dependencies: [] },
+      ["file"],
+      undefined,
+      `Found ${unpackagedSharedLibraries.length} shared library file component(s) that were not traced to OS package ownership.`,
+    );
+    this.displayPrompt();
+  },
+});
 cdxgenRepl.defineCommand("frameworks", {
   help: "print the components of type framework as a table",
   action() {
@@ -660,7 +1185,14 @@ cdxgenRepl.defineCommand("save", {
       if (!saveToFile) {
         saveToFile = "bom.json";
       }
-      fs.writeFileSync(saveToFile, JSON.stringify(sbom, null, null));
+      if (isDryRun) {
+        console.log(
+          `⚠ Dry run mode blocks saving the BOM to ${saveToFile}. Disable --dry-run or CDXGEN_DRY_RUN to persist it.`,
+        );
+        this.displayPrompt();
+        return;
+      }
+      safeWriteSync(saveToFile, JSON.stringify(sbom, null, 2));
       console.log(`BOM saved successfully to ${saveToFile}`);
     } else {
       console.log(
@@ -1049,6 +1581,25 @@ cdxgenRepl.defineCommand("obomtips", {
     this.displayPrompt();
   },
 });
+cdxgenRepl.defineCommand("hbomtips", {
+  help: "show analyst tips and useful commands for HBOM investigations",
+  action() {
+    console.log("HBOM analyst quick guide:");
+    console.log("1. .hbomsummary");
+    console.log("2. .hbomclasses");
+    console.log("3. .hbomevidence");
+    console.log("4. .hbomdiagnostics");
+    console.log("5. .hbomfirmware / .hbombuses / .hbompower");
+    console.log(
+      "6. .auditfindings to review hbom-security, hbom-performance, and hbom-compliance findings",
+    );
+    console.log("7. .search <hardwareClass or device name>");
+    console.log(
+      'Tip: .query components[properties[name="cdx:hbom:hardwareClass" and value="storage"]] filters directly by hardware class.',
+    );
+    this.displayPrompt();
+  },
+});
 cdxgenRepl.defineCommand("licenses", {
   help: "visualize license distribution",
   async action() {
@@ -1249,6 +1800,7 @@ cdxgenRepl.defineCommand("tagcloud", {
   "docker_volumes",
   "etc_hosts",
   "firefox_addons",
+  "gatekeeper",
   "vscode_extensions",
   "homebrew_packages",
   "installed_applications",
@@ -1265,8 +1817,10 @@ cdxgenRepl.defineCommand("tagcloud", {
   "portage_packages",
   "process_events",
   "processes",
+  "secureboot_certificates",
   "privilege_transitions",
   "privileged_listening_ports",
+  "npm_packages",
   "python_packages",
   "rpm_packages",
   "scheduled_tasks",
@@ -1291,6 +1845,7 @@ cdxgenRepl.defineCommand("tagcloud", {
   "npm_packages",
   "opera_extensions",
   "pipes_snapshot",
+  "process_open_handles_snapshot",
   "process_open_sockets",
   "safari_extensions",
   "scheduled_tasks",