@cyclonedx/cdxgen 12.1.4 → 12.2.0

package/lib/managers/binary.js

@@ -1,5 +1,4 @@
 import {
-  existsSync,
   lstatSync,
   mkdtempSync,
   readFileSync,
@@ -31,6 +30,7 @@ import {
   isSpdxLicenseExpression,
   multiChecksumFile,
   retrieveCdxgenPluginVersion,
+  safeExistsSync,
   safeMkdirSync,
   safeSpawnSync,
 } from "../helpers/utils.js";
@@ -82,8 +82,8 @@ let extraNMBinPath;
 // Is there a non-empty local plugins directory
 if (
   !CDXGEN_PLUGINS_DIR &&
-  existsSync(join(dirName, "plugins")) &&
-  existsSync(join(dirName, "plugins", "trivy"))
+  safeExistsSync(join(dirName, "plugins")) &&
+  safeExistsSync(join(dirName, "plugins", "trivy"))
 ) {
   CDXGEN_PLUGINS_DIR = join(dirName, "plugins");
 }
@@ -91,7 +91,7 @@ if (
 // Is there a non-empty local node_modules directory
 if (
   !CDXGEN_PLUGINS_DIR &&
-  existsSync(
+  safeExistsSync(
     join(
       dirName,
       "node_modules",
@@ -100,7 +100,7 @@ if (
       "plugins",
     ),
   ) &&
-  existsSync(
+  safeExistsSync(
     join(
       dirName,
       "node_modules",
@@ -118,7 +118,7 @@ if (
     `cdxgen-plugins-bin${pluginsBinSuffix}`,
     "plugins",
   );
-  if (existsSync(join(dirName, "node_modules", ".bin"))) {
+  if (safeExistsSync(join(dirName, "node_modules", ".bin"))) {
     extraNMBinPath = join(dirName, "node_modules", ".bin");
   }
 }
@@ -168,7 +168,7 @@ if (!CDXGEN_PLUGINS_DIR) {
       `cdxgen-plugins-bin${pluginsBinSuffix}`,
       "plugins",
     );
-    if (existsSync(join(tmpA[0], "node_modules", ".bin"))) {
+    if (safeExistsSync(join(tmpA[0], "node_modules", ".bin"))) {
       extraNMBinPath = join(tmpA[0], "node_modules", ".bin");
     }
   } else if (dirName.includes(join(".pnpm", "@cyclonedx+cdxgen"))) {
@@ -183,7 +183,7 @@ if (!CDXGEN_PLUGINS_DIR) {
       `cdxgen-plugins-bin${pluginsBinSuffix}`,
       "plugins",
     );
-    if (existsSync(join(tmpA[0], ".bin"))) {
+    if (safeExistsSync(join(tmpA[0], ".bin"))) {
       extraNMBinPath = join(tmpA[0], ".bin");
     }
   } else if (dirName.includes(join("caxa", "applications"))) {
@@ -201,12 +201,12 @@ if (!CDXGEN_PLUGINS_DIR) {
     extraNMBinPath = join(dirName, "node_modules", ".bin");
   }
   // Set the plugins directory
-  if (globalPlugins && existsSync(globalPlugins)) {
+  if (globalPlugins && safeExistsSync(globalPlugins)) {
     CDXGEN_PLUGINS_DIR = globalPlugins;
     if (DEBUG_MODE) {
       console.log("Found global plugins", CDXGEN_PLUGINS_DIR);
     }
-  } else if (altGlobalPlugins && existsSync(altGlobalPlugins)) {
+  } else if (altGlobalPlugins && safeExistsSync(altGlobalPlugins)) {
     CDXGEN_PLUGINS_DIR = altGlobalPlugins;
     // To help detect bin commands such as atom, astgen, etc, we need to set this to the PATH variable.
     if (DEBUG_MODE) {
@@ -227,7 +227,7 @@ if (!CDXGEN_PLUGINS_DIR) {
   CDXGEN_PLUGINS_DIR = "";
 }
 let TRIVY_BIN = process.env.TRIVY_CMD;
-if (existsSync(join(CDXGEN_PLUGINS_DIR, "trivy"))) {
+if (safeExistsSync(join(CDXGEN_PLUGINS_DIR, "trivy"))) {
   TRIVY_BIN = join(
     CDXGEN_PLUGINS_DIR,
     "trivy",
@@ -235,7 +235,7 @@ if (existsSync(join(CDXGEN_PLUGINS_DIR, "trivy"))) {
   );
 }
 let CARGO_AUDITABLE_BIN = process.env.CARGO_AUDITABLE_CMD;
-if (existsSync(join(CDXGEN_PLUGINS_DIR, "cargo-auditable"))) {
+if (safeExistsSync(join(CDXGEN_PLUGINS_DIR, "cargo-auditable"))) {
   CARGO_AUDITABLE_BIN = join(
     CDXGEN_PLUGINS_DIR,
     "cargo-auditable",
@@ -243,7 +243,7 @@ if (existsSync(join(CDXGEN_PLUGINS_DIR, "cargo-auditable"))) {
   );
 }
 let OSQUERY_BIN = process.env.OSQUERY_CMD;
-if (existsSync(join(CDXGEN_PLUGINS_DIR, "osquery"))) {
+if (safeExistsSync(join(CDXGEN_PLUGINS_DIR, "osquery"))) {
   OSQUERY_BIN = join(
     CDXGEN_PLUGINS_DIR,
     "osquery",
@@ -255,7 +255,7 @@ if (existsSync(join(CDXGEN_PLUGINS_DIR, "osquery"))) {
   }
 }
 let DOSAI_BIN = process.env.DOSAI_CMD;
-if (existsSync(join(CDXGEN_PLUGINS_DIR, "dosai"))) {
+if (safeExistsSync(join(CDXGEN_PLUGINS_DIR, "dosai"))) {
   DOSAI_BIN = join(
     CDXGEN_PLUGINS_DIR,
     "dosai",
@@ -268,7 +268,7 @@ const BLINT_BIN = process.env.BLINT_CMD || "blint";
 
 // sourcekitten
 let SOURCEKITTEN_BIN = process.env.SOURCEKITTEN_CMD;
-if (existsSync(join(CDXGEN_PLUGINS_DIR, "sourcekitten"))) {
+if (safeExistsSync(join(CDXGEN_PLUGINS_DIR, "sourcekitten"))) {
   SOURCEKITTEN_BIN = join(CDXGEN_PLUGINS_DIR, "sourcekitten", "sourcekitten");
 }
 
@@ -476,7 +476,7 @@ export async function getOSPackages(src, imageConfig) {
     } catch (_err) {
       // ignore errors
     }
-    if (existsSync(src)) {
+    if (safeExistsSync(src)) {
       imageType = "rootfs";
     }
     const tempDir = mkdtempSync(join(getTmpDir(), "trivy-cdxgen-"));
@@ -513,7 +513,7 @@ export async function getOSPackages(src, imageConfig) {
         console.error(result.stdout, result.stderr);
       }
     }
-    if (existsSync(bomJsonFile)) {
+    if (safeExistsSync(bomJsonFile)) {
       let tmpBom = {};
       try {
         tmpBom = JSON.parse(
@@ -536,9 +536,9 @@ export async function getOSPackages(src, imageConfig) {
       const osReleaseData = {};
       let osReleaseFile;
       // Let's try to read the os-release file from various locations
-      if (existsSync(join(src, "etc", "os-release"))) {
+      if (safeExistsSync(join(src, "etc", "os-release"))) {
         osReleaseFile = join(src, "etc", "os-release");
-      } else if (existsSync(join(src, "usr", "lib", "os-release"))) {
+      } else if (safeExistsSync(join(src, "usr", "lib", "os-release"))) {
         osReleaseFile = join(src, "usr", "lib", "os-release");
       }
       if (osReleaseFile) {

package/lib/managers/docker.js

@@ -71,7 +71,14 @@ if (
   isContainerd = true;
 }
 
-// Taken from https://github.com/isaacs/node-tar/blob/main/src/strip-absolute-path.ts
+/**
+ * Strip absolute path prefixes from a path string, handling both Unix and
+ * Windows paths (including UNC and extended-length paths such as //?/C:/).
+ * Taken from https://github.com/isaacs/node-tar/blob/main/src/strip-absolute-path.ts
+ *
+ * @param {string} path The path to strip
+ * @returns {string} The path with its absolute root removed
+ */
 export const stripAbsolutePath = (path) => {
   // This appears to be a most frequent case, so let's return quickly.
   if (path === "/") {
@@ -165,6 +172,18 @@ export function detectRancherDesktop() {
 // Cache the registry auth keys
 const registry_auth_keys = {};
 const REQUEST_TIMEOUT_SECS = 60000;
+/**
+ * Build a `got` options object for Docker / registry API requests. Resolves
+ * authentication headers by consulting (in order) the DOCKER_AUTH_CONFIG
+ * environment variable, DOCKER_USER/DOCKER_PASSWORD/DOCKER_EMAIL environment
+ * variables, hardcoded tokens in ~/.docker/config.json, credential helpers
+ * listed in credHelpers/credsStore, and finally TLS certificate files pointed
+ * to by DOCKER_CERT_PATH.
+ *
+ * @param {string} [forRegistry] Registry hostname (e.g. "registry-1.docker.io").
+ *   Defaults to DOCKER_SERVER_ADDRESS env var or "docker.io".
+ * @returns {Object} Options object suitable for passing to `got`
+ */
 const getDefaultOptions = (forRegistry) => {
   let authTokenSet = false;
   if (!forRegistry) {
@@ -358,6 +377,20 @@ const getDefaultOptions = (forRegistry) => {
   return opts;
 };
 
+/**
+ * Establish (or reuse) a `got` client connected to the local Docker or Podman
+ * daemon. Tries multiple socket / URL candidates in order: the default Docker
+ * socket, the rootless Docker socket, the Windows TCP endpoint, the rootless
+ * Podman socket, and the root Podman socket. Sets the module-level flags
+ * `isPodman`, `isPodmanRootless`, `isDockerRootless`, and `isWinLocalTLS` as a
+ * side-effect. Returns `undefined` when containerd / nerdctl is in use or no
+ * daemon could be reached.
+ *
+ * @param {Object} options Additional `got` options to merge into the connection
+ * @param {string} [forRegistry] Registry hostname forwarded to `getDefaultOptions`
+ * @returns {Promise<import("got").Got|undefined>} A `got` instance bound to the
+ *   daemon base URL, or `undefined`
+ */
 export const getConnection = async (options, forRegistry) => {
   if (isContainerd || isNerdctl) {
     return undefined;
@@ -461,6 +494,17 @@ export const getConnection = async (options, forRegistry) => {
   return dockerConn;
 };
 
+/**
+ * Send a single HTTP request to the Docker / Podman daemon via the `got`
+ * client returned by {@link getConnection}. GET requests are parsed as JSON;
+ * all other methods receive a Buffer response body.
+ *
+ * @param {string} path API path relative to the daemon base URL (e.g. "images/ubuntu:latest/json")
+ * @param {string} method HTTP method (e.g. "GET", "POST", "DELETE")
+ * @param {string} [forRegistry] Registry hostname forwarded to `getDefaultOptions` for auth headers
+ * @returns {Promise<Object|Buffer|undefined>} Parsed JSON object for GET
+ *   requests, raw Buffer for other methods, or `undefined` if no client is available
+ */
 export const makeRequest = async (path, method, forRegistry) => {
   const client = await getConnection({}, forRegistry);
   if (!client) {
@@ -815,6 +859,14 @@ function tarFilter(path, entry) {
   );
 }
 
+/**
+ * Suppress low-signal tar warnings (TAR_ENTRY_INFO, TAR_LONGLINK) that are
+ * expected when extracting container image layers. All other warning codes are
+ * logged when DEBUG_MODE is enabled.
+ *
+ * @param {string} code Tar warning code (e.g. "TAR_ENTRY_INFO")
+ * @param {string} message Human-readable warning message
+ */
 function handleTarWarning(code, message) {
   if (code === "TAR_ENTRY_INFO" || code === "TAR_LONGLINK") {
     return;
@@ -885,6 +937,18 @@ const EXTRACT_EXCLUDE_TYPES = new Set([
   "Link",
 ]);
 
+/**
+ * Extract a container image tar archive into a destination directory.
+ * Applies path sanitisation, ownership/permission preservation settings, and
+ * an entry filter to skip problematic files and device nodes. Handles common
+ * tar errors gracefully, logging only unexpected ones.
+ *
+ * @param {string} fullImageName Path to the source tar archive
+ * @param {string} dir Destination directory to extract into
+ * @param {Object} options CLI options (uses `options.failOnError`)
+ * @returns {Promise<boolean>} `true` on success, `false` when the archive is
+ *   empty or a non-fatal error was encountered
+ */
 export const extractTar = async (fullImageName, dir, options) => {
   try {
     await stream.pipeline(
@@ -1016,6 +1080,21 @@ export const exportArchive = async (fullImageName, options = {}) => {
   return undefined;
 };
 
+/**
+ * Parse a Docker/containerd manifest file and extract all image layers into a
+ * single merged directory. Resolves the last layer's config to determine the
+ * container's working directory, and builds the package path list for
+ * subsequent analysis.
+ *
+ * @param {string} manifestFile Path to the manifest.json (or index.json) file
+ * @param {Object} localData Local image inspect data (e.g. from `docker inspect`)
+ * @param {string} tempDir Temporary directory that holds the unpacked image
+ * @param {string} allLayersExplodedDir Directory where all layers are merged
+ * @param {Object} options CLI options (uses `options.failOnError`)
+ * @returns {Promise<Object>} Export data object containing `manifest`,
+ *   `allLayersDir`, `allLayersExplodedDir`, `lastLayerConfig`,
+ *   `lastWorkingDir`, `binPaths`, and `pkgPathList`
+ */
 export const extractFromManifest = async (
   manifestFile,
   localData,
@@ -1414,10 +1493,29 @@ export const getPkgPathList = (exportData, lastWorkingDir) => {
   return pathList;
 };
 
+/**
+ * Remove a container image from the local Docker / Podman daemon.
+ *
+ * @param {string} fullImageName Full image name including tag or digest (e.g. "ubuntu:22.04")
+ * @param {boolean} [force=false] When `true`, force-remove the image even if it is in use
+ * @returns {Promise<Buffer|undefined>} Raw response buffer from the daemon, or
+ *   `undefined` if no daemon connection is available
+ */
 export const removeImage = async (fullImageName, force = false) => {
   return await makeRequest(`images/${fullImageName}?force=${force}`, "DELETE");
 };
 
+/**
+ * Retrieve a base64url-encoded authentication token for a registry server by
+ * invoking the `docker-credential-<exeSuffix>` credential helper binary.
+ * Results are cached in `registry_auth_keys` to avoid redundant subprocess
+ * calls.
+ *
+ * @param {string} exeSuffix Credential helper name suffix (e.g. "osxkeychain", "wincred", "pass")
+ * @param {string} serverAddress Registry server address (e.g. "https://index.docker.io/v1/")
+ * @returns {string|undefined} Base64url-encoded JSON auth token, or `undefined`
+ *   if the helper is unavailable or returns an error
+ */
 export const getCredsFromHelper = (exeSuffix, serverAddress) => {
   if (registry_auth_keys[serverAddress]) {
     return registry_auth_keys[serverAddress];
@@ -1460,6 +1558,15 @@ export const getCredsFromHelper = (exeSuffix, serverAddress) => {
   return undefined;
 };
 
+/**
+ * Append skipped source-file entries to the `SrcFile` properties of matching
+ * components. A component matches when its `oci:SrcImage` property value
+ * equals the skipped image's `image` field and the source file path is not
+ * already listed.
+ *
+ * @param {Array<{image: string, src: string}>} skippedImageSrcs List of skipped image/source pairs
+ * @param {Array<Object>} components CycloneDX component objects to update in place
+ */
 export const addSkippedSrcFiles = (skippedImageSrcs, components) => {
   for (const skippedImage of skippedImageSrcs) {
     for (const co of components) {

package/lib/managers/oci.js

@@ -9,6 +9,16 @@ import {
   safeSpawnSync,
 } from "../helpers/utils.js";
 
+/**
+ * Retrieves a CycloneDX BOM attached to an OCI image using the `oras` CLI tool.
+ * Discovers SBOM attachments via `oras discover`, pulls the first matching
+ * artifact, and returns the parsed BOM JSON. Retries automatically with a
+ * platform-specific manifest when the initial platform-agnostic discovery fails.
+ *
+ * @param {string} image OCI image reference (e.g. `"registry.example.com/org/app:tag"`)
+ * @param {string} [platform] OCI platform string (e.g. `"linux/amd64"`); detected automatically when omitted
+ * @returns {Object|undefined} Parsed CycloneDX BOM JSON object, or `undefined` if not found
+ */
 export function getBomWithOras(image, platform = undefined) {
   const platformArch = arch() === "arm64" ? "arm64" : "amd64";
   let parameters = [

package/lib/managers/piptree.js

@@ -4,16 +4,10 @@
  *
  * We use the internal pip api to construct the dependency tree for modern python + pip environments
  */
-import {
-  existsSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { delimiter, join } from "node:path";
 
-import { getTmpDir, safeSpawnSync } from "../helpers/utils.js";
+import { getTmpDir, safeExistsSync, safeSpawnSync } from "../helpers/utils.js";
 
 const PIP_TREE_PLUGIN_CONTENT = `
 import importlib.metadata as importlib_metadata
@@ -125,7 +119,7 @@ def get_installed_with_extras():
         name_version_cache[name] = version
         name_dist_cache[name] = dist
     for dist in importlib_metadata.distributions():
-        name = dist.metadata['Name']
+        name = dist.metadata['Name'] or ""
         version = dist.version or ""
         # extras this package defines:
         extras = dist.metadata.get_all('Provides-Extra') or []
@@ -254,7 +248,7 @@ export const getTreeWithPlugin = (env, python_cmd, basePath) => {
       console.log(result.stdout, result.stderr);
     }
   }
-  if (existsSync(pipTreeJson)) {
+  if (safeExistsSync(pipTreeJson)) {
     tree = JSON.parse(
       readFileSync(pipTreeJson, {
         encoding: "utf-8",

package/lib/parsers/npmrc.js

@@ -0,0 +1,92 @@
+export const DEFAULT_NPMRC_BLOCKLIST = new Set([
+  "git",
+  "script-shell",
+  "shell",
+  "call",
+  "browser",
+  "replace-registry-host",
+  "node-gyp",
+  "node-options",
+  "bin-links",
+  "install-links",
+  "location",
+  "userconfig",
+  "globalconfig",
+  "foreground-scripts",
+  "rebuild-bundle",
+]);
+
+/**
+ * Parse .npmrc content into a plain key-value object.
+ *
+ * @param {string} content - Raw .npmrc file content
+ * @returns {Object} Parsed key-value pairs
+ */
+export function parseNpmrc(content) {
+  const result = {};
+  const lines = content.split(/\r\n|\r|\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#") || line.startsWith(";")) {
+      continue;
+    }
+    const eqIndex = line.indexOf("=");
+    if (eqIndex === -1) continue;
+    let key = line.substring(0, eqIndex).trim();
+    let value = line.substring(eqIndex + 1).trim();
+    if (!key) continue;
+    const isArray = key.endsWith("[]");
+    if (isArray) {
+      key = key.slice(0, -2);
+    }
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (isArray) {
+      if (!result[key]) result[key] = [];
+      result[key].push(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Extract npm/pnpm configuration values from environment variables.
+ * See https://docs.npmjs.com/cli/v11/using-npm/config
+ *
+ * npm uses the NPM_CONFIG_ prefix for env var config:
+ * - Dashes become underscores: --allow-same-version → npm_config_allow_same_version
+ * - Case-insensitive prefix matching: NPM_CONFIG_FOO = npm_config_foo
+ * - Simple keys are lowercased; scoped/URI keys preserve case
+ * - Boolean flags without values are treated as true
+ *
+ * pnpm v11+ uses the PNPM_CONFIG_ prefix instead of NPM_CONFIG_ for pnpm-specific settings.
+ *   Both prefixes are supported; pnpm_config_* takes precedence over npm_config_* for the same key.
+ *   See https://pnpm.io/next/npmrc
+ * @param {Object} env - Environment variables object (defaults to process.env)
+ * @returns {Object} Parsed npm config key-value pairs
+ */
+export function parseNpmrcFromEnv(env = process.env) {
+  const result = {};
+  const NPM_PREFIX = "npm_config_";
+  const PNPM_PREFIX = "pnpm_config_";
+  for (const prefix of [NPM_PREFIX, PNPM_PREFIX]) {
+    for (const [fullKey, value] of Object.entries(env)) {
+      if (!fullKey.toLowerCase().startsWith(prefix)) {
+        continue;
+      }
+      let configKey = fullKey.slice(prefix.length);
+      if (!configKey) continue;
+      if (!configKey.startsWith("//") && !configKey.startsWith("@")) {
+        configKey = configKey.toLowerCase();
+      }
+      result[configKey] = value === "" || value === undefined ? "true" : value;
+    }
+  }
+  return result;
+}