@cyclonedx/cdxgen 12.3.2 → 12.4.0

package/lib/helpers/utils.js

@@ -11,6 +11,7 @@ import {
   mkdirSync,
   mkdtempSync,
   readFileSync,
+  realpathSync,
   rmSync,
   unlinkSync,
   writeFileSync,
@@ -55,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,
@@ -116,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;
@@ -160,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);
@@ -171,6 +768,8 @@ export function recordActivity(activity) {
   return entry;
 }
 
+dryRunReadTraceState.recordActivity = recordActivity;
+
 export function getRecordedActivities() {
   return [...activityLedger];
 }
@@ -178,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,
@@ -217,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) {
@@ -248,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;
 }
 
 /**
@@ -282,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;
 }
 
@@ -313,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) {
@@ -328,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) {
@@ -356,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"]);
@@ -428,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
@@ -439,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,
@@ -460,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,
@@ -483,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,
@@ -505,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) {
@@ -604,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;
 }
@@ -981,9 +1766,10 @@ export const PROJECT_TYPE_ALIASES = {
   dart: ["dart", "flutter", "pub"],
   haskell: ["haskell", "hackage", "cabal"],
   elixir: ["elixir", "hex", "mix"],
-  c: ["c", "cpp", "c++", "conan"],
+  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"],
@@ -1014,17 +1800,19 @@ export const PROJECT_TYPE_ALIASES = {
     "visionos",
   ],
   binary: ["binary", "blint"],
-  oci: ["docker", "oci", "container", "podman"],
+  oci: ["docker", "oci", "container", "podman", "rootfs", "oci-dir"],
   cocoa: ["cocoa", "cocoapods", "objective-c", "swift", "ios"],
   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": [
@@ -1154,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.
  *
@@ -1195,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
@@ -1227,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(),
@@ -1246,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(),
@@ -1266,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(),
@@ -1292,6 +2241,7 @@ export const cdxgenAgent = got.extend({
           response.url;
         recordActivity({
           kind: "network",
+          networkIntent: response.request.options.context?.activityIntent,
           status: "completed",
           target: activityTarget,
         });
@@ -1305,6 +2255,7 @@ export const cdxgenAgent = got.extend({
         }
         recordActivity({
           kind: "network",
+          networkIntent: error.options?.context?.activityIntent,
           reason: error.message,
           status: "failed",
           target:
@@ -1388,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,
@@ -1398,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}'.`,
@@ -1405,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);
     }
@@ -2585,6 +3558,23 @@ export async function parsePkgLock(pkgLockFile, options = {}) {
           value: "true",
         });
       }
+      const npmManifestSources = collectNpmManifestSources(node);
+      if (npmManifestSources.length) {
+        addComponentProperty(
+          pkg,
+          "cdx:npm:manifestSourceType",
+          npmManifestSources
+            .map((manifestSource) => manifestSource.type)
+            .join(","),
+        );
+        addComponentProperty(
+          pkg,
+          "cdx:npm:manifestSource",
+          npmManifestSources
+            .map((manifestSource) => manifestSource.value)
+            .join(","),
+        );
+      }
       // This getter method could fail with errors at times.
       // Example Error: Invalid tag name "^>=6.0.0" of package "^>=6.0.0": Tags may not have any characters that encodeURIComponent encodes.
       try {
@@ -6811,8 +7801,17 @@ export async function getPyMetadata(pkgList, fetchDepsInfo) {
           value: origName,
         });
       }
-      if (body.releases?.[p.version] && body.releases[p.version].length) {
-        const digest = body.releases[p.version][0].digests;
+      const releaseEntries = body.releases?.[p.version]?.length
+        ? body.releases[p.version]
+        : Array.isArray(body.urls)
+          ? body.urls
+          : [];
+      mergeExternalReferences(
+        p,
+        collectPypiReleaseExternalReferences(releaseEntries),
+      );
+      if (releaseEntries.length) {
+        const digest = releaseEntries[0].digests;
         if (digest["sha256"]) {
           p._integrity = `sha256-${digest["sha256"]}`;
         } else if (digest["md5"]) {
@@ -7001,46 +8000,327 @@ export function parseBdistMetadata(mDataFile, rawMetadata = undefined) {
         break;
     }
   }
-  if (mDataFile) {
-    pkg.evidence = {
-      identity: {
-        field: "purl",
-        confidence: 0.5,
-        methods: [
-          {
-            technique: "manifest-analysis",
-            confidence: 0.5,
-            value: mDataFile,
-          },
-        ],
-      },
+  if (mDataFile) {
+    pkg.evidence = {
+      identity: {
+        field: "purl",
+        confidence: 0.5,
+        methods: [
+          {
+            technique: "manifest-analysis",
+            confidence: 0.5,
+            value: mDataFile,
+          },
+        ],
+      },
+    };
+  }
+  pkg.purl = `pkg:pypi/${pkg.name.toLowerCase().replaceAll("_", "-")}@${pkg.version}`;
+  pkg["bom-ref"] = pkg.purl;
+  return [pkg];
+}
+
+/**
+ * Method to parse pipfile.lock data
+ *
+ * @param {Object} lockData JSON data from Pipfile.lock
+ */
+export async function parsePiplockData(lockData) {
+  const pkgList = [];
+  Object.keys(lockData)
+    .filter((i) => i !== "_meta")
+    .forEach((k) => {
+      const depBlock = lockData[k];
+      Object.keys(depBlock).forEach((p) => {
+        const pkg = depBlock[p];
+        if (Object.hasOwn(pkg, "version")) {
+          const versionStr = pkg.version.replace("==", "");
+          pkgList.push({ name: p, version: versionStr });
+        }
+      });
+    });
+  return await getPyMetadata(pkgList, false);
+}
+
+function addComponentProperty(component, name, value) {
+  if (value === undefined || value === null || value === "" || !component) {
+    return;
+  }
+  component.properties = component.properties || [];
+  if (
+    component.properties.some(
+      (property) => property.name === name && property.value === value,
+    )
+  ) {
+    return;
+  }
+  component.properties.push({
+    name,
+    value,
+  });
+}
+
+const PYTHON_DIRECT_REFERENCE_PATTERN =
+  /^([A-Za-z0-9_.-]+)(?:\[[^\]]+])?\s*@\s*(\S+)$/;
+
+function isWindowsAbsolutePath(value) {
+  return /^[a-zA-Z]:[\\/]/.test(value) || value.startsWith("\\\\");
+}
+
+function createExternalReferenceKey(reference) {
+  return JSON.stringify([
+    reference.type,
+    reference.url,
+    reference.comment || "",
+  ]);
+}
+
+function classifyNpmManifestSource(spec) {
+  if (typeof spec !== "string" || !spec.trim()) {
+    return undefined;
+  }
+  const normalizedSpec = spec.trim();
+  const lowerSpec = normalizedSpec.toLowerCase();
+  if (
+    lowerSpec.startsWith("git+") ||
+    lowerSpec.startsWith("git://") ||
+    lowerSpec.startsWith("github:") ||
+    lowerSpec.startsWith("gitlab:") ||
+    lowerSpec.startsWith("bitbucket:") ||
+    lowerSpec.startsWith("gist:")
+  ) {
+    return {
+      type: "git",
+      value: normalizedSpec,
+    };
+  }
+  if (lowerSpec.startsWith("http://") || lowerSpec.startsWith("https://")) {
+    return {
+      type: "url",
+      value: normalizedSpec,
+    };
+  }
+  if (
+    lowerSpec.startsWith("file:") ||
+    lowerSpec.startsWith("link:") ||
+    lowerSpec.startsWith("workspace:") ||
+    normalizedSpec.startsWith("./") ||
+    normalizedSpec.startsWith("../") ||
+    normalizedSpec.startsWith("/") ||
+    isWindowsAbsolutePath(normalizedSpec)
+  ) {
+    return {
+      type: "path",
+      value: normalizedSpec,
+    };
+  }
+  return undefined;
+}
+
+function collectNpmManifestSources(node) {
+  const manifestSources = [];
+  const seen = new Set();
+  if (!node?.edgesIn) {
+    return manifestSources;
+  }
+  for (const edge of node.edgesIn) {
+    const manifestSource = classifyNpmManifestSource(edge?.spec);
+    if (!manifestSource) {
+      continue;
+    }
+    const dedupeKey = `${manifestSource.type}|${manifestSource.value}`;
+    if (seen.has(dedupeKey)) {
+      continue;
+    }
+    seen.add(dedupeKey);
+    manifestSources.push(manifestSource);
+  }
+  return manifestSources;
+}
+
+function normalizePythonDependencyKey(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    return undefined;
+  }
+  return value.trim().toLowerCase().replaceAll("_", "-");
+}
+
+function extractPythonDependencyKey(value) {
+  const manifestSource = parsePyProjectDependencySourceString(value);
+  if (manifestSource?.name) {
+    return normalizePythonDependencyKey(manifestSource.name);
+  }
+  const packageMatch =
+    typeof value === "string"
+      ? value.trim().match(/^([A-Za-z0-9_.-]+)(?:\[[^\]]+])?/)
+      : undefined;
+  return normalizePythonDependencyKey(packageMatch?.[1]);
+}
+function classifyPythonManifestSourceValue(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    return undefined;
+  }
+  const normalizedValue = value.trim();
+  const lowerValue = normalizedValue.toLowerCase();
+  if (
+    lowerValue.startsWith("git+") ||
+    lowerValue.startsWith("git://") ||
+    lowerValue.startsWith("git@") ||
+    lowerValue.startsWith("ssh://git@")
+  ) {
+    return {
+      type: "git",
+      value: normalizedValue,
+    };
+  }
+  if (
+    lowerValue.startsWith("http://") ||
+    lowerValue.startsWith("https://") ||
+    lowerValue.startsWith("ftp://")
+  ) {
+    return {
+      type: "url",
+      value: normalizedValue,
+    };
+  }
+  if (
+    lowerValue.startsWith("file:") ||
+    normalizedValue.startsWith("./") ||
+    normalizedValue.startsWith("../") ||
+    normalizedValue.startsWith("/") ||
+    isWindowsAbsolutePath(normalizedValue)
+  ) {
+    return {
+      type: "path",
+      value: normalizedValue,
+    };
+  }
+  return undefined;
+}
+
+function applyManifestSourceProperties(
+  component,
+  propertyPrefix,
+  manifestSource,
+) {
+  if (!manifestSource?.type || !manifestSource?.value) {
+    return;
+  }
+  addComponentProperty(
+    component,
+    `${propertyPrefix}:manifestSourceType`,
+    manifestSource.type,
+  );
+  addComponentProperty(
+    component,
+    `${propertyPrefix}:manifestSource`,
+    manifestSource.value,
+  );
+}
+
+function recordPythonDependencySource(
+  dependencySourceMap,
+  dependencyName,
+  sourceType,
+  sourceValue,
+) {
+  const normalizedKey = normalizePythonDependencyKey(dependencyName);
+  if (!normalizedKey || !sourceType || !sourceValue) {
+    return;
+  }
+  dependencySourceMap[normalizedKey] = {
+    type: sourceType,
+    value: sourceValue,
+  };
+}
+
+function parsePyProjectDependencySourceString(value) {
+  if (typeof value !== "string" || !value.includes("@")) {
+    return undefined;
+  }
+  const directReferenceMatch = value
+    .trim()
+    .match(PYTHON_DIRECT_REFERENCE_PATTERN);
+  if (!directReferenceMatch) {
+    return undefined;
+  }
+  const manifestSource = classifyPythonManifestSourceValue(
+    directReferenceMatch[2],
+  );
+  if (!manifestSource) {
+    return undefined;
+  }
+  return {
+    name: directReferenceMatch[1],
+    ...manifestSource,
+  };
+}
+
+function collectPythonManifestSource(pkg) {
+  const sourceCandidates = [
+    { kind: "git", value: pkg?.source?.git },
+    { kind: "git", value: pkg?.vcs?.git },
+    { kind: "url", value: pkg?.vcs?.url },
+    { kind: "url", value: pkg?.source?.url },
+    { kind: "path", value: pkg?.source?.path },
+    { kind: "path", value: pkg?.source?.editable },
+    { kind: "path", value: pkg?.source?.virtual },
+  ];
+  for (const candidate of sourceCandidates) {
+    if (typeof candidate.value !== "string" || !candidate.value.trim()) {
+      continue;
+    }
+    const normalizedValue = candidate.value.trim();
+    if (candidate.kind === "git") {
+      return {
+        type: "git",
+        value: normalizedValue.startsWith("git+")
+          ? normalizedValue
+          : `git+${normalizedValue}`,
+      };
+    }
+    const manifestSource = classifyPythonManifestSourceValue(normalizedValue);
+    if (manifestSource) {
+      return manifestSource;
+    }
+    return {
+      type: candidate.kind,
+      value: normalizedValue,
     };
   }
-  pkg.purl = `pkg:pypi/${pkg.name.toLowerCase().replaceAll("_", "-")}@${pkg.version}`;
-  pkg["bom-ref"] = pkg.purl;
-  return [pkg];
+  return undefined;
 }
 
