@cdxgen/cdxgen 0.0.1 → 13.0.0

package/bin/hbom.js

@@ -0,0 +1,495 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import process from "node:process";
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+import { createHBom } from "../lib/cli/index.js";
+import { thoughtLog } from "../lib/core/logger.js";
+import {
+  DEBUG_MODE,
+  isDryRun,
+  retrieveCdxgenVersion,
+  safeExistsSync,
+  safeMkdirSync,
+  safeWriteSync,
+  setActivityContext,
+  setDryRunMode,
+} from "../lib/ecosystems/utils.js";
+import { getOutputDirectory } from "../lib/helpers/exportUtils.js";
+import { printActivitySummary } from "../lib/inventory/display.js";
+import {
+  ensureNoMixedHbomProjectTypes,
+  ensureSupportedHbomSpecVersion,
+  hasHbomProjectType,
+} from "../lib/inventory/hbom.js";
+import { getHbomSummary } from "../lib/inventory/hbomAnalysis.js";
+import {
+  importProtobomModule,
+  isProtoBomPath,
+} from "../lib/inventory/protobomLoader.js";
+import { validateBom } from "../lib/validator/bomValidator.js";
+
+function determineHbomCommandName() {
+  const invokedScriptName = basename(process.argv[1] || "hbom").replace(
+    /\.(?:[cm]?js|exe)$/u,
+    "",
+  );
+  return invokedScriptName || "hbom";
+}
+
+const hbomCommandName = determineHbomCommandName();
+
+const _yargs = yargs(hideBin(process.argv));
+
+const args = _yargs
+  .parserConfiguration({
+    "boolean-negation": true,
+    "greedy-arrays": false,
+    "parse-numbers": true,
+    "short-option-groups": false,
+  })
+  .usage("$0 [command] [options]")
+  .command(
+    "diagnostics",
+    "Identify HBOM collector missing-command and permission-denied issues from a live run or an existing HBOM JSON file.",
+  )
+  .option("output", {
+    alias: "o",
+    default: "hbom.json",
+    description: "Output file. Default hbom.json",
+    type: "string",
+  })
+  .option("print", {
+    alias: "p",
+    description:
+      "Print the generated HBOM to stdout instead of writing a file.",
+    type: "boolean",
+    default: false,
+  })
+  .option("pretty", {
+    description: "Pretty-print the generated HBOM JSON.",
+    type: "boolean",
+    default: true,
+  })
+  .option("validate", {
+    description: "Validate the generated HBOM using the CycloneDX schema.",
+    type: "boolean",
+    default: true,
+  })
+  .option("export-proto", {
+    description:
+      "Serialize and export the generated HBOM as a protobuf binary.",
+    type: "boolean",
+    default: false,
+  })
+  .option("proto-bin-file", {
+    description: "Path for the serialized protobuf HBOM binary.",
+    type: "string",
+    default: "hbom.cdx",
+  })
+  .option("dry-run", {
+    description:
+      "Read-only mode. Report the requested HBOM collection and block host probing plus filesystem writes.",
+    type: "boolean",
+    default: isDryRun,
+  })
+  .option("spec-version", {
+    choices: [1.7],
+    default: 1.7,
+    description:
+      "CycloneDX specification version to use. HBOM currently supports 1.7 only.",
+    type: "number",
+  })
+  .option("platform", {
+    description: "Override platform selection.",
+    type: "string",
+  })
+  .option("arch", {
+    description: "Override architecture selection.",
+    type: "string",
+  })
+  .option("sensitive", {
+    description: "Include raw identifiers instead of redacted defaults.",
+    type: "boolean",
+    default: false,
+  })
+  .option("no-command-enrichment", {
+    description: "Disable optional command-based enrichment.",
+    type: "boolean",
+    default: false,
+  })
+  .option("include-runtime", {
+    description:
+      "Collect OBOM runtime inventory alongside the HBOM and emit a merged host view with strict topology links.",
+    type: "boolean",
+    default: false,
+  })
+  .option("privileged", {
+    description:
+      "Enable privileged Linux enrichment and non-interactive sudo retries for documented permission-sensitive commands.",
+    type: "boolean",
+    default: false,
+  })
+  .option("plist-enrichment", {
+    description: "Enable additional Darwin plist-based enrichment.",
+    type: "boolean",
+    default: false,
+  })
+  .option("strict", {
+    description:
+      "Fail instead of returning partial results when enrichment fails.",
+    type: "boolean",
+    default: false,
+  })
+  .option("timeout", {
+    description:
+      "Per-command timeout in milliseconds. Increase this on slower hosts such as Raspberry Pi systems.",
+    type: "number",
+  })
+  .option("type", {
+    description:
+      "Compatibility project type flag. Only 'hbom' or 'hardware' are accepted.",
+    hidden: true,
+  })
+  .option("input", {
+    alias: "i",
+    description:
+      "Read an existing HBOM JSON or protobuf file instead of collecting a fresh live inventory. Primarily useful with the diagnostics command.",
+    type: "string",
+  })
+  .option("json", {
+    description:
+      "Print the diagnostics summary as JSON instead of human-readable text. Only applies to the diagnostics command.",
+    type: "boolean",
+    default: false,
+  })
+  .array("type")
+  .example([
+    ["$0", "Generate an HBOM file for the current host"],
+    ["$0 -p", "Print the generated HBOM to stdout"],
+    ["$0 --platform linux --arch amd64", "Override target selection"],
+    ["$0 --privileged --pretty", "Enable privileged Linux enrichment"],
+    [
+      "$0 diagnostics",
+      "Run a live HBOM diagnostic pass and summarize missing commands or permission-sensitive enrichments",
+    ],
+    [
+      "$0 diagnostics --input hbom.json",
+      "Summarize missing commands or permission-denied enrichments from an existing HBOM file",
+    ],
+  ])
+  .scriptName(hbomCommandName)
+  .version(retrieveCdxgenVersion())
+  .alias("v", "version")
+  .help(false)
+  .option("help", {
+    alias: "h",
+    description: "Show help",
+    type: "boolean",
+  })
+  .wrap(Math.min(120, yargs().terminalWidth())).argv;
+
+if (args.help) {
+  console.log(`${retrieveCdxgenVersion()}\n`);
+  _yargs.showHelp();
+  process.exit(0);
+}
+
+const requestedTypes = args.type?.length ? args.type : ["hbom"];
+const selectedCommand = `${args._?.[0] ?? "generate"}`;
+
+try {
+  ensureNoMixedHbomProjectTypes(requestedTypes);
+  ensureSupportedHbomSpecVersion(args.specVersion);
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}
+if (!hasHbomProjectType(requestedTypes)) {
+  console.error(
+    `The '${hbomCommandName}' command only supports the 'hbom' or 'hardware' project type.`,
+  );
+  process.exit(1);
+}
+
+const options = {
+  arch: args.arch,
+  command: selectedCommand,
+  commandName: hbomCommandName,
+  dryRun: args.dryRun,
+  input: args.input ? resolve(args.input) : undefined,
+  noCommandEnrichment: args.noCommandEnrichment,
+  includeRuntime: args.includeRuntime,
+  json: args.json,
+  output: resolve(args.output),
+  platform: args.platform,
+  plistEnrichment: args.plistEnrichment,
+  pretty: args.pretty,
+  print: args.print,
+  privileged: args.privileged,
+  exportProto: args.exportProto,
+  protoBinFile: resolve(args.protoBinFile),
+  projectType: [requestedTypes[0]],
+  sensitive: args.sensitive,
+  specVersion: args.specVersion,
+  strict: args.strict,
+  timeout: args.timeout,
+  validate: args.validate,
+};
+
+setDryRunMode(options.dryRun);
+setActivityContext({
+  projectType: requestedTypes[0],
+  sourcePath: process.cwd(),
+});
+
+if (options.dryRun) {
+  thoughtLog(
+    "HBOM dry-run mode is enabled. I must keep collection read-only, block command enrichment, and avoid filesystem writes.",
+  );
+}
+
+function groupDiagnosticsByIssue(issue, commandDiagnostics = []) {
+  const groupedDiagnostics = new Map();
+
+  for (const entry of commandDiagnostics) {
+    if (entry?.issue !== issue) {
+      continue;
+    }
+    const commandName = `${entry.command ?? entry.id ?? "command"}`;
+    const hint = `${entry.installHint ?? entry.privilegeHint ?? ""}`.trim();
+    const message = `${entry.message ?? ""}`.trim();
+    const groupingKey = [commandName, issue, hint, message].join("\u0000");
+    const currentEntry = groupedDiagnostics.get(groupingKey) ?? {
+      command: commandName,
+      count: 0,
+      hint: hint || undefined,
+      message: message || undefined,
+    };
+    currentEntry.count += 1;
+    groupedDiagnostics.set(groupingKey, currentEntry);
+  }
+
+  return [...groupedDiagnostics.values()].sort((firstEntry, secondEntry) =>
+    firstEntry.command.localeCompare(secondEntry.command),
+  );
+}
+
+function buildFormattedDiagnosticLines(groupedEntries = []) {
+  return groupedEntries.flatMap((entry) => {
+    const headline = `- ${entry.command}${entry.count > 1 ? ` (${entry.count} invocations)` : ""}`;
+    const detailParts = [];
+    if (entry.message) {
+      detailParts.push(entry.message);
+    }
+    if (entry.hint) {
+      detailParts.push(`Hint: ${entry.hint}`);
+    }
+    if (!detailParts.length) {
+      return [headline];
+    }
+    return [headline, ...detailParts.map((value) => `  ${value}`)];
+  });
+}
+
+function printHbomDiagnosticNotice(bomJson) {
+  const hbomSummary = getHbomSummary(bomJson);
+  if (!hbomSummary.actionableDiagnosticCount) {
+    return;
+  }
+  const detailParts = [];
+  if (hbomSummary.missingCommandCount) {
+    detailParts.push(`${hbomSummary.missingCommandCount} missing command`);
+  }
+  if (hbomSummary.permissionDeniedCount) {
+    detailParts.push(
+      `${hbomSummary.permissionDeniedCount} permission-denied enrichment`,
+    );
+  }
+  const followUpCommand = options.print
+    ? `${hbomCommandName} diagnostics`
+    : `${hbomCommandName} diagnostics --input ${options.output}`;
+  console.error(
+    `HBOM collector reported ${hbomSummary.actionableDiagnosticCount} actionable diagnostic(s) (${detailParts.join(", ")}). Run '${followUpCommand}' for detailed install and privilege guidance.`,
+  );
+}
+
+async function loadBomFromInputFile(inputFile) {
+  if (!inputFile || !safeExistsSync(inputFile)) {
+    throw new Error(`HBOM input file not found: ${inputFile}`);
+  }
+  if (isProtoBomPath(inputFile)) {
+    const { readBinary } = await importProtobomModule(
+      hbomCommandName,
+      "protobuf BOM input",
+    );
+    return readBinary(inputFile, true);
+  }
+  return JSON.parse(readFileSync(inputFile, { encoding: "utf8" }));
+}
+
+function printHbomDiagnosticsReport(bomJson) {
+  const hbomSummary = getHbomSummary(bomJson);
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          actionableDiagnosticCount: hbomSummary.actionableDiagnosticCount,
+          architecture: hbomSummary.architecture,
+          collectorProfile: hbomSummary.collectorProfile,
+          commandDiagnosticCount: hbomSummary.commandDiagnosticCount,
+          commandDiagnostics: hbomSummary.commandDiagnostics,
+          commandErrorCount: hbomSummary.commandErrorCount,
+          diagnosticIssues: hbomSummary.diagnosticIssues,
+          installHints: hbomSummary.installHints,
+          metadataName: hbomSummary.metadataName,
+          missingCommandCount: hbomSummary.missingCommandCount,
+          missingCommands: hbomSummary.missingCommands,
+          partialSupportCount: hbomSummary.partialSupportCount,
+          permissionDeniedCommands: hbomSummary.permissionDeniedCommands,
+          permissionDeniedCount: hbomSummary.permissionDeniedCount,
+          platform: hbomSummary.platform,
+          privilegeHints: hbomSummary.privilegeHints,
+          requiresPrivilegedEnrichment:
+            hbomSummary.requiresPrivilegedEnrichment,
+          timeoutCount: hbomSummary.timeoutCount,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  const missingCommands = groupDiagnosticsByIssue(
+    "missing-command",
+    hbomSummary.commandDiagnostics,
+  );
+  const permissionDeniedCommands = groupDiagnosticsByIssue(
+    "permission-denied",
+    hbomSummary.commandDiagnostics,
+  );
+
+  console.log("HBOM diagnostics summary");
+  console.log(
+    `Target: ${hbomSummary.platform ?? "unknown"}/${hbomSummary.architecture ?? "unknown"}`,
+  );
+  if (hbomSummary.collectorProfile) {
+    console.log(`Collector profile: ${hbomSummary.collectorProfile}`);
+  }
+  if (hbomSummary.metadataName) {
+    console.log(`Host: ${hbomSummary.metadataName}`);
+  }
+  console.log(`Total diagnostics: ${hbomSummary.commandDiagnosticCount}`);
+  console.log(`Missing commands: ${hbomSummary.missingCommandCount}`);
+  console.log(`Permission denied: ${hbomSummary.permissionDeniedCount}`);
+  console.log(`Partial support: ${hbomSummary.partialSupportCount}`);
+  console.log(`Timeouts: ${hbomSummary.timeoutCount}`);
+  console.log(`Other command errors: ${hbomSummary.commandErrorCount}`);
+
+  if (!hbomSummary.commandDiagnosticCount) {
+    console.log("No HBOM collector diagnostics were found.");
+    return;
+  }
+
+  if (missingCommands.length) {
+    console.log("\nMissing commands:");
+    for (const line of buildFormattedDiagnosticLines(missingCommands)) {
+      console.log(line);
+    }
+  }
+
+  if (permissionDeniedCommands.length) {
+    console.log("\nPermission-sensitive enrichments:");
+    for (const line of buildFormattedDiagnosticLines(
+      permissionDeniedCommands,
+    )) {
+      console.log(line);
+    }
+  }
+
+  if (hbomSummary.requiresPrivilegedEnrichment) {
+    console.log(
+      "\nSome Linux enrichments can likely succeed only with --privileged and a target environment that allows non-interactive sudo.",
+    );
+  }
+}
+
+async function runDiagnosticsCommand() {
+  if (options.includeRuntime) {
+    thoughtLog(
+      "The diagnostics subcommand focuses on HBOM collector gaps only, so I will skip the merged runtime host view.",
+    );
+  }
+  const bomJson = options.input
+    ? await loadBomFromInputFile(options.input)
+    : (
+        await createHBom(process.cwd(), {
+          ...options,
+          includeRuntime: false,
+          print: false,
+          validate: false,
+        })
+      ).bomJson;
+  printHbomDiagnosticsReport(bomJson);
+}
+
+(async () => {
+  if (selectedCommand === "diagnostics") {
+    await runDiagnosticsCommand();
+    if (options.dryRun || DEBUG_MODE) {
+      printActivitySummary();
+    }
+    return;
+  }
+  thoughtLog(
+    "Let's generate a Hardware Bill-of-Materials (HBOM) for this host.",
+  );
+  if (options.includeRuntime) {
+    thoughtLog(
+      "Let's also collect the runtime inventory so I can build a merged HBOM+OBOM host view without guessing relationships.",
+    );
+  }
+  const { bomJson } = await createHBom(process.cwd(), options);
+  if (options.validate && !(await validateBom(bomJson))) {
+    process.exit(1);
+  }
+  const output = JSON.stringify(bomJson, null, options.pretty ? 2 : null);
+  if (options.print) {
+    console.log(output);
+  } else {
+    const outputDirectory = getOutputDirectory(options.output);
+    if (outputDirectory && !safeExistsSync(outputDirectory)) {
+      safeMkdirSync(outputDirectory, { recursive: true });
+    }
+    safeWriteSync(options.output, output);
+    thoughtLog(`Let's save the HBOM file to '${options.output}'.`);
+  }
+  if (options.exportProto) {
+    const protoOutputDirectory = getOutputDirectory(options.protoBinFile);
+    if (protoOutputDirectory && !safeExistsSync(protoOutputDirectory)) {
+      safeMkdirSync(protoOutputDirectory, { recursive: true });
+    }
+    const { writeBinary } = await importProtobomModule(
+      hbomCommandName,
+      "protobuf export",
+    );
+    writeBinary(bomJson, options.protoBinFile);
+    thoughtLog(
+      `Let's also save the HBOM protobuf binary to '${options.protoBinFile}'.`,
+    );
+  }
+  printHbomDiagnosticNotice(bomJson);
+  if (options.dryRun || DEBUG_MODE) {
+    printActivitySummary();
+  }
+})().catch((error) => {
+  if (options.dryRun || DEBUG_MODE) {
+    printActivitySummary();
+  }
+  console.error(error.message || error);
+  process.exit(1);
+});