@cyclonedx/cdxgen 12.3.3 → 12.4.1

package/lib/helpers/utils.js

@@ -56,17 +56,25 @@ import { getTreeWithPlugin } from "../managers/piptree.js";
 import { IriValidationStrategy, validateIri } from "../parsers/iri.js";
 import Arborist from "../third-party/arborist/lib/index.js";
 import { analyzeSuspiciousJsFile } from "./analyzer.js";
+import { DEFAULT_HBOM_AUDIT_CATEGORIES } from "./auditCategories.js";
 import { parseWorkflowFile } from "./ciParsers/githubActions.js";
 import { extractPackageInfoFromHintPath } from "./dotnetutils.js";
+import {
+  createOccurrenceEvidence,
+  parseOccurrenceEvidenceLocation,
+} from "./evidenceUtils.js";
+import { createGtfoBinsPropertiesFromRow } from "./gtfobins.js";
 import { thoughtLog, traceLog } from "./logger.js";
 import { createLolbasProperties } from "./lolbas.js";
 import {
+  createOsQueryFallbackBomRef,
   createOsQueryPurl,
   deriveOsQueryDescription,
   deriveOsQueryName,
   deriveOsQueryPublisher,
   deriveOsQueryVersion,
   sanitizeOsQueryIdentity,
+  shouldCreateOsQueryPurl,
 } from "./osqueryTransform.js";
 import {
   collectPyLockFileComponents,
@@ -117,6 +125,596 @@ export const DRY_RUN_ERROR_CODE = "CDXGEN_DRY_RUN";
 const activityLedger = [];
 let activityCounter = 0;
 let currentActivityContext = {};
+const dryRunReadTraceState =
+  globalThis.__cdxgenDryRunReadTraceState ||
+  (globalThis.__cdxgenDryRunReadTraceState = {
+    environmentReads: new Map(),
+    observations: new Map(),
+    recordActivity: undefined,
+    sensitiveFileReads: new Map(),
+  });
+const SENSITIVE_ENV_VAR_PATTERN =
+  /(^|_)(?:token|key|secret|pass(?:word)?|credential(?:s)?|cred|auth|session|cookie|email|user)$/i;
+const DIRECTORY_DISCOVERY_NAMES = new Set([
+  ".cargo",
+  ".docker",
+  ".gem",
+  ".github",
+  ".m2",
+  ".nuget",
+  ".venv",
+  ".yarn",
+  "blobs",
+  "extensions",
+  "node_modules",
+  "target",
+  "vendor",
+]);
+const LOCKFILE_ACTIVITY_HINTS = new Map([
+  [
+    "bun.lock",
+    { classification: "lockfile", ecosystem: "bun", label: "Bun lockfile" },
+  ],
+  [
+    "cargo.lock",
+    { classification: "lockfile", ecosystem: "cargo", label: "Cargo lockfile" },
+  ],
+  [
+    "composer.lock",
+    {
+      classification: "lockfile",
+      ecosystem: "composer",
+      label: "Composer lockfile",
+    },
+  ],
+  [
+    "gemfile.lock",
+    {
+      classification: "lockfile",
+      ecosystem: "rubygems",
+      label: "Bundler lockfile",
+    },
+  ],
+  [
+    "package-lock.json",
+    { classification: "lockfile", ecosystem: "npm", label: "npm lockfile" },
+  ],
+  [
+    "packages.lock.json",
+    { classification: "lockfile", ecosystem: "nuget", label: "NuGet lockfile" },
+  ],
+  [
+    "pdm.lock",
+    { classification: "lockfile", ecosystem: "python", label: "PDM lockfile" },
+  ],
+  [
+    "pnpm-lock.yaml",
+    { classification: "lockfile", ecosystem: "pnpm", label: "pnpm lockfile" },
+  ],
+  [
+    "poetry.lock",
+    {
+      classification: "lockfile",
+      ecosystem: "python",
+      label: "Poetry lockfile",
+    },
+  ],
+  [
+    "podfile.lock",
+    {
+      classification: "lockfile",
+      ecosystem: "cocoapods",
+      label: "CocoaPods lockfile",
+    },
+  ],
+  [
+    "pylock.toml",
+    {
+      classification: "lockfile",
+      ecosystem: "python",
+      label: "PEP 751 lockfile",
+    },
+  ],
+  [
+    "uv.lock",
+    { classification: "lockfile", ecosystem: "python", label: "uv lockfile" },
+  ],
+  [
+    "yarn.lock",
+    { classification: "lockfile", ecosystem: "yarn", label: "Yarn lockfile" },
+  ],
+]);
+const MANIFEST_ACTIVITY_HINTS = new Map([
+  [
+    "cargo.toml",
+    { classification: "manifest", ecosystem: "cargo", label: "Cargo manifest" },
+  ],
+  [
+    "composer.json",
+    {
+      classification: "manifest",
+      ecosystem: "composer",
+      label: "Composer manifest",
+    },
+  ],
+  [
+    "gemfile",
+    {
+      classification: "manifest",
+      ecosystem: "rubygems",
+      label: "Gem manifest",
+    },
+  ],
+  [
+    "package.json",
+    { classification: "manifest", ecosystem: "npm", label: "package manifest" },
+  ],
+  [
+    "pom.xml",
+    { classification: "manifest", ecosystem: "maven", label: "Maven manifest" },
+  ],
+  [
+    "pyproject.toml",
+    {
+      classification: "manifest",
+      ecosystem: "python",
+      label: "Python project manifest",
+    },
+  ],
+  [
+    "requirements.txt",
+    {
+      classification: "manifest",
+      ecosystem: "python",
+      label: "Python requirements manifest",
+    },
+  ],
+  [
+    "setup.py",
+    {
+      classification: "manifest",
+      ecosystem: "python",
+      label: "Python setup manifest",
+    },
+  ],
+]);
+const SENSITIVE_CONFIG_ACTIVITY_HINTS = [
+  {
+    matcher: (lowerPath, _baseName) =>
+      lowerPath.includes("/.cargo/config.toml") ||
+      lowerPath.endsWith("/.cargo/credentials") ||
+      lowerPath.endsWith("/.cargo/credentials.toml"),
+    metadata: {
+      classification: "config",
+      ecosystem: "cargo",
+      label: "Cargo registry configuration",
+      sensitive: true,
+    },
+  },
+  {
+    matcher: (lowerPath, baseName) =>
+      lowerPath.includes("/.docker/config.json") ||
+      (baseName === "config.json" && lowerPath.includes("/docker")),
+    metadata: {
+      classification: "credential",
+      ecosystem: "oci",
+      label: "Docker credential file",
+      sensitive: true,
+    },
+  },
+  {
+    matcher: (lowerPath) => lowerPath.endsWith("/.gem/credentials"),
+    metadata: {
+      classification: "credential",
+      ecosystem: "rubygems",
+      label: "RubyGems credentials file",
+      sensitive: true,
+    },
+  },
+  {
+    matcher: (_lowerPath, baseName) =>
+      baseName === ".npmrc" || baseName === ".pnpmrc" || baseName === ".yarnrc",
+    metadata: {
+      classification: "config",
+      ecosystem: "npm",
+      label: "JavaScript package manager configuration",
+      sensitive: true,
+    },
+  },
+  {
+    matcher: (_lowerPath, baseName) => baseName === ".yarnrc.yml",
+    metadata: {
+      classification: "config",
+      ecosystem: "yarn",
+      label: "Yarn configuration",
+      sensitive: true,
+    },
+  },
+  {
+    matcher: (_lowerPath, baseName) =>
+      baseName === ".pypirc" || baseName === "pip.conf",
+    metadata: {
+      classification: "config",
+      ecosystem: "python",
+      label: "Python package publishing configuration",
+      sensitive: true,
+    },
+  },
+  {
+    matcher: (_lowerPath, baseName) =>
+      baseName === "uv.toml" || baseName === "poetry.toml",
+    metadata: {
+      classification: "config",
+      ecosystem: "python",
+      label: "Python package manager configuration",
+      sensitive: true,
+    },
+  },
+  {
+    matcher: (_lowerPath, baseName) => baseName === "nuget.config",
+    metadata: {
+      classification: "config",
+      ecosystem: "nuget",
+      label: "NuGet configuration",
+      sensitive: true,
+    },
+  },
+  {
+    matcher: (_lowerPath, baseName) => baseName === "settings.xml",
+    metadata: {
+      classification: "config",
+      ecosystem: "maven",
+      label: "Maven settings.xml",
+      sensitive: true,
+    },
+  },
+];
+const CERTIFICATE_FILE_EXTENSIONS = new Set([".crt", ".cer", ".pem"]);
+const KEY_FILE_EXTENSIONS = new Set([
+  ".key",
+  ".jks",
+  ".keystore",
+  ".p12",
+  ".pfx",
+]);
+
+const buildReadCountSuffix = (count) => (count > 1 ? ` (${count} times)` : "");
+
+const buildEnvironmentReadReason = (varName, count, sensitive) =>
+  `Read ${sensitive ? "sensitive " : ""}environment variable ${varName}${buildReadCountSuffix(count)}.`;
+
+const buildSensitiveFileReadReason = (filePath, count, label) =>
+  `Read ${label} ${filePath}${buildReadCountSuffix(count)}.`;
+
+function emitActivity(activity) {
+  if (typeof dryRunReadTraceState.recordActivity !== "function") {
+    return undefined;
+  }
+  return dryRunReadTraceState.recordActivity(activity);
+}
+
+function classifyActivityPath(filePath) {
+  if (typeof filePath !== "string" || !filePath.length) {
+    return undefined;
+  }
+  const normalizedPath = filePath.replaceAll("\\", "/");
+  const lowerPath = normalizedPath.toLowerCase();
+  const baseName = basename(lowerPath);
+  if (LOCKFILE_ACTIVITY_HINTS.has(baseName)) {
+    return LOCKFILE_ACTIVITY_HINTS.get(baseName);
+  }
+  if (MANIFEST_ACTIVITY_HINTS.has(baseName)) {
+    return MANIFEST_ACTIVITY_HINTS.get(baseName);
+  }
+  for (const { matcher, metadata } of SENSITIVE_CONFIG_ACTIVITY_HINTS) {
+    if (matcher(lowerPath, baseName)) {
+      return metadata;
+    }
+  }
+  if (
+    lowerPath.includes("/cache/") ||
+    lowerPath.includes("/.cache/") ||
+    lowerPath.includes("/caches/")
+  ) {
+    return {
+      classification: "cache",
+      label: "cache path",
+    };
+  }
+  if (
+    CERTIFICATE_FILE_EXTENSIONS.has(extname(baseName)) ||
+    baseName === "cert.pem"
+  ) {
+    return {
+      classification: "certificate",
+      label: "certificate file",
+      sensitive: true,
+    };
+  }
+  if (
+    KEY_FILE_EXTENSIONS.has(extname(baseName)) ||
+    baseName === "key.pem" ||
+    baseName.startsWith("id_")
+  ) {
+    return {
+      classification: "key",
+      label: "private key file",
+      sensitive: true,
+    };
+  }
+  const trimmedPath = normalizedPath.endsWith("/")
+    ? normalizedPath.slice(0, -1)
+    : normalizedPath;
+  const directoryName = basename(trimmedPath.toLowerCase());
+  if (DIRECTORY_DISCOVERY_NAMES.has(directoryName)) {
+    return {
+      classification: "directory",
+      label: "directory discovery path",
+    };
+  }
+  return undefined;
+}
+
+function classifyDiscoveryPattern(pattern) {
+  const patternValue = Array.isArray(pattern)
+    ? pattern.join(",")
+    : String(pattern);
+  const lowerPattern = patternValue.toLowerCase();
+  if (
+    lowerPattern.includes("package-lock.json") ||
+    lowerPattern.includes("pnpm-lock.yaml") ||
+    lowerPattern.includes("yarn.lock") ||
+    lowerPattern.includes("poetry.lock") ||
+    lowerPattern.includes("uv.lock") ||
+    lowerPattern.includes("cargo.lock") ||
+    lowerPattern.includes("gemfile.lock")
+  ) {
+    return {
+      discoveryType: "lockfile-discovery",
+      label: "lockfile discovery",
+    };
+  }
+  if (
+    lowerPattern.includes("package.json") ||
+    lowerPattern.includes("pom.xml") ||
+    lowerPattern.includes("pyproject.toml") ||
+    lowerPattern.includes("cargo.toml") ||
+    lowerPattern.includes("composer.json")
+  ) {
+    return {
+      discoveryType: "manifest-discovery",
+      label: "manifest discovery",
+    };
+  }
+  return {
+    discoveryType: "directory-enumeration",
+    label: "directory enumeration",
+  };
+}
+
+function recordDeduplicatedRead(traceMap, traceKey, activity, createReason) {
+  const existingTrace = traceMap.get(traceKey);
+  if (existingTrace) {
+    existingTrace.count += 1;
+    if (existingTrace.entry) {
+      existingTrace.entry.count = existingTrace.count;
+      existingTrace.entry.reason = createReason(existingTrace.count);
+    }
+    return existingTrace.entry;
+  }
+  const entry = emitActivity({
+    ...activity,
+    reason: createReason(1),
+  });
+  if (entry) {
+    entry.count = 1;
+  }
+  traceMap.set(traceKey, {
+    count: 1,
+    entry,
+  });
+  return entry;
+}
+
+export function isSensitiveEnvironmentVariableName(varName) {
+  return typeof varName === "string" && SENSITIVE_ENV_VAR_PATTERN.test(varName);
+}
+
+export function recordObservedActivity(kind, target, options = {}) {
+  if (!(isDryRun || DEBUG_MODE) || !kind || !target) {
+    return undefined;
+  }
+  const status = options.status || "completed";
+  const traceKey =
+    options.traceKey ||
+    `${kind}:${status}:${target}:${options.traceDetail || ""}`;
+  const metadata = options.metadata || {};
+  const reasonBuilder =
+    options.reasonBuilder ||
+    ((count) =>
+      options.reason
+        ? `${options.reason}${buildReadCountSuffix(count)}`
+        : `Recorded ${kind} activity for ${target}${buildReadCountSuffix(count)}.`);
+  return recordDeduplicatedRead(
+    dryRunReadTraceState.observations,
+    traceKey,
+    {
+      kind,
+      status,
+      target,
+      ...metadata,
+    },
+    reasonBuilder,
+  );
+}
+
+export function recordDecisionActivity(target, options = {}) {
+  return recordObservedActivity(options.kind || "decision", target, options);
+}
+
+export function recordDiscoveryActivity(target, options = {}) {
+  return recordObservedActivity(options.kind || "discover", target, options);
+}
+
+export function recordPolicyActivity(target, options = {}) {
+  return recordObservedActivity(options.kind || "policy", target, options);
+}
+
+function normalizeRecordedPathForComparison(
+  candidatePath,
+  basePath = undefined,
+) {
+  if (typeof candidatePath !== "string" || !candidatePath.length) {
+    return undefined;
+  }
+  let normalizedPath = candidatePath.replaceAll("\\", "/");
+  if (basePath && path.isAbsolute(candidatePath)) {
+    const resolvedBasePath = resolve(basePath);
+    const normalizedBasePath = resolvedBasePath.replaceAll("\\", "/");
+    const isWithinBasePath = (candidate) => {
+      const normalizedCandidate = candidate.replaceAll("\\", "/");
+      return (
+        normalizedCandidate === normalizedBasePath ||
+        normalizedCandidate.startsWith(`${normalizedBasePath}/`)
+      );
+    };
+
+    const resolvedCandidatePath = resolve(candidatePath);
+    if (isWithinBasePath(resolvedCandidatePath)) {
+      normalizedPath = relative(
+        resolvedBasePath,
+        resolvedCandidatePath,
+      ).replaceAll("\\", "/");
+    } else {
+      const rebasedCandidatePath = resolve(
+        resolvedBasePath,
+        candidatePath.replace(/^([A-Za-z]:)?[\\/]+/, ""),
+      );
+      if (isWithinBasePath(rebasedCandidatePath)) {
+        normalizedPath = relative(
+          resolvedBasePath,
+          rebasedCandidatePath,
+        ).replaceAll("\\", "/");
+      }
+    }
+  }
+  return normalizedPath;
+}
+
+export function recordSymlinkResolution(
+  sourcePath,
+  resolvedPath,
+  options = {},
+) {
+  const normalizedSourcePath = normalizeRecordedPathForComparison(
+    sourcePath,
+    options.basePath,
+  );
+  const normalizedResolvedPath = normalizeRecordedPathForComparison(
+    resolvedPath,
+    options.basePath,
+  );
+  const status = options.status || "completed";
+  if (
+    !normalizedSourcePath ||
+    (status === "completed" &&
+      (!normalizedResolvedPath ||
+        normalizedSourcePath === normalizedResolvedPath))
+  ) {
+    return undefined;
+  }
+  const metadata = {
+    capability: "symlink-resolution",
+    ...(normalizedResolvedPath ? { resolvedPath: normalizedResolvedPath } : {}),
+    ...(options.errorCode ? { errorCode: options.errorCode } : {}),
+    ...(options.metadata || {}),
+  };
+  return recordObservedActivity("symlink-resolution", normalizedSourcePath, {
+    metadata,
+    reason:
+      options.reason ||
+      (status === "failed"
+        ? `Failed to resolve symlink ${normalizedSourcePath}.`
+        : `Resolved symlink ${normalizedSourcePath} to ${normalizedResolvedPath}.`),
+    status,
+  });
+}
+
+function getArchiveSourceByteSize(sourcePath) {
+  if (!sourcePath || !safeExistsSync(sourcePath)) {
+    return undefined;
+  }
+  try {
+    const sourceStats = lstatSync(sourcePath);
+    return sourceStats.isFile() ? sourceStats.size : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function recordEnvironmentRead(varName, options = {}) {
+  // Read tracing intentionally mirrors the activity ledger's dry-run/debug behavior.
+  if (!(isDryRun || DEBUG_MODE) || !varName) {
+    return undefined;
+  }
+  const source = options.source || "process.env";
+  const sensitive =
+    options.sensitive ?? isSensitiveEnvironmentVariableName(varName);
+  const status = options.status || "completed";
+  const traceKey = `${source}:${varName}:${status}`;
+  const target = `${source}:${varName}`;
+  return recordDeduplicatedRead(
+    dryRunReadTraceState.environmentReads,
+    traceKey,
+    {
+      kind: "env",
+      redacted: sensitive,
+      secretCategory: sensitive ? "environment-variable" : undefined,
+      sensitive,
+      status,
+      target,
+    },
+    (count) =>
+      options.reason || buildEnvironmentReadReason(varName, count, sensitive),
+  );
+}
+
+export function recordSensitiveFileRead(filePath, options = {}) {
+  // Read tracing intentionally mirrors the activity ledger's dry-run/debug behavior.
+  if (!(isDryRun || DEBUG_MODE) || !filePath) {
+    return undefined;
+  }
+  const kind = options.kind || "read";
+  const pathMetadata = classifyActivityPath(filePath) || {};
+  const label = options.label || pathMetadata.label || "sensitive file";
+  const status = options.status || "completed";
+  const traceKey = `${kind}:${status}:${filePath}`;
+  return recordDeduplicatedRead(
+    dryRunReadTraceState.sensitiveFileReads,
+    traceKey,
+    {
+      classification: pathMetadata.classification,
+      ecosystem: pathMetadata.ecosystem,
+      kind,
+      redacted: pathMetadata.sensitive ?? true,
+      secretCategory:
+        pathMetadata.classification === "key"
+          ? "private-key"
+          : pathMetadata.classification === "certificate"
+            ? "certificate"
+            : "credential-file",
+      status,
+      target: filePath,
+    },
+    (count) =>
+      options.reason || buildSensitiveFileReadReason(filePath, count, label),
+  );
+}
+
+export function readEnvironmentVariable(varName, options = {}) {
+  recordEnvironmentRead(varName, options);
+  return process.env[varName];
+}
 
 export function setDryRunMode(enabled) {
   isDryRun = !!enabled;
@@ -161,10 +759,8 @@ export function recordActivity(activity) {
   const identifier = `ACT-${String(++activityCounter).padStart(4, "0")}`;
   const entry = {
     identifier,
+    ...currentActivityContext,
     timestamp: new Date().toISOString(),
-    projectType: currentActivityContext.projectType,
-    packageType: currentActivityContext.packageType,
-    sourcePath: currentActivityContext.sourcePath,
     ...activity,
   };
   activityLedger.push(entry);
@@ -172,6 +768,8 @@ export function recordActivity(activity) {
   return entry;
 }
 
+dryRunReadTraceState.recordActivity = recordActivity;
+
 export function getRecordedActivities() {
   return [...activityLedger];
 }
@@ -179,11 +777,21 @@ export function getRecordedActivities() {
 export function resetRecordedActivities() {
   activityLedger.length = 0;
   activityCounter = 0;
+  dryRunReadTraceState.environmentReads.clear();
+  dryRunReadTraceState.observations.clear();
+  dryRunReadTraceState.sensitiveFileReads.clear();
 }
 
-function recordFilesystemActivity(kind, target, status, reason = undefined) {
+function recordFilesystemActivity(
+  kind,
+  target,
+  status,
+  reason = undefined,
+  metadata = {},
+) {
   return recordActivity({
     kind,
+    ...metadata,
     reason,
     status,
     target,
@@ -218,13 +826,40 @@ function hasWritePermission(filePath) {
  * @Boolean True if the path exists. False otherwise
  */
 export function safeExistsSync(filePath) {
+  const pathMetadata = classifyActivityPath(filePath);
   if (!hasReadPermission(filePath)) {
     if (DEBUG_MODE) {
       console.log("cdxgen lacks read permission for a requested path.");
     }
+    if (pathMetadata) {
+      recordPolicyActivity(filePath, {
+        metadata: {
+          classification: pathMetadata.classification,
+          ecosystem: pathMetadata.ecosystem,
+          policyType: "fs.read",
+        },
+        reason: `Denied inspection of ${pathMetadata.label} ${filePath} due to missing fs.read permission.`,
+        status: "blocked",
+      });
+    }
     return false;
   }
-  return existsSync(filePath);
+  const exists = existsSync(filePath);
+  if (pathMetadata) {
+    const inspectionKind =
+      pathMetadata.classification === "directory" ? "discover" : "inspect";
+    recordObservedActivity(inspectionKind, filePath, {
+      metadata: {
+        classification: pathMetadata.classification,
+        ecosystem: pathMetadata.ecosystem,
+        exists,
+        redacted: pathMetadata.sensitive ?? false,
+      },
+      reasonBuilder: (count) =>
+        `${exists ? "Inspected" : "Checked for"} ${pathMetadata.label} ${filePath}${buildReadCountSuffix(count)}.`,
+    });
+  }
+  return exists;
 }
 
 export function safeWriteSync(filePath, data, options) {
@@ -249,9 +884,8 @@ export function safeWriteSync(filePath, data, options) {
     );
     return undefined;
   }
-  const result = writeFileSync(filePath, data, options);
+  writeFileSync(filePath, data, options);
   recordFilesystemActivity("write", filePath, "completed");
-  return result;
 }
 
 /**
@@ -283,24 +917,32 @@ export function safeMkdirSync(filePath, options) {
     );
     return undefined;
   }
-  const result = mkdirSync(filePath, options);
+  mkdirSync(filePath, options);
   recordFilesystemActivity("mkdir", filePath, "completed");
-  return result;
 }
 
 export function safeMkdtempSync(prefix, options = undefined) {
+  const resourceType =
+    typeof prefix === "string" && prefix.toLowerCase().includes("cache")
+      ? "cache"
+      : "temporary-workspace";
   if (isDryRun) {
     const tempPath = `${prefix}${randomUUID().replaceAll("-", "").slice(0, 6)}`;
     recordFilesystemActivity(
       "temp-dir",
       tempPath,
       "blocked",
-      "Dry run mode blocks temporary directory creation.",
+      `Dry run mode blocks temporary directory creation for ${resourceType}.`,
+      {
+        resourceType,
+      },
     );
     return tempPath;
   }
   const tempPath = mkdtempSync(prefix, options);
-  recordFilesystemActivity("temp-dir", tempPath, "completed");
+  recordFilesystemActivity("temp-dir", tempPath, "completed", undefined, {
+    resourceType,
+  });
   return tempPath;
 }
 
@@ -314,9 +956,8 @@ export function safeRmSync(filePath, options = undefined) {
     );
     return undefined;
   }
-  const result = rmSync(filePath, options);
+  rmSync(filePath, options);
   recordFilesystemActivity("cleanup", filePath, "completed");
-  return result;
 }
 
 export function safeUnlinkSync(filePath) {
@@ -329,9 +970,8 @@ export function safeUnlinkSync(filePath) {
     );
     return undefined;
   }
-  const result = unlinkSync(filePath);
+  unlinkSync(filePath);
   recordFilesystemActivity("cleanup", filePath, "completed");
-  return result;
 }
 
 export function safeCopyFileSync(src, dest, mode = undefined) {
@@ -357,32 +997,69 @@ export async function safeExtractArchive(
   targetPath,
   extractor,
   kind = "unzip",
+  options = undefined,
 ) {
+  const traceArchiveStats = isDryRun || DEBUG_MODE;
+  const sourceBytes = traceArchiveStats
+    ? getArchiveSourceByteSize(sourcePath)
+    : undefined;
   if (isDryRun) {
     recordActivity({
+      archiveKind: kind,
+      capability: "archive-extraction",
       kind,
-      reason: "Dry run mode blocks archive extraction and decompression.",
+      ...(options?.metadata || {}),
+      ...(sourceBytes !== undefined ? { sourceBytes } : {}),
+      reason:
+        options?.blockedReason ||
+        `Dry run mode blocks ${kind} extraction from ${sourcePath} into ${targetPath}.`,
       status: "blocked",
       target: `${sourcePath} -> ${targetPath}`,
     });
     return false;
   }
-  await extractor();
-  recordActivity({
-    kind,
-    status: "completed",
-    target: `${sourcePath} -> ${targetPath}`,
-  });
-  return true;
+  try {
+    await extractor();
+    recordActivity({
+      archiveKind: kind,
+      capability: "archive-extraction",
+      kind,
+      ...(options?.metadata || {}),
+      ...(sourceBytes !== undefined ? { sourceBytes } : {}),
+      status: "completed",
+      target: `${sourcePath} -> ${targetPath}`,
+    });
+    return true;
+  } catch (error) {
+    recordActivity({
+      archiveKind: kind,
+      capability: "archive-extraction",
+      kind,
+      ...(options?.metadata || {}),
+      ...(sourceBytes !== undefined ? { sourceBytes } : {}),
+      ...(error?.code ? { errorCode: error.code } : {}),
+      reason:
+        options?.failureReason ||
+        `Failed ${kind} extraction from ${sourcePath} into ${targetPath}: ${error.message}`,
+      status: "failed",
+      target: `${sourcePath} -> ${targetPath}`,
+    });
+    throw error;
+  }
 }
 
 export const commandsExecuted = new Set();
-const ALLOW_COMMANDS = (process.env.CDXGEN_ALLOWED_COMMANDS || "").split(",");
-function isAllowedCommand(command) {
-  if (!process.env.CDXGEN_ALLOWED_COMMANDS) {
+function isAllowedCommand(
+  command,
+  allowedCommandsEnv = readEnvironmentVariable("CDXGEN_ALLOWED_COMMANDS"),
+) {
+  if (!allowedCommandsEnv) {
     return true;
   }
-  return ALLOW_COMMANDS.includes(command.trim());
+  return allowedCommandsEnv
+    .split(",")
+    .map((entry) => entry.trim())
+    .includes(command.trim());
 }
 
 const ALLOWED_WRAPPERS = new Set(["gradlew", "mvnw"]);
@@ -429,6 +1106,71 @@ function isWindowsShellHijackRisk(command, options) {
   return false;
 }
 
+const VERSION_PROBE_ARGS = new Set(["--version", "-version", "version"]);
+
+function detectProbeType(command, args = []) {
+  const normalizedCommand = basename(String(command || "")).toLowerCase();
+  const normalizedArgs = (args || []).map((arg) => String(arg).toLowerCase());
+  if (
+    normalizedArgs.some((arg) => VERSION_PROBE_ARGS.has(arg)) ||
+    (normalizedArgs.length === 1 && normalizedArgs[0] === "-v")
+  ) {
+    return "version-check";
+  }
+  if (normalizedCommand === "which" || normalizedArgs.includes("--help")) {
+    return "capability-probe";
+  }
+  if (
+    normalizedCommand.startsWith("python") &&
+    normalizedArgs.includes("-c") &&
+    normalizedArgs.some((arg) => arg.includes("import"))
+  ) {
+    return "runtime-probe";
+  }
+  return undefined;
+}
+
+function buildCommandActivityDescriptor(command, args, options) {
+  const target = `${command}${args?.length ? ` ${args.join(" ")}` : ""}`;
+  const cdxgenActivity = options?.cdxgenActivity || {};
+  const probeType = cdxgenActivity.probeType || detectProbeType(command, args);
+  const metadata = {
+    ...(cdxgenActivity.metadata || {}),
+  };
+  if (probeType) {
+    metadata.capability = metadata.capability || "tool-runtime-probe";
+    metadata.probeType = probeType;
+  }
+  if (cdxgenActivity.gitOperation) {
+    metadata.gitOperation = cdxgenActivity.gitOperation;
+  }
+  return {
+    blockedReason:
+      cdxgenActivity.blockedReason ||
+      (probeType
+        ? `Dry run mode blocks ${probeType.replaceAll("-", " ")} command execution.`
+        : "Dry run mode blocks child process execution."),
+    kind: cdxgenActivity.kind || "execute",
+    metadata,
+    target: cdxgenActivity.target || target,
+  };
+}
+
+function getOutputByteSize(value, encoding = "utf-8") {
+  if (value === undefined || value === null) {
+    return 0;
+  }
+  if (Buffer.isBuffer(value)) {
+    return value.length;
+  }
+  if (ArrayBuffer.isView(value)) {
+    return value.byteLength;
+  }
+  const safeEncoding =
+    typeof encoding === "string" && encoding !== "buffer" ? encoding : "utf8";
+  return Buffer.byteLength(String(value), safeEncoding);
+}
+
 /**
  * Safe wrapper around spawnSync that enforces permission checks, injects default
  * options (maxBuffer, encoding, timeout), warns about unsafe Python and pip/uv
@@ -440,17 +1182,49 @@ function isWindowsShellHijackRisk(command, options) {
  * @returns {Object} spawnSync result object with status, stdout, stderr, and error fields
  */
 export function safeSpawnSync(command, args, options) {
+  const activityDescriptor = buildCommandActivityDescriptor(
+    command,
+    args,
+    options,
+  );
+  const allowedCommandsEnv = readEnvironmentVariable("CDXGEN_ALLOWED_COMMANDS");
+  const commandAllowed = isAllowedCommand(command, allowedCommandsEnv);
+  if (allowedCommandsEnv) {
+    recordPolicyActivity(command, {
+      metadata: {
+        allowed: commandAllowed,
+        allowlist: allowedCommandsEnv,
+        policyType: "command-allowlist",
+      },
+      reason: `${commandAllowed ? "Allowed" : "Blocked"} command ${command} against CDXGEN_ALLOWED_COMMANDS.`,
+      status: commandAllowed ? "completed" : "blocked",
+      traceDetail: "allowlist",
+    });
+  }
+  if (isSecureMode && process.permission) {
+    const hasChildPermission = process.permission.has("child");
+    recordPolicyActivity(command, {
+      metadata: {
+        allowed: hasChildPermission,
+        policyType: "child-process",
+      },
+      reason: `${hasChildPermission ? "Confirmed" : "Denied"} child-process permission for ${command}.`,
+      status: hasChildPermission ? "completed" : "blocked",
+      traceDetail: "child-permission",
+    });
+  }
   if (isDryRun) {
     const error = createDryRunError(
       "execute",
       command,
-      "Dry run mode blocks child process execution.",
+      activityDescriptor.blockedReason,
     );
     recordActivity({
-      kind: "execute",
+      kind: activityDescriptor.kind,
+      ...activityDescriptor.metadata,
       reason: error.message,
       status: "blocked",
-      target: `${command}${args?.length ? ` ${args.join(" ")}` : ""}`,
+      target: activityDescriptor.target,
     });
     return {
       status: 1,
@@ -461,16 +1235,17 @@ export function safeSpawnSync(command, args, options) {
   }
   if (
     (isSecureMode && process.permission && !process.permission.has("child")) ||
-    !isAllowedCommand(command)
+    !commandAllowed
   ) {
     if (DEBUG_MODE) {
       console.log(`cdxgen lacks execute permission for ${command}`);
     }
     recordActivity({
-      kind: "execute",
+      kind: activityDescriptor.kind,
+      ...activityDescriptor.metadata,
       reason: "cdxgen lacks execute permission for this command.",
       status: "blocked",
-      target: `${command}${args?.length ? ` ${args.join(" ")}` : ""}`,
+      target: activityDescriptor.target,
     });
     return {
       status: 1,
@@ -484,10 +1259,11 @@ export function safeSpawnSync(command, args, options) {
       const blockedReason = `${command} matches local file in cwd (Windows shell hijack risk)`;
       console.warn(`\x1b[1;31mSecurity Alert: ${blockedReason}\x1b[0m`);
       recordActivity({
-        kind: "execute",
+        kind: activityDescriptor.kind,
+        ...activityDescriptor.metadata,
         reason: blockedReason,
         status: "blocked",
-        target: `${command}${args?.length ? ` ${args.join(" ")}` : ""}`,
+        target: activityDescriptor.target,
       });
       return {
         status: 1,
@@ -506,6 +1282,11 @@ export function safeSpawnSync(command, args, options) {
   }
   if (!options) {
     options = {};
+  } else if (options.cdxgenActivity) {
+    options = {
+      ...options,
+    };
+    delete options.cdxgenActivity;
   }
   // Inject maxBuffer
   if (!options.maxBuffer) {
@@ -605,10 +1386,13 @@ export function safeSpawnSync(command, args, options) {
   }
   const result = spawnSync(command, args, options);
   recordActivity({
-    kind: "execute",
+    kind: activityDescriptor.kind,
+    ...activityDescriptor.metadata,
+    stderrBytes: getOutputByteSize(result.stderr, options.encoding),
     reason: result.error?.message,
     status: result.status === 0 && !result.error ? "completed" : "failed",
-    target: `${command}${args?.length ? ` ${args.join(" ")}` : ""}`,
+    stdoutBytes: getOutputByteSize(result.stdout, options.encoding),
+    target: activityDescriptor.target,
   });
   return result;
 }
@@ -985,6 +1769,7 @@ export const PROJECT_TYPE_ALIASES = {
   c: ["c", "cpp", "c++", "conan", "collider"],
   clojure: ["clojure", "edn", "clj", "leiningen"],
   github: ["github", "actions"],
+  hbom: ["hbom", "hardware"],
   os: ["os", "osquery", "windows", "linux", "mac", "macos", "darwin"],
   jenkins: ["jenkins", "hpi"],
   helm: ["helm", "charts"],
@@ -1020,12 +1805,14 @@ export const PROJECT_TYPE_ALIASES = {
   scala: ["scala", "scala3", "sbt", "mill"],
   nix: ["nix", "nixos", "flake"],
   caxa: ["caxa"],
+  asar: ["asar", "electron", "electron-asar"],
   "vscode-extension": [
     "vscode-extension",
     "vsix",
     "vscode",
     "openvsx",
     "vscode-extensions",
+    "ide-extension",
     "ide-extensions",
   ],
   "chrome-extension": [
@@ -1155,6 +1942,90 @@ export function hasAnyProjectType(projectTypes, options, defaultStatus = true) {
   return shouldInclude;
 }
 
+/**
+ * Determine whether the predictive dependency audit should run for the current
+ * CLI invocation.
+ *
+ * OBOM-focused runs (`obom` or explicit `-t os` / OS aliases only) should keep
+ * the direct BOM audit findings but skip the predictive dependency audit.
+ *
+ * @param {object} options CLI options
+ * @param {string} [commandPath] Invoked command path or name
+ * @returns {boolean} True when predictive dependency audit should run
+ */
+export function shouldRunPredictiveBomAudit(options, commandPath) {
+  const normalizedCommandPath = `${commandPath || ""}`.toLowerCase();
+  if (normalizedCommandPath.includes("obom")) {
+    return false;
+  }
+  if (normalizedCommandPath.includes("hbom")) {
+    return false;
+  }
+  const projectTypes = Array.isArray(options?.projectType)
+    ? options.projectType
+    : typeof options?.projectType === "string"
+      ? options.projectType.split(",")
+      : [];
+  const normalizedProjectTypes = projectTypes
+    .map((projectType) => `${projectType || ""}`.trim().toLowerCase())
+    .filter(Boolean);
+  if (!normalizedProjectTypes.length) {
+    return true;
+  }
+  const hbomProjectTypes = new Set(["hbom", "hardware"]);
+  if (
+    normalizedProjectTypes.every((projectType) =>
+      hbomProjectTypes.has(projectType),
+    )
+  ) {
+    return false;
+  }
+  const osProjectTypes = new Set(["os", ...(PROJECT_TYPE_ALIASES.os || [])]);
+  return !normalizedProjectTypes.every((projectType) =>
+    osProjectTypes.has(projectType),
+  );
+}
+
+/**
+ * Determine the default BOM audit categories for the current CLI invocation.
+ *
+ * OBOM-focused runs should default to the runtime-specific rule pack unless the
+ * user explicitly requests other categories.
+ *
+ * @param {object} options CLI options
+ * @param {string} [commandPath] Invoked command path or name
+ * @returns {string | undefined} Default category string, if any
+ */
+export function getDefaultBomAuditCategories(options, commandPath) {
+  const normalizedCommandPath = `${commandPath || ""}`.toLowerCase();
+  const defaultHbomCategories = options?.includeRuntime
+    ? `${DEFAULT_HBOM_AUDIT_CATEGORIES},host-topology`
+    : DEFAULT_HBOM_AUDIT_CATEGORIES;
+  if (normalizedCommandPath.includes("hbom")) {
+    return defaultHbomCategories;
+  }
+  const projectTypes = Array.isArray(options?.projectType)
+    ? options.projectType
+    : typeof options?.projectType === "string"
+      ? options.projectType.split(",")
+      : [];
+  const normalizedProjectTypes = projectTypes
+    .map((projectType) => `${projectType || ""}`.trim().toLowerCase())
+    .filter(Boolean);
+  if (
+    normalizedProjectTypes.length &&
+    normalizedProjectTypes.every((projectType) =>
+      ["hbom", "hardware"].includes(projectType),
+    )
+  ) {
+    return defaultHbomCategories;
+  }
+  if (!shouldRunPredictiveBomAudit(options, commandPath)) {
+    return "obom-runtime";
+  }
+  return undefined;
+}
+
 /**
  * Convenient method to check if the given package manager is allowed.
  *
@@ -1196,23 +2067,76 @@ function isCacheDisabled() {
 const cache = isCacheDisabled() ? undefined : gotHttpCache;
 export const remoteHostsAccessed = new Set();
 
-function isAllowedHost(hostname) {
-  if (!process.env.CDXGEN_ALLOWED_HOSTS) {
+export function isAllowedHttpHost(
+  hostname,
+  allowedHostsEnv = readEnvironmentVariable("CDXGEN_ALLOWED_HOSTS"),
+) {
+  if (!allowedHostsEnv) {
     return true;
   }
-  const allow_hosts = (process.env.CDXGEN_ALLOWED_HOSTS || "").split(",");
+  if (!hostname || hasDangerousUnicode(hostname)) {
+    return false;
+  }
+  const normalizedHostname = hostname.toLowerCase();
+  const allow_hosts = allowedHostsEnv
+    .split(",")
+    .map((host) => host.trim().toLowerCase())
+    .filter(Boolean);
   for (const ahost of allow_hosts) {
-    if (!ahost.length) {
-      continue;
-    }
-    if (hostname === ahost) {
+    if (normalizedHostname === ahost) {
       return true;
     }
     // wildcard support
-    if (ahost.startsWith("*.") && hostname.endsWith(ahost.replace("*", ""))) {
+    if (
+      ahost.startsWith("*.") &&
+      normalizedHostname.length > ahost.length - 1 &&
+      normalizedHostname.endsWith(`.${ahost.slice(2)}`)
+    ) {
       return true;
     }
   }
+  return false;
+}
+
+function hostnameMatches(hostname, candidateHost) {
+  return hostname === candidateHost || hostname.endsWith(`.${candidateHost}`);
+}
+
+function inferNetworkIntent(requestUrl) {
+  const hostname = requestUrl?.hostname?.toLowerCase() || "";
+  const pathname = requestUrl?.pathname?.toLowerCase() || "";
+  if (pathname.includes("/api/v1/bom")) {
+    return "sbom-submit";
+  }
+  if (pathname.includes("/manifests/")) {
+    return "oci-manifest-access";
+  }
+  if (pathname.includes("/blobs/")) {
+    return "oci-layer-access";
+  }
+  if (
+    pathname.includes("license") ||
+    hostnameMatches(hostname, "spdx.org") ||
+    hostnameMatches(hostname, "opensource.org")
+  ) {
+    return "license-fetch";
+  }
+  if (
+    hostnameMatches(hostname, "registry.npmjs.org") ||
+    hostnameMatches(hostname, "pypi.org") ||
+    hostnameMatches(hostname, "rubygems.org") ||
+    hostnameMatches(hostname, "repo.maven.apache.org") ||
+    hostnameMatches(hostname, "repo1.maven.org") ||
+    hostnameMatches(hostname, "crates.io") ||
+    hostnameMatches(hostname, "pub.dev") ||
+    hostnameMatches(hostname, "nuget.org")
+  ) {
+    return "registry-lookup";
+  }
+  if (hostnameMatches(hostname, "github.com") && pathname.endsWith(".git")) {
+    return "git-fetch";
+  }
+  return "metadata-fetch";
 }
 
 // Custom user-agent for cdxgen
@@ -1228,18 +2152,40 @@ export const cdxgenAgent = got.extend({
   hooks: {
     beforeRequest: [
       (options) => {
+        const networkIntent =
+          options.context?.activityIntent || inferNetworkIntent(options.url);
+        const allowedHostsEnv = readEnvironmentVariable("CDXGEN_ALLOWED_HOSTS");
+        const hostAllowed = isAllowedHttpHost(
+          options.url.hostname,
+          allowedHostsEnv,
+        );
         options.context = {
           ...options.context,
+          activityIntent: networkIntent,
           activityTarget: options.url.toString(),
         };
+        if (allowedHostsEnv) {
+          recordPolicyActivity(options.url.hostname, {
+            metadata: {
+              allowed: hostAllowed,
+              allowlist: allowedHostsEnv,
+              networkIntent,
+              policyType: "host-allowlist",
+            },
+            reason: `${hostAllowed ? "Allowed" : "Blocked"} host ${options.url.hostname} against CDXGEN_ALLOWED_HOSTS.`,
+            status: hostAllowed ? "completed" : "blocked",
+            traceDetail: "host-allowlist",
+          });
+        }
         if (isDryRun) {
           const error = createDryRunError(
             "network",
             options.url.toString(),
-            "Dry run mode blocks outbound network access.",
+            `Dry run mode blocks outbound network access (${networkIntent}).`,
           );
           recordActivity({
             kind: "network",
+            networkIntent,
             reason: error.message,
             status: "blocked",
             target: options.url.toString(),
@@ -1247,12 +2193,13 @@ export const cdxgenAgent = got.extend({
           options.context.activityBlocked = true;
           throw error;
         }
-        if (!isAllowedHost(options.url.hostname)) {
+        if (!hostAllowed) {
           console.log(
             `Access to the remote host '${options.url.hostname}' is not permitted.`,
           );
           recordActivity({
             kind: "network",
+            networkIntent,
             reason: "The remote host is not permitted.",
             status: "blocked",
             target: options.url.toString(),
@@ -1267,6 +2214,7 @@ export const cdxgenAgent = got.extend({
           );
           recordActivity({
             kind: "network",
+            networkIntent,
             reason: `The '${options.url.protocol}' protocol is not permitted in secure mode.`,
             status: "blocked",
             target: options.url.toString(),
@@ -1293,6 +2241,7 @@ export const cdxgenAgent = got.extend({
           response.url;
         recordActivity({
           kind: "network",
+          networkIntent: response.request.options.context?.activityIntent,
           status: "completed",
           target: activityTarget,
         });
@@ -1306,6 +2255,7 @@ export const cdxgenAgent = got.extend({
         }
         recordActivity({
           kind: "network",
+          networkIntent: error.options?.context?.activityIntent,
           reason: error.message,
           status: "failed",
           target:
@@ -1389,6 +2339,10 @@ export function getAllFilesWithIgnore(
   includeDot,
   ignoreList,
 ) {
+  const patternValue = Array.isArray(pattern)
+    ? pattern.join(",")
+    : String(pattern);
+  const discoveryMetadata = classifyDiscoveryPattern(patternValue);
   try {
     const files = globSync(pattern, {
       cwd: dirPath,
@@ -1399,6 +2353,16 @@ export function getAllFilesWithIgnore(
       follow: false,
       ignore: ignoreList,
     });
+    recordDiscoveryActivity(`${dirPath} :: ${patternValue}`, {
+      metadata: {
+        discoveryType: discoveryMetadata.discoveryType,
+        matchedCount: files.length,
+        pattern: patternValue,
+      },
+      traceDetail: `matched:${files.length}`,
+      reasonBuilder: (count) =>
+        `Scanned ${dirPath} with glob '${patternValue}' for ${discoveryMetadata.label}; matched ${files.length} path(s)${buildReadCountSuffix(count)}.`,
+    });
     if (files.length > 1) {
       thoughtLog(
         `Found ${files.length} files for the pattern '${pattern}' at '${dirPath}'.`,
@@ -1406,6 +2370,14 @@ export function getAllFilesWithIgnore(
     }
     return files;
   } catch (err) {
+    recordDiscoveryActivity(`${dirPath} :: ${patternValue}`, {
+      metadata: {
+        discoveryType: discoveryMetadata.discoveryType,
+        pattern: patternValue,
+      },
+      reason: `File discovery failed for glob '${patternValue}' under ${dirPath}: ${err.message}`,
+      status: "failed",
+    });
     if (DEBUG_MODE) {
       console.error(err);
     }
@@ -7089,7 +8061,7 @@ function addComponentProperty(component, name, value) {
 }
 
 const PYTHON_DIRECT_REFERENCE_PATTERN =
-  /^([A-Za-z0-9_.-]+)(?:\[[^\]]+\])?\s*@\s*(\S+)$/;
+  /^([A-Za-z0-9_.-]+)(?:\[[^\]]+])?\s*@\s*(\S+)$/;
 
 function isWindowsAbsolutePath(value) {
   return /^[a-zA-Z]:[\\/]/.test(value) || value.startsWith("\\\\");
@@ -7180,7 +8152,7 @@ function extractPythonDependencyKey(value) {
   }
   const packageMatch =
     typeof value === "string"
-      ? value.trim().match(/^([A-Za-z0-9_.-]+)(?:\[[^\]]+\])?/)
+      ? value.trim().match(/^([A-Za-z0-9_.-]+)(?:\[[^\]]+])?/)
       : undefined;
   return normalizePythonDependencyKey(packageMatch?.[1]);
 }
@@ -8463,7 +9435,7 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
 
     // Handle extras (e.g., package[extra1,extra2])
     let extras = null;
-    const extrasMatch = l.match(/^([a-zA-Z0-9_\-\.]+)(\[([^\]]+)\])?(.*)$/);
+    const extrasMatch = l.match(/^([a-zA-Z0-9_\-.]+)(\[([^\]]+)])?(.*)$/);
     if (extrasMatch) {
       const [, packageName, , extrasStr, versionSpecifiers] = extrasMatch;
       const name = packageName;
@@ -8532,7 +9504,7 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
       }
       pkgList.push(apkg);
     } else {
-      const match = l.match(/^([a-zA-Z0-9_\-\.]+)(.*)$/);
+      const match = l.match(/^([a-zA-Z0-9_\-.]+)(.*)$/);
       if (!match) {
         continue;
       }
@@ -13599,7 +14571,7 @@ export function parseFlakeNix(flakeNixFile) {
     const flakeContent = readFileSync(flakeNixFile, "utf-8");
 
     // Extract inputs from flake.nix using regex
-    const inputsRegex = /inputs\s*=\s*\{[^}]*\}/g;
+    const inputsRegex = /inputs\s*=\s*\{[^}]*}/g;
     let match;
     while ((match = inputsRegex.exec(flakeContent)) !== null) {
       const inputBlock = match[0];
@@ -13607,7 +14579,7 @@ export function parseFlakeNix(flakeNixFile) {
       // Match different input patterns including nested inputs
       const inputPatterns = [
         /([a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*)\.url\s*=\s*"([^"]+)"/g,
-        /([a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*)\s*=\s*\{\s*url\s*=\s*"([^"]+)"[^}]*\}/gs,
+        /([a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*)\s*=\s*\{\s*url\s*=\s*"([^"]+)"[^}]*}/gs,
       ];
 
       const addedPackages = new Set();
@@ -15549,16 +16521,22 @@ export function convertOSQueryResults(
       if (name) {
         name = sanitizeOsQueryIdentity(name);
         group = sanitizeOsQueryIdentity(group);
-        const purl = createOsQueryPurl(
-          queryObj.purlType,
-          group,
-          name,
-          version,
-          qualifiers,
-          subpath,
-        );
+        const isCryptoAsset = queryObj.componentType === "cryptographic-asset";
+        const purl = shouldCreateOsQueryPurl(queryObj.componentType)
+          ? createOsQueryPurl(
+              queryObj.purlType,
+              group,
+              name,
+              version,
+              qualifiers,
+              subpath,
+            )
+          : undefined;
         const props = [{ name: "cdx:osquery:category", value: queryCategory }];
         props.push(...createLolbasProperties(queryCategory, res));
+        if (platform() === "linux") {
+          props.push(...createGtfoBinsPropertiesFromRow(queryCategory, res));
+        }
         let providesList;
         if (enhance) {
           switch (queryObj.purlType) {
@@ -15584,25 +16562,39 @@ export function convertOSQueryResults(
         if (providesList) {
           props.push({ name: "PkgProvides", value: providesList.join(", ") });
         }
+        const cryptoProperties = isCryptoAsset
+          ? createOsQueryCryptoProperties(queryCategory, res, version)
+          : undefined;
+        const hashes = createOsQueryComponentHashes(res);
         const apkg = {
           name,
           group,
           version: version || "",
           description,
           publisher,
-          "bom-ref": decodeURIComponent(purl),
+          "bom-ref": createOsQueryBomRef(
+            queryCategory,
+            queryObj.componentType,
+            res,
+            name,
+            version,
+            purl,
+          ),
           purl,
           scope,
           type: queryObj.componentType,
         };
+        if (hashes?.length) {
+          apkg.hashes = hashes;
+        }
+        if (cryptoProperties) {
+          apkg.cryptoProperties = cryptoProperties;
+        }
         for (const k of Object.keys(res).filter((p) => {
           if (["version", "description", "publisher"].includes(p)) {
             return false;
           }
-          if (queryObj.purlType !== "chrome-extension" && p === "name") {
-            return false;
-          }
-          return true;
+          return !(queryObj.purlType !== "chrome-extension" && p === "name");
         })) {
           if (res[k] && res[k] !== "null") {
             props.push({
@@ -15619,6 +16611,182 @@ export function convertOSQueryResults(
   return pkgList;
 }
 
+function createOsQueryComponentHashes(res) {
+  const hashes = [];
+  if (res?.md5) {
+    hashes.push({ alg: "MD5", content: res.md5 });
+  }
+  if (res?.sha1) {
+    hashes.push({ alg: "SHA-1", content: res.sha1 });
+  }
+  if (res?.sha256) {
+    hashes.push({ alg: "SHA-256", content: res.sha256 });
+  }
+  return hashes.length ? hashes : undefined;
+}
+
+function createOsQueryBomRef(
+  queryCategory,
+  componentType,
+  res,
+  name,
+  version,
+  purl,
+) {
+  if (purl) {
+    return decodeURIComponent(purl);
+  }
+  if (componentType === "cryptographic-asset") {
+    return createOsQueryCryptoBomRef(queryCategory, res, name, version);
+  }
+  const identityEntry = [
+    ["path", res?.path],
+    ["key_file", res?.key_file],
+    ["history_file", res?.history_file],
+    ["fragment_path", res?.fragment_path],
+    ["source_path", res?.source_path],
+    ["source", res?.source],
+    ["key", res?.key],
+    ["label", res?.label],
+    ["identifier", res?.identifier],
+    ["uuid", res?.uuid],
+    ["device_id", res?.device_id],
+    ["sid", res?.sid],
+    ["logon_id", res?.logon_id],
+    ["pid", res?.pid],
+    ["uid", res?.uid],
+  ].find(
+    ([, value]) =>
+      value !== undefined && value !== null && String(value).length,
+  );
+  return createOsQueryFallbackBomRef(
+    queryCategory,
+    componentType,
+    name,
+    version,
+    identityEntry?.[0],
+    identityEntry?.[1],
+  );
+}
+
+function createOsQueryCryptoBomRef(queryCategory, res, name, version) {
+  const encodedName = encodeURIComponent(
+    name || queryCategory || "crypto-asset",
+  );
+  switch (queryCategory) {
+    case "trusted_gpg_keys":
+      return `crypto/related-crypto-material/public-key/${encodedName}@sha256:${res?.sha256 || version || "unknown"}`;
+    case "kernel_keys":
+      return `crypto/related-crypto-material/key/${encodedName}@${version || res?.serial_number || "unknown"}`;
+    case "certificates":
+    case "secureboot_certificates":
+      return `crypto/certificate/${encodedName}@${res?.sha256 ? `sha256:${res.sha256}` : version || "unknown"}`;
+    default:
+      return `crypto/related-crypto-material/unknown/${encodedName}@${version || "unknown"}`;
+  }
+}
+
+function createOsQueryCryptoProperties(queryCategory, res, version) {
+  switch (queryCategory) {
+    case "trusted_gpg_keys":
+      return {
+        assetType: "related-crypto-material",
+        relatedCryptoMaterialProperties: {
+          type: "public-key",
+          id: res?.sha256 || version || res?.path || res?.name || "unknown",
+          state: "active",
+        },
+      };
+    case "kernel_keys":
+      return {
+        assetType: "related-crypto-material",
+        relatedCryptoMaterialProperties: {
+          type: "key",
+          id:
+            res?.serial_number ||
+            version ||
+            res?.description ||
+            res?.name ||
+            "unknown",
+          state: res?.timeout === "expd" ? "deactivated" : "active",
+        },
+      };
+    case "certificates":
+    case "secureboot_certificates": {
+      const certificateFileExtension = extname(res?.path || "")
+        .replace(/^\./, "")
+        .toLowerCase();
+      const certificateFormat =
+        queryCategory === "secureboot_certificates"
+          ? "X.509"
+          : deriveCertificateFormat(certificateFileExtension);
+      return {
+        assetType: "certificate",
+        algorithmProperties: {
+          executionEnvironment: "unknown",
+          implementationPlatform: "unknown",
+        },
+        certificateProperties: {
+          serialNumber: res?.serial || undefined,
+          subjectName: res?.subject || res?.common_name || undefined,
+          issuerName: res?.issuer || undefined,
+          notValidBefore: normalizeCertificateDate(res?.not_valid_before),
+          notValidAfter: normalizeCertificateDate(res?.not_valid_after),
+          certificateFormat,
+          certificateFileExtension: certificateFileExtension || undefined,
+          fingerprint: res?.sha1
+            ? { alg: "SHA-1", content: res.sha1 }
+            : undefined,
+        },
+      };
+    }
+    default:
+      return {
+        assetType: "related-crypto-material",
+        relatedCryptoMaterialProperties: {
+          type: "unknown",
+          id: version || res?.path || res?.name || "unknown",
+        },
+      };
+  }
+}
+
+function deriveCertificateFormat(certificateFileExtension) {
+  switch ((certificateFileExtension || "").toLowerCase()) {
+    case "pem":
+      return "PEM";
+    case "der":
+      return "DER";
+    case "cer":
+    case "crt":
+      return "X.509";
+    default:
+      return undefined;
+  }
+}
+
+function normalizeCertificateDate(value) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  const stringValue = `${value}`.trim();
+  if (!stringValue) {
+    return undefined;
+  }
+  const numericValue = Number(stringValue);
+  if (Number.isFinite(numericValue)) {
+    const millis = stringValue.length > 10 ? numericValue : numericValue * 1000;
+    const parsedDate = new Date(millis);
+    return Number.isNaN(parsedDate.getTime())
+      ? undefined
+      : parsedDate.toISOString();
+  }
+  const parsedDate = new Date(stringValue);
+  return Number.isNaN(parsedDate.getTime())
+    ? undefined
+    : parsedDate.toISOString();
+}
+
 /**
  * Create a PackageURL object from a repository URL string, package type, and version.
  *
@@ -17085,6 +18253,14 @@ export function getGradleCommand(srcPath, rootPath) {
       // continue regardless of error
     }
     gradleCmd = resolve(join(srcPath, findGradleFile));
+    recordDecisionActivity(gradleCmd, {
+      metadata: {
+        decisionType: "path-resolution",
+        selectedSource: "project-wrapper",
+        tool: "gradle",
+      },
+      reason: `Selected project-local Gradle wrapper ${gradleCmd}.`,
+    });
   } else if (rootPath && safeExistsSync(join(rootPath, findGradleFile))) {
     // Check if the root directory has a wrapper script
     try {
@@ -17093,10 +18269,43 @@ export function getGradleCommand(srcPath, rootPath) {
       // continue regardless of error
     }
     gradleCmd = resolve(join(rootPath, findGradleFile));
+    recordDecisionActivity(gradleCmd, {
+      metadata: {
+        decisionType: "path-resolution",
+        selectedSource: "root-wrapper",
+        tool: "gradle",
+      },
+      reason: `Selected root-level Gradle wrapper ${gradleCmd}.`,
+    });
   } else if (process.env.GRADLE_CMD) {
     gradleCmd = process.env.GRADLE_CMD;
+    recordDecisionActivity(gradleCmd, {
+      metadata: {
+        decisionType: "path-resolution",
+        selectedSource: "GRADLE_CMD",
+        tool: "gradle",
+      },
+      reason: `Selected Gradle command from GRADLE_CMD (${gradleCmd}).`,
+    });
   } else if (process.env.GRADLE_HOME) {
     gradleCmd = join(process.env.GRADLE_HOME, "bin", "gradle");
+    recordDecisionActivity(gradleCmd, {
+      metadata: {
+        decisionType: "path-resolution",
+        selectedSource: "GRADLE_HOME",
+        tool: "gradle",
+      },
+      reason: `Selected Gradle command from GRADLE_HOME (${gradleCmd}).`,
+    });
+  } else {
+    recordDecisionActivity(gradleCmd, {
+      metadata: {
+        decisionType: "path-resolution",
+        selectedSource: "PATH",
+        tool: "gradle",
+      },
+      reason: "Falling back to Gradle from PATH.",
+    });
   }
   return gradleCmd;
 }
@@ -17974,6 +19183,14 @@ export function getMavenCommand(srcPath, rootPath) {
     }
     mavenWrapperCmd = resolve(join(srcPath, findMavenFile));
     isWrapperFound = true;
+    recordDecisionActivity(mavenWrapperCmd, {
+      metadata: {
+        decisionType: "path-resolution",
+        selectedSource: "project-wrapper-candidate",
+        tool: "maven",
+      },
+      reason: `Found Maven wrapper candidate ${mavenWrapperCmd}.`,
+    });
   } else if (rootPath && safeExistsSync(join(rootPath, findMavenFile))) {
     // Check if the root directory has a wrapper script
     try {
@@ -17983,6 +19200,14 @@ export function getMavenCommand(srcPath, rootPath) {
     }
     mavenWrapperCmd = resolve(join(rootPath, findMavenFile));
     isWrapperFound = true;
+    recordDecisionActivity(mavenWrapperCmd, {
+      metadata: {
+        decisionType: "path-resolution",
+        selectedSource: "root-wrapper-candidate",
+        tool: "maven",
+      },
+      reason: `Found root-level Maven wrapper candidate ${mavenWrapperCmd}.`,
+    });
   }
   if (isWrapperFound) {
     if (DEBUG_MODE) {
@@ -17991,25 +19216,74 @@ export function getMavenCommand(srcPath, rootPath) {
       );
     }
     const result = safeSpawnSync(mavenWrapperCmd, ["wrapper:wrapper"], {
+      cdxgenActivity: {
+        kind: "probe",
+        metadata: {
+          tool: "maven",
+        },
+        probeType: "wrapper-readiness",
+      },
       cwd: rootPath,
       shell: isWin,
     });
     if (!result.error && !result.status) {
       isWrapperReady = true;
       mavenCmd = mavenWrapperCmd;
+      recordDecisionActivity(mavenCmd, {
+        metadata: {
+          decisionType: "path-resolution",
+          selectedSource: "wrapper",
+          tool: "maven",
+        },
+        reason: `Selected Maven wrapper ${mavenCmd} after readiness probe.`,
+      });
     } else {
       if (DEBUG_MODE) {
         console.log(
           "Maven wrapper script test has failed. Will use the installed version of maven.",
         );
       }
+      recordDecisionActivity(mavenWrapperCmd, {
+        metadata: {
+          decisionType: "fallback",
+          selectedSource: "PATH",
+          skippedSource: "wrapper",
+          tool: "maven",
+        },
+        reason: `Maven wrapper readiness probe failed for ${mavenWrapperCmd}; falling back to installed Maven.`,
+      });
     }
   }
   if (!isWrapperFound || !isWrapperReady) {
     if (process.env.MVN_CMD || process.env.MAVEN_CMD) {
       mavenCmd = process.env.MVN_CMD || process.env.MAVEN_CMD;
+      recordDecisionActivity(mavenCmd, {
+        metadata: {
+          decisionType: "path-resolution",
+          selectedSource: process.env.MVN_CMD ? "MVN_CMD" : "MAVEN_CMD",
+          tool: "maven",
+        },
+        reason: `Selected Maven command from environment (${mavenCmd}).`,
+      });
     } else if (process.env.MAVEN_HOME) {
       mavenCmd = join(process.env.MAVEN_HOME, "bin", "mvn");
+      recordDecisionActivity(mavenCmd, {
+        metadata: {
+          decisionType: "path-resolution",
+          selectedSource: "MAVEN_HOME",
+          tool: "maven",
+        },
+        reason: `Selected Maven command from MAVEN_HOME (${mavenCmd}).`,
+      });
+    } else {
+      recordDecisionActivity(mavenCmd, {
+        metadata: {
+          decisionType: "path-resolution",
+          selectedSource: "PATH",
+          tool: "maven",
+        },
+        reason: "Falling back to Maven from PATH.",
+      });
     }
   }
   return mavenCmd;
@@ -19344,16 +20618,17 @@ export async function addEvidenceForImports(
           const evidences = allImports[subevidence];
           for (const evidence of evidences) {
             if (evidence && Object.keys(evidence).length && evidence.fileName) {
-              pkg.evidence = pkg.evidence || {};
-              pkg.evidence.occurrences = pkg.evidence.occurrences || [];
-              const occurrenceLocation = `${evidence.fileName}${
-                evidence.lineNumber ? `#${evidence.lineNumber}` : ""
-              }`;
-              if (!seenOccurrenceLocations.has(occurrenceLocation)) {
-                pkg.evidence.occurrences.push({
-                  location: occurrenceLocation,
-                });
-                seenOccurrenceLocations.add(occurrenceLocation);
+              const occurrence = createOccurrenceEvidence(evidence.fileName, {
+                ...(evidence.lineNumber ? { line: evidence.lineNumber } : {}),
+              });
+              if (occurrence) {
+                pkg.evidence = pkg.evidence || {};
+                pkg.evidence.occurrences = pkg.evidence.occurrences || [];
+                const occurrenceLocation = `${occurrence.location}${occurrence.line ? `#${occurrence.line}` : ""}`;
+                if (!seenOccurrenceLocations.has(occurrenceLocation)) {
+                  pkg.evidence.occurrences.push(occurrence);
+                  seenOccurrenceLocations.add(occurrenceLocation);
+                }
               }
               importedModules.add(evidence.importedAs);
               for (const importedSm of evidence.importedModules || []) {
@@ -20578,14 +21853,16 @@ export function addEvidenceForDotnet(pkgList, slicesFile) {
           purlLocationMap[apkg.purl],
         ).sort();
         // Add the occurrences evidence
-        apkg.evidence.occurrences = locationOccurrences.map((l) => ({
-          location: l,
-        }));
+        apkg.evidence = apkg.evidence || {};
+        apkg.evidence.occurrences = locationOccurrences.map((l) =>
+          parseOccurrenceEvidenceLocation(l),
+        );
         // Set the package scope
         apkg.scope = "required";
       }
       // Add the imported modules to properties
       if (purlModulesMap[apkg.purl]) {
+        apkg.properties = apkg.properties || [];
         apkg.properties.push({
           name: "ImportedModules",
           value: Array.from(purlModulesMap[apkg.purl]).sort().join(", "),
@@ -20593,6 +21870,7 @@ export function addEvidenceForDotnet(pkgList, slicesFile) {
       }
       // Add the called methods to properties
       if (purlMethodsMap[apkg.purl]) {
+        apkg.properties = apkg.properties || [];
         apkg.properties.push({
           name: "CalledMethods",
           value: Array.from(purlMethodsMap[apkg.purl]).sort().join(", "),
@@ -20831,6 +22109,14 @@ export function extractPathEnv(envValues) {
       expandedBinPaths.push(apath);
     }
   }
+  recordObservedActivity("path-resolution", "PATH", {
+    metadata: {
+      capability: "path-lookup",
+      pathCount: expandedBinPaths.length,
+    },
+    reasonBuilder: (count) =>
+      `Expanded PATH into ${expandedBinPaths.length} executable search path(s)${buildReadCountSuffix(count)}.`,
+  });
   return expandedBinPaths;
 }
 
@@ -20839,13 +22125,17 @@ export function extractPathEnv(envValues) {
  *
  * @param basePath Base directory
  * @param binPaths {Array[String]} Paths containing potential binaries
+ * @param excludePaths {Array[String]} Container-relative paths that should be excluded from the result set
  * @return {Array[String]} List of executables
  */
-export function collectExecutables(basePath, binPaths) {
+export function collectExecutables(basePath, binPaths, excludePaths = []) {
   if (!binPaths) {
     return [];
   }
   const executablesByResolvedPath = new Map();
+  const excludedPathSet = new Set(
+    (excludePaths || []).map((f) => f.replace(/^\/+/, "").replace(/\\/g, "/")),
+  );
   const ignoreList = [
     "**/*.{h,c,cpp,hpp,man,txt,md,htm,html,jar,ear,war,zip,tar,egg,keepme,gitignore,json,js,py,pyc}",
     "[",
@@ -20865,12 +22155,38 @@ export function collectExecutables(basePath, binPaths) {
         let resolvedFile = file;
         try {
           resolvedFile = relative(basePath, realpathSync(join(basePath, file)));
-        } catch (_err) {
+          if (resolvedFile !== file) {
+            recordSymlinkResolution(join(basePath, file), resolvedFile, {
+              basePath,
+              metadata: {
+                resolutionKind: "executable",
+              },
+              reason: `Resolved executable candidate ${file} to ${resolvedFile}.`,
+            });
+          }
+        } catch (err) {
+          recordSymlinkResolution(join(basePath, file), undefined, {
+            basePath,
+            errorCode: err?.code || err?.name,
+            metadata: {
+              resolutionKind: "executable",
+            },
+            reason: `Failed to resolve executable candidate ${file}.`,
+            status: "failed",
+          });
           // Broken symlinks or permission errors can prevent realpath resolution.
           if (DEBUG_MODE) {
             console.log(`Unable to resolve executable path alias for ${file}`);
           }
         }
+        if (
+          excludedPathSet.has(file.replace(/^\/+/, "").replace(/\\/g, "/")) ||
+          excludedPathSet.has(
+            resolvedFile.replace(/^\/+/, "").replace(/\\/g, "/"),
+          )
+        ) {
+          continue;
+        }
         const existingFile = executablesByResolvedPath.get(resolvedFile);
         if (shouldPreferUsrMergedExecutablePath(file, existingFile)) {
           executablesByResolvedPath.set(resolvedFile, file);
@@ -20902,6 +22218,7 @@ function shouldPreferUsrMergedExecutablePath(file, existingFile) {
  * @param libPaths {Array[String]} Paths containing potential libraries
  * @param ldConf {String} Config file used by ldconfig to locate additional paths
  * @param ldConfDirPattern {String} Config directory that can contain more .conf files for ldconfig
+ * @param excludePaths {Array[String]} Container-relative paths that should be excluded from the result set
  *
  * @return {Array[String]} List of executables
  */
@@ -20910,11 +22227,15 @@ export function collectSharedLibs(
   libPaths,
   ldConf,
   ldConfDirPattern,
+  excludePaths = [],
 ) {
   if (!libPaths) {
     return [];
   }
-  let sharedLibs = [];
+  const sharedLibs = [];
+  const excludedPathSet = new Set(
+    (excludePaths || []).map((f) => f.replace(/^\/+/, "").replace(/\\/g, "/")),
+  );
   const ignoreList = [
     "**/*.{h,c,cpp,hpp,man,txt,md,htm,html,jar,ear,war,zip,tar,egg,keepme,gitignore,json,js,py,pyc}",
   ];
@@ -20946,7 +22267,39 @@ export function collectSharedLibs(
         follow: true,
         ignore: ignoreList,
       });
-      sharedLibs = sharedLibs.concat(files);
+      for (const file of files) {
+        let resolvedFile = file;
+        try {
+          resolvedFile = relative(basePath, realpathSync(join(basePath, file)));
+          recordSymlinkResolution(join(basePath, file), resolvedFile, {
+            basePath,
+            metadata: {
+              resolutionKind: "shared-library",
+            },
+            reason: `Resolved shared library candidate ${file} to ${resolvedFile}.`,
+          });
+        } catch (err) {
+          recordSymlinkResolution(join(basePath, file), undefined, {
+            basePath,
+            errorCode: err?.code || err?.name,
+            metadata: {
+              resolutionKind: "shared-library",
+            },
+            reason: `Failed to resolve shared library candidate ${file}.`,
+            status: "failed",
+          });
+          // Broken symlinks or permission errors can prevent realpath resolution.
+        }
+        if (
+          excludedPathSet.has(file.replace(/^\/+/, "").replace(/\\/g, "/")) ||
+          excludedPathSet.has(
+            resolvedFile.replace(/^\/+/, "").replace(/\\/g, "/"),
+          )
+        ) {
+          continue;
+        }
+        sharedLibs.push(file);
+      }
     } catch (_err) {
       // ignore
     }
@@ -21080,11 +22433,7 @@ export function hasDangerousUnicode(str) {
 
   // Check for control characters (except common ones like \n, \r, \t)
   const controlChars = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/;
-  if (controlChars.test(str)) {
-    return true;
-  }
-
-  return false;
+  return controlChars.test(str);
 }
 // biome-ignore-end lint/suspicious/noControlCharactersInRegex: validation
 
@@ -21119,11 +22468,7 @@ export function isValidDriveRoot(root) {
   }
 
   // Backslash (optional) must be exactly ASCII backslash (0x5C)
-  if (backslash && backslash.charCodeAt(0) !== 0x5c) {
-    return false;
-  }
-
-  return true;
+  return !(backslash && backslash.charCodeAt(0) !== 0x5c);
 }
 
 /**