-/**
- * Method to parse pipfile.lock data
- *
- * @param {Object} lockData JSON data from Pipfile.lock
- */
-export async function parsePiplockData(lockData) {
-  const pkgList = [];
-  Object.keys(lockData)
-    .filter((i) => i !== "_meta")
-    .forEach((k) => {
-      const depBlock = lockData[k];
-      Object.keys(depBlock).forEach((p) => {
-        const pkg = depBlock[p];
-        if (Object.hasOwn(pkg, "version")) {
-          const versionStr = pkg.version.replace("==", "");
-          pkgList.push({ name: p, version: versionStr });
-        }
-      });
-    });
-  return await getPyMetadata(pkgList, false);
+function parsePythonRequirementManifestSource(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    return undefined;
+  }
+  const normalizedValue = value.trim();
+  const directReferenceMatch = normalizedValue.match(
+    PYTHON_DIRECT_REFERENCE_PATTERN,
+  );
+  if (directReferenceMatch) {
+    const manifestSource = classifyPythonManifestSourceValue(
+      directReferenceMatch[2],
+    );
+    if (manifestSource) {
+      return {
+        name: directReferenceMatch[1],
+        ...manifestSource,
+      };
+    }
+  }
+  const vcsRequirementMatch = normalizedValue.match(
+    /^(git\+\S+?)(?:#.*egg=([A-Za-z0-9_.-]+))?$/,
+  );
+  if (vcsRequirementMatch?.[2]) {
+    return {
+      name: vcsRequirementMatch[2],
+      type: "git",
+      value: vcsRequirementMatch[1],
+    };
+  }
+  return undefined;
 }
 
 /**
@@ -7102,6 +8382,7 @@ export function parsePyProjectTomlFile(tomlFile) {
   let tomlData;
   const directDepsKeys = {};
   const groupDepsKeys = {};
+  const dependencySourceMap = {};
   try {
     tomlData = toml.parse(readFileSync(tomlFile, { encoding: "utf-8" }));
   } catch (err) {
@@ -7173,8 +8454,19 @@ export function parsePyProjectTomlFile(tomlFile) {
   }
   if (tomlData?.project?.dependencies) {
     for (const adep of tomlData.project.dependencies) {
-      // Example: bcrypt>=4.2.0
-      directDepsKeys[adep.split(/[\s<>=]/)[0]] = true;
+      const dependencyKey = extractPythonDependencyKey(adep);
+      if (dependencyKey) {
+        directDepsKeys[dependencyKey] = true;
+      }
+      const manifestSource = parsePyProjectDependencySourceString(adep);
+      if (manifestSource) {
+        recordPythonDependencySource(
+          dependencySourceMap,
+          manifestSource.name,
+          manifestSource.type,
+          manifestSource.value,
+        );
+      }
     }
   }
   if (tomlData["dependency-groups"]) {
@@ -7186,6 +8478,15 @@ export function parsePyProjectTomlFile(tomlFile) {
             groupDepsKeys[pname] = [];
           }
           groupDepsKeys[pname].push(agroup);
+          const manifestSource = parsePyProjectDependencySourceString(p);
+          if (manifestSource) {
+            recordPythonDependencySource(
+              dependencySourceMap,
+              manifestSource.name,
+              manifestSource.type,
+              manifestSource.value,
+            );
+          }
         } else {
           return;
         }
@@ -7206,6 +8507,29 @@ export function parsePyProjectTomlFile(tomlFile) {
         ].includes(adep)
       ) {
         directDepsKeys[adep] = true;
+        const poetryDependency = tomlData.tool.poetry.dependencies[adep];
+        if (poetryDependency?.git) {
+          recordPythonDependencySource(
+            dependencySourceMap,
+            adep,
+            "git",
+            poetryDependency.git,
+          );
+        } else if (poetryDependency?.url) {
+          recordPythonDependencySource(
+            dependencySourceMap,
+            adep,
+            "url",
+            poetryDependency.url,
+          );
+        } else if (poetryDependency?.path) {
+          recordPythonDependencySource(
+            dependencySourceMap,
+            adep,
+            "path",
+            poetryDependency.path,
+          );
+        }
       }
     } // for
     if (tomlData?.tool?.poetry?.group) {
@@ -7217,10 +8541,63 @@ export function parsePyProjectTomlFile(tomlFile) {
             groupDepsKeys[adep] = [];
           }
           groupDepsKeys[adep].push(agroup);
+          const poetryDependency =
+            tomlData.tool.poetry.group[agroup]?.dependencies?.[adep];
+          if (poetryDependency?.git) {
+            recordPythonDependencySource(
+              dependencySourceMap,
+              adep,
+              "git",
+              poetryDependency.git,
+            );
+          } else if (poetryDependency?.url) {
+            recordPythonDependencySource(
+              dependencySourceMap,
+              adep,
+              "url",
+              poetryDependency.url,
+            );
+          } else if (poetryDependency?.path) {
+            recordPythonDependencySource(
+              dependencySourceMap,
+              adep,
+              "path",
+              poetryDependency.path,
+            );
+          }
         }
       } // for
     }
   }
+  if (tomlData?.tool?.uv?.sources) {
+    for (const adep of Object.keys(tomlData.tool.uv.sources)) {
+      const uvSource = Array.isArray(tomlData.tool.uv.sources[adep])
+        ? tomlData.tool.uv.sources[adep][0]
+        : tomlData.tool.uv.sources[adep];
+      if (uvSource?.git) {
+        recordPythonDependencySource(
+          dependencySourceMap,
+          adep,
+          "git",
+          uvSource.git,
+        );
+      } else if (uvSource?.url) {
+        recordPythonDependencySource(
+          dependencySourceMap,
+          adep,
+          "url",
+          uvSource.url,
+        );
+      } else if (uvSource?.path) {
+        recordPythonDependencySource(
+          dependencySourceMap,
+          adep,
+          "path",
+          uvSource.path,
+        );
+      }
+    }
+  }
   return {
     parentComponent: pkg,
     poetryMode,
@@ -7229,9 +8606,146 @@ export function parsePyProjectTomlFile(tomlFile) {
     workspacePaths,
     directDepsKeys,
     groupDepsKeys,
+    dependencySourceMap,
   };
 }
 
+function collectPythonLockDistributionReferences(pkg) {
+  const externalReferences = [];
+  const seen = new Set();
+
+  function addExternalReference(type, url, comment) {
+    if (typeof url !== "string" || !url.trim()) {
+      return;
+    }
+    const normalizedUrl = url.trim();
+    const reference = {
+      type,
+      url: normalizedUrl,
+      comment,
+    };
+    const referenceKey = createExternalReferenceKey(reference);
+    if (seen.has(referenceKey)) {
+      return;
+    }
+    seen.add(referenceKey);
+    externalReferences.push(reference);
+  }
+
+  addExternalReference("distribution", pkg?.archive?.url, "archive");
+  addExternalReference("distribution", pkg?.sdist?.url, "sdist");
+  if (Array.isArray(pkg?.wheels)) {
+    for (const wheel of pkg.wheels) {
+      addExternalReference(
+        "distribution",
+        wheel?.url,
+        wheel?.file || wheel?.name || wheel?.filename || "wheel",
+      );
+    }
+  }
+  const vcsSource = [
+    { kind: "url", value: pkg?.vcs?.url },
+    { kind: "git", value: pkg?.vcs?.git },
+    { kind: "git", value: pkg?.source?.git },
+  ].find(
+    (entry) => typeof entry.value === "string" && entry.value.trim().length > 0,
+  );
+  if (vcsSource) {
+    const vcsUrl = vcsSource.value.trim();
+    const normalizedVcsUrl =
+      vcsSource.kind === "git" && !vcsUrl.startsWith("git+")
+        ? `git+${vcsUrl}`
+        : vcsUrl;
+    addExternalReference("vcs", normalizedVcsUrl, "vcs");
+  }
+  if (pkg?.source?.url) {
+    const manifestSource = classifyPythonManifestSourceValue(pkg.source.url);
+    addExternalReference(
+      manifestSource?.type === "git" ? "vcs" : "distribution",
+      pkg.source.url,
+      "source",
+    );
+  }
+  return externalReferences;
+}
+
+function collectPythonLockMetadataFileEntries(lockTomlObj, pkg) {
+  if (!lockTomlObj?.metadata?.files || !pkg?.name) {
+    return [];
+  }
+  const expectedKeys = new Set([normalizePythonDependencyKey(pkg.name)]);
+  if (pkg.version) {
+    expectedKeys.add(
+      `${normalizePythonDependencyKey(pkg.name)} ${`${pkg.version}`.trim().toLowerCase()}`,
+    );
+  }
+  const matchingEntries = [];
+  for (const [entryKey, entryValues] of Object.entries(
+    lockTomlObj.metadata.files,
+  )) {
+    if (!Array.isArray(entryValues)) {
+      continue;
+    }
+    if (expectedKeys.has(normalizePythonDependencyKey(entryKey))) {
+      matchingEntries.push(...entryValues);
+    }
+  }
+  return matchingEntries;
+}
+
+function mergeExternalReferences(component, references) {
+  if (!references?.length) {
+    return;
+  }
+  const existingReferences = component.externalReferences || [];
+  const seen = new Set(
+    existingReferences.map((reference) =>
+      createExternalReferenceKey(reference),
+    ),
+  );
+  for (const reference of references) {
+    const dedupeKey = createExternalReferenceKey(reference);
+    if (seen.has(dedupeKey)) {
+      continue;
+    }
+    seen.add(dedupeKey);
+    existingReferences.push(reference);
+  }
+  if (existingReferences.length) {
+    component.externalReferences = existingReferences;
+  }
+}
+
+function collectPythonLockMetadataDistributionReferences(fileEntries) {
+  const distributionReferences = [];
+  for (const fileEntry of fileEntries || []) {
+    if (typeof fileEntry?.url !== "string" || !fileEntry.url.trim()) {
+      continue;
+    }
+    distributionReferences.push({
+      type: "distribution",
+      url: fileEntry.url.trim(),
+      comment: fileEntry.file,
+    });
+  }
+  return distributionReferences;
+}
+
+function collectPypiReleaseExternalReferences(releaseEntries) {
+  const externalReferences = [];
+  for (const releaseEntry of releaseEntries || []) {
+    if (typeof releaseEntry?.url !== "string" || !releaseEntry.url.trim()) {
+      continue;
+    }
+    externalReferences.push({
+      type: "distribution",
+      url: releaseEntry.url.trim(),
+      comment: releaseEntry.filename || releaseEntry.packagetype,
+    });
+  }
+  return externalReferences;
+}
+
 /**
  * Method to parse python lock files such as poetry.lock, pdm.lock, uv.lock, and pylock.toml.
  *
@@ -7248,6 +8762,7 @@ export async function parsePyLockData(lockData, lockFile, pyProjectFile) {
   const pkgBomRefMap = {};
   let directDepsKeys = {};
   let groupDepsKeys = {};
+  let dependencySourceMap = {};
   let parentComponent;
   let workspacePaths;
   let workspaceWarningShown = false;
@@ -7255,6 +8770,7 @@ export async function parsePyLockData(lockData, lockFile, pyProjectFile) {
   let pyLockProperties = [];
   // Keep track of any workspace components to be added to the parent component
   const workspaceComponentMap = {};
+  const workspaceDependencySourceMap = {};
   const workspacePyProjMap = {};
   const workspaceRefPyProjMap = {};
   const pkgParentMap = {};
@@ -7274,6 +8790,7 @@ export async function parsePyLockData(lockData, lockFile, pyProjectFile) {
     const pyProjMap = parsePyProjectTomlFile(pyProjectFile);
     directDepsKeys = pyProjMap.directDepsKeys || {};
     groupDepsKeys = pyProjMap.groupDepsKeys || {};
+    dependencySourceMap = pyProjMap.dependencySourceMap || {};
     parentComponent = pyProjMap.parentComponent;
     workspacePaths = pyProjMap.workspacePaths;
     if (workspacePaths?.length) {
@@ -7337,6 +8854,12 @@ export async function parsePyLockData(lockData, lockFile, pyProjectFile) {
             }
           }
           const wparentComponentRef = wcompMap.parentComponent["bom-ref"];
+          if (wcompMap?.dependencySourceMap) {
+            Object.assign(
+              workspaceDependencySourceMap,
+              wcompMap.dependencySourceMap,
+            );
+          }
           // Track the parents of workspace direct dependencies
           if (wcompMap?.directDepsKeys) {
             for (const wdd of Object.keys(wcompMap?.directDepsKeys)) {
@@ -7408,6 +8931,11 @@ export async function parsePyLockData(lockData, lockFile, pyProjectFile) {
         value: workspacePyProjMap[apkg.name] || pyProjectFile,
       });
     }
+    const manifestSource =
+      dependencySourceMap[normalizePythonDependencyKey(apkg.name)] ||
+      workspaceDependencySourceMap[normalizePythonDependencyKey(apkg.name)] ||
+      collectPythonManifestSource(apkg);
+    applyManifestSourceProperties(pkg, "cdx:pypi", manifestSource);
     if (apkg.optional) {
       pkg.scope = "optional";
     }
@@ -7449,6 +8977,7 @@ export async function parsePyLockData(lockData, lockFile, pyProjectFile) {
         });
       }
     }
+    mergeExternalReferences(pkg, collectPythonLockDistributionReferences(apkg));
     if (pyLockMode) {
       pkg.properties = pkg.properties.concat(
         collectPyLockPackageProperties(apkg),
@@ -7511,9 +9040,17 @@ export async function parsePyLockData(lockData, lockFile, pyProjectFile) {
         }
       }
     }
-    if (lockTomlObj?.metadata?.files?.[pkg.name]?.length) {
+    const metadataFileEntries = collectPythonLockMetadataFileEntries(
+      lockTomlObj,
+      pkg,
+    );
+    mergeExternalReferences(
+      pkg,
+      collectPythonLockMetadataDistributionReferences(metadataFileEntries),
+    );
+    if (metadataFileEntries.length) {
       pkg.components = [];
-      for (const afileObj of lockTomlObj.metadata.files[pkg.name]) {
+      for (const afileObj of metadataFileEntries) {
         const hashParts = afileObj?.hash?.split(":");
         let hashes;
         if (hashParts?.length === 2) {
@@ -7547,8 +9084,9 @@ export async function parsePyLockData(lockData, lockFile, pyProjectFile) {
         pkg.components = (pkg.components || []).concat(pylockFileComponents);
       }
     }
+    const normalizedPkgName = normalizePythonDependencyKey(pkg.name);
     if (
-      directDepsKeys[pkg.name] ||
+      directDepsKeys[normalizedPkgName] ||
       (hasWorkspaces && !Object.keys(workspaceComponentMap).length)
     ) {
       rootList.push(pkg);
@@ -7743,6 +9281,23 @@ export async function parseReqFile(reqFile, fetchDepsInfo = false) {
 const LICENSE_ID_COMMENTS_PATTERN =
   /^(Apache-2\.0|MIT|ISC|GPL-|LGPL-|BSD-[23]-Clause)/i;
 
+function parseLicenseComment(comment) {
+  if (!comment) {
+    return undefined;
+  }
+  const licenses = comment
+    .split("/")
+    .map((value) => {
+      const licenseId = value.trim();
+      if (!licenseId.match(LICENSE_ID_COMMENTS_PATTERN)) {
+        return undefined;
+      }
+      return { license: { id: licenseId } };
+    })
+    .filter((value) => value !== undefined);
+  return licenses.length ? licenses : undefined;
+}
+
 /**
  * Method to parse requirements.txt file. Must only be used internally.
  *
@@ -7780,11 +9335,16 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
   const lines = normalizedData.split("\n");
   for (const line of lines) {
     let l = line.trim();
+    let editableRequirement = false;
     if (l.includes("# Basic requirements")) {
       compScope = "required";
     } else if (l.includes("added by pip freeze")) {
       compScope = undefined;
     }
+    if (l.startsWith("-e ") || l.startsWith("--editable ")) {
+      editableRequirement = true;
+      l = l.replace(/^--editable\s+|^-e\s+/, "").trim();
+    }
     if (l.startsWith("Skipping line") || l.startsWith("(add")) {
       continue;
     }
@@ -7833,10 +9393,49 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
       markers = parts.slice(1).join(";").trim();
       structuredMarkers = parseReqEnvMarkers(markers);
     }
+    const requirementManifestSource = parsePythonRequirementManifestSource(l);
+    if (requirementManifestSource?.name) {
+      const apkg = {
+        name: requirementManifestSource.name,
+        version: null,
+        scope: compScope,
+        evidence,
+      };
+      if (hashes.length > 0) {
+        apkg.hashes = hashes;
+      }
+      const licenses = parseLicenseComment(comment);
+      if (licenses) {
+        apkg.licenses = licenses;
+      }
+      applyManifestSourceProperties(
+        apkg,
+        "cdx:pypi",
+        requirementManifestSource,
+      );
+      if (editableRequirement) {
+        addComponentProperty(apkg, "cdx:pypi:editable", "true");
+      }
+      if (markers) {
+        addComponentProperty(apkg, "cdx:pip:markers", markers);
+        if (structuredMarkers?.length > 0) {
+          addComponentProperty(
+            apkg,
+            "cdx:pip:structuredMarkers",
+            JSON.stringify(structuredMarkers),
+          );
+        }
+      }
+      if (reqFile) {
+        addComponentProperty(apkg, "SrcFile", reqFile);
+      }
+      pkgList.push(apkg);
+      continue;
+    }
 
     // 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;
@@ -7866,20 +9465,9 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
       if (hashes.length > 0) {
         apkg.hashes = hashes;
       }
-      if (comment) {
-        apkg.licenses = comment
-          .split("/")
-          .map((c) => {
-            const licenseObj = {};
-            const cId = c.trim();
-            if (cId.match(LICENSE_ID_COMMENTS_PATTERN)) {
-              licenseObj.id = cId;
-            } else {
-              return undefined;
-            }
-            return { license: licenseObj };
-          })
-          .filter((l) => l !== undefined);
+      const licenses = parseLicenseComment(comment);
+      if (licenses) {
+        apkg.licenses = licenses;
       }
       if (extras && extras.length > 0) {
         properties.push({
@@ -7905,12 +9493,18 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
           });
         }
       }
+      if (editableRequirement) {
+        properties.push({
+          name: "cdx:pypi:editable",
+          value: "true",
+        });
+      }
       if (properties.length) {
         apkg.properties = properties;
       }
       pkgList.push(apkg);
     } else {
-      const match = l.match(/^([a-zA-Z0-9_\-\.]+)(.*)$/);
+      const match = l.match(/^([a-zA-Z0-9_\-.]+)(.*)$/);
       if (!match) {
         continue;
       }
@@ -7932,20 +9526,9 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
         scope: compScope,
         evidence,
       };
-      if (comment) {
-        apkg.licenses = comment
-          .split("/")
-          .map((c) => {
-            const licenseObj = {};
-            const cId = c.trim();
-            if (cId.match(LICENSE_ID_COMMENTS_PATTERN)) {
-              licenseObj.id = cId;
-            } else {
-              return undefined;
-            }
-            return { license: licenseObj };
-          })
-          .filter((l) => l !== undefined);
+      const licenses = parseLicenseComment(comment);
+      if (licenses) {
+        apkg.licenses = licenses;
       }
       if (versionSpecifiers && !versionSpecifiers.startsWith("==")) {
         properties.push({
@@ -7965,6 +9548,12 @@ async function parseReqData(reqFile, reqData = null, fetchDepsInfo = false) {
           });
         }
       }
+      if (editableRequirement) {
+        properties.push({
+          name: "cdx:pypi:editable",
+          value: "true",
+        });
+      }
       if (properties.length) {
         apkg.properties = properties;
       }
@@ -12621,48 +14210,230 @@ export function parseConanLockData(conanLockData) {
       }
     }
   }
-  return { pkgList, dependencies, parentComponentDependencies };
+  return { pkgList, dependencies, parentComponentDependencies };
+}
+
+/**
+ * Parse a Conan conanfile.txt and extract required and optional packages.
+ *
+ * @param {string} conanData Raw text contents of a conanfile.txt
+ * @returns {Object[]} Array of package objects with purl, name, version, and scope
+ */
+export function parseConanData(conanData) {
+  const pkgList = [];
+  if (!conanData) {
+    return pkgList;
+  }
+  let scope = "required";
+  conanData.split("\n").forEach((l) => {
+    l = l.replace("\r", "");
+    if (l.includes("[build_requires]")) {
+      scope = "optional";
+    }
+    if (l.includes("[requires]")) {
+      scope = "required";
+    }
+
+    // The line must start with sequence non-whitespace characters, followed by a slash,
+    // followed by at least one more non-whitespace character.
+    // Provides a heuristic for locating Conan package references inside conanfile.txt files.
+    if (l.match(/^[^\s\/]+\/\S+/)) {
+      const [purl, name, version] =
+        mapConanPkgRefToPurlStringAndNameAndVersion(l);
+      if (purl !== null) {
+        pkgList.push({
+          name,
+          version,
+          purl,
+          "bom-ref": decodeURIComponent(purl),
+          scope,
+        });
+      }
+    }
+  });
+  return pkgList;
+}
+
+/**
+ * Construct a generic package component object for collider-managed packages.
+ *
+ * @param {string} name Package name
+ * @param {Object} pkgData Locked package entry from collider.lock
+ * @param {string} lockFile Source lock file path
+ * @param {string} dependencyKind Whether the package is direct or transitive
+ * @returns {Object|undefined} Package component
+ */
+function buildColliderComponent(name, pkgData, lockFile, dependencyKind) {
+  if (!name) {
+    return undefined;
+  }
+  pkgData = pkgData || {};
+  dependencyKind = dependencyKind || "transitive";
+  const version = pkgData?.version || "";
+  const purl = new PackageURL(
+    "generic",
+    "",
+    name,
+    version || undefined,
+    null,
+    null,
+  ).toString();
+  const properties = [
+    {
+      name: "cdx:collider:dependencyKind",
+      value: dependencyKind,
+    },
+  ];
+  if (lockFile) {
+    properties.unshift({
+      name: "SrcFile",
+      value: lockFile,
+    });
+  }
+  const wrapHash =
+    typeof pkgData?.wrap_hash === "string" ? pkgData.wrap_hash.trim() : "";
+  const wrapHashMatch = wrapHash.match(/^sha256:([0-9A-Fa-f]{64})$/);
+  if (wrapHash) {
+    properties.push({
+      name: "cdx:collider:wrapHash",
+      value: wrapHash,
+    });
+  }
+  properties.push({
+    name: "cdx:collider:hasWrapHash",
+    value: wrapHashMatch ? "true" : "false",
+  });
+  if (wrapHash && !wrapHashMatch) {
+    properties.push({
+      name: "cdx:collider:wrapHashInvalid",
+      value: "true",
+    });
+  }
+  let originReference;
+  if (typeof pkgData?.origin === "string" && pkgData.origin.trim()) {
+    try {
+      const originUrl = new URL(pkgData.origin.trim());
+      const originHadSensitiveParts = Boolean(
+        originUrl.username ||
+          originUrl.password ||
+          originUrl.search ||
+          originUrl.hash,
+      );
+      originUrl.username = "";
+      originUrl.password = "";
+      originUrl.search = "";
+      originUrl.hash = "";
+      originReference = originUrl.toString();
+      properties.push({
+        name: "cdx:collider:origin",
+        value: originReference,
+      });
+      properties.push({
+        name: "cdx:collider:originScheme",
+        value: originUrl.protocol.replace(":", ""),
+      });
+      if (originUrl.host) {
+        properties.push({
+          name: "cdx:collider:originHost",
+          value: originUrl.host,
+        });
+      }
+      if (originHadSensitiveParts) {
+        properties.push({
+          name: "cdx:collider:originSanitized",
+          value: "true",
+        });
+      }
+    } catch {
+      thoughtLog("Ignoring invalid Collider origin URL");
+    }
+  }
+  const component = {
+    name,
+    version,
+    purl,
+    "bom-ref": decodeURIComponent(purl),
+    properties,
+  };
+  if (dependencyKind === "direct") {
+    component.scope = "required";
+  }
+  if (wrapHashMatch) {
+    component.hashes = [
+      {
+        alg: "SHA-256",
+        content: wrapHashMatch[1].toLowerCase(),
+      },
+    ];
+  }
+  if (originReference) {
+    component.externalReferences = [
+      {
+        type: "distribution",
+        url: originReference,
+      },
+    ];
+  }
+  return component;
 }
 
 /**
- * Parse a Conan conanfile.txt and extract required and optional packages.
+ * Parse Collider lock file data (collider.lock) and return the package list and
+ * parent component dependencies.
  *
- * @param {string} conanData Raw text contents of a conanfile.txt
- * @returns {Object[]} Array of package objects with purl, name, version, and scope
+ * @param {string} colliderLockData Raw JSON string of the Collider lock file
+ * @param {string} lockFile Source lock file path
+ * @returns {{ pkgList: Object[], dependencies: Object, parentComponentDependencies: string[] }}
  */
-export function parseConanData(conanData) {
+export function parseColliderLockData(colliderLockData, lockFile) {
   const pkgList = [];
-  if (!conanData) {
-    return pkgList;
+  const dependencies = {};
+  const parentComponentDependencies = [];
+  if (!colliderLockData) {
+    return { pkgList, dependencies, parentComponentDependencies };
   }
-  let scope = "required";
-  conanData.split("\n").forEach((l) => {
-    l = l.replace("\r", "");
-    if (l.includes("[build_requires]")) {
-      scope = "optional";
+  let parsedLockFile;
+  try {
+    parsedLockFile = JSON.parse(colliderLockData);
+  } catch {
+    return { pkgList, dependencies, parentComponentDependencies };
+  }
+  const addedBomRefs = new Set();
+  const directDependencies = parsedLockFile.dependencies || {};
+  const packages = parsedLockFile.packages || {};
+  for (const [name, pkgData] of Object.entries(directDependencies)) {
+    const component = buildColliderComponent(name, pkgData, lockFile, "direct");
+    if (!component) {
+      continue;
     }
-    if (l.includes("[requires]")) {
-      scope = "required";
+    if (!addedBomRefs.has(component["bom-ref"])) {
+      pkgList.push(component);
+      addedBomRefs.add(component["bom-ref"]);
     }
-
-    // The line must start with sequence non-whitespace characters, followed by a slash,
-    // followed by at least one more non-whitespace character.
-    // Provides a heuristic for locating Conan package references inside conanfile.txt files.
-    if (l.match(/^[^\s\/]+\/\S+/)) {
-      const [purl, name, version] =
-        mapConanPkgRefToPurlStringAndNameAndVersion(l);
-      if (purl !== null) {
-        pkgList.push({
-          name,
-          version,
-          purl,
-          "bom-ref": decodeURIComponent(purl),
-          scope,
-        });
-      }
+    if (!parentComponentDependencies.includes(component["bom-ref"])) {
+      parentComponentDependencies.push(component["bom-ref"]);
     }
-  });
-  return pkgList;
+    if (!(component["bom-ref"] in dependencies)) {
+      dependencies[component["bom-ref"]] = [];
+    }
+  }
+  for (const [name, pkgData] of Object.entries(packages)) {
+    const component = buildColliderComponent(
+      name,
+      pkgData,
+      lockFile,
+      "transitive",
+    );
+    if (!component || addedBomRefs.has(component["bom-ref"])) {
+      continue;
+    }
+    pkgList.push(component);
+    addedBomRefs.add(component["bom-ref"]);
+    if (!(component["bom-ref"] in dependencies)) {
+      dependencies[component["bom-ref"]] = [];
+    }
+  }
+  return { pkgList, dependencies, parentComponentDependencies };
 }
 
 /**
@@ -12800,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];
@@ -12808,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();
@@ -14750,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) {
@@ -14785,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({
@@ -14820,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.
  *
@@ -16286,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 {
@@ -16294,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;
 }
@@ -17175,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 {
@@ -17184,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) {
@@ -17192,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;
@@ -18363,6 +20436,92 @@ export function parsePackageJsonName(name) {
   return returnObject;
 }
 
+/**
+ * Collect bom-refs from metadata.tools entries.
+ *
+ * @param {Object[]|Object} tools CycloneDX metadata.tools section
+ * @param {Function} predicate Optional filter function
+ * @returns {string[]} Unique tool bom-refs
+ */
+export function extractToolRefs(tools, predicate) {
+  if (!tools) {
+    return [];
+  }
+  const toolRefs = new Set();
+  const toolList = Array.isArray(tools)
+    ? tools
+    : [...(tools.components || []), ...(tools.services || [])];
+  for (const tool of toolList) {
+    let toolRef = tool?.["bom-ref"];
+    if (!toolRef && tool?.purl) {
+      toolRef = decodeURIComponent(tool.purl);
+    }
+    if (!toolRef && tool?.name) {
+      try {
+        toolRef = new PackageURL(
+          "generic",
+          tool.group || tool.publisher || tool.manufacturer?.name || undefined,
+          tool.name,
+          tool.version || undefined,
+          null,
+          null,
+        ).toString();
+      } catch (_err) {
+        thoughtLog("Unable to derive bom-ref for external tool", {
+          group: tool.group,
+          manufacturer: tool.manufacturer?.name,
+          name: tool.name,
+          publisher: tool.publisher,
+          version: tool.version,
+        });
+        toolRef = undefined;
+      }
+    }
+    if (!toolRef) {
+      continue;
+    }
+    if (!tool["bom-ref"]) {
+      tool["bom-ref"] = toolRef;
+    }
+    if (predicate && !predicate(tool)) {
+      continue;
+    }
+    toolRefs.add(toolRef);
+  }
+  return Array.from(toolRefs);
+}
+
+/**
+ * Attach evidence.identity.tools references to the supplied subjects.
+ *
+ * @param {Object|Object[]} subjects Component or service objects
+ * @param {string[]} toolRefs Tool bom-refs
+ * @returns {Object|Object[]} The same mutated subject(s)
+ */
+export function attachIdentityTools(subjects, toolRefs) {
+  if (!subjects || !toolRefs?.length) {
+    return subjects;
+  }
+  const uniqueToolRefs = Array.from(new Set(toolRefs.filter(Boolean)));
+  if (!uniqueToolRefs.length) {
+    return subjects;
+  }
+  const subjectList = Array.isArray(subjects) ? subjects : [subjects];
+  for (const subject of subjectList) {
+    const identities = Array.isArray(subject?.evidence?.identity)
+      ? subject.evidence.identity
+      : subject?.evidence?.identity
+        ? [subject.evidence.identity]
+        : [];
+    for (const identity of identities) {
+      identity.tools = Array.from(
+        new Set([...(identity.tools || []), ...uniqueToolRefs]),
+      );
+    }
+  }
+  return subjects;
+}
+
 /**
  * Method to add occurrence evidence for components based on import statements. Currently useful for js
  *
@@ -18459,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 || []) {
@@ -19693,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(", "),
@@ -19708,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(", "),
@@ -19946,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;
 }
 
@@ -19954,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 [];
   }
-  let executables = [];
+  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}",
     "[",
@@ -19976,12 +22151,64 @@ export function collectExecutables(basePath, binPaths) {
         follow: true,
         ignore: ignoreList,
       });
-      executables = executables.concat(files);
+      for (const file of files) {
+        let resolvedFile = file;
+        try {
+          resolvedFile = relative(basePath, realpathSync(join(basePath, file)));
+          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);
+        }
+      }
     } catch (_err) {
       // ignore
     }
   }
-  return Array.from(new Set(executables)).sort();
+  return Array.from(executablesByResolvedPath.values()).sort();
+}
+
+function shouldPreferUsrMergedExecutablePath(file, existingFile) {
+  if (!existingFile) {
+    return true;
+  }
+  const fileUsesUsrPrefix = file.startsWith("usr/");
+  const existingFileUsesUsrPrefix = existingFile.startsWith("usr/");
+  if (fileUsesUsrPrefix !== existingFileUsesUsrPrefix) {
+    return fileUsesUsrPrefix;
+  }
+  return file < existingFile;
 }
 
 /**
@@ -19991,6 +22218,7 @@ export function collectExecutables(basePath, binPaths) {
  * @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
  */
@@ -19999,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}",
   ];
@@ -20035,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
     }
@@ -20169,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
 
@@ -20208,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);
 }
 
 /**