@cdxgen/cdxgen 13.2.0 → 13.3.0

package/lib/cli/bomAssembly.js

@@ -25,7 +25,10 @@ import {
   CDXGEN_VERSION,
   frameworksList,
 } from "../core/state.js";
-import { isPkgTypeOnlyImport } from "../ecosystems/npmutils.js";
+import {
+  isPkgTypeOnlyImport,
+  setNpmCleanedVersionProperty,
+} from "../ecosystems/npmutils.js";
 import { parsePackageJsonName } from "../ecosystems/parsers-js.js";
 import {
   AI_INSTRUCTION_FILE_KINDS,
@@ -50,8 +53,7 @@ import {
 import { enrichComponentWithMcpMetadata } from "../inventory/mcp.js";
 import {
   applyPurl,
-  encodeForPurl,
-  isValidPurl,
+  canonicalPurlFromLooseString,
   npmPurl,
   tryBuildPurl,
 } from "../inventory/purl.js";
@@ -182,6 +184,31 @@ export const determineParentComponent = (options) => {
   return parentComponent;
 };
 
+/**
+ * Tells whether a `--project-name`/`--project-version` override names the very
+ * project the generator detected, rather than a larger project containing it.
+ *
+ * The override is typed `application` because it can name anything. When its
+ * name, group, and version match the detected parent, the two describe the same
+ * project, and the detected parent is the better description of it: it carries
+ * the ecosystem purl and the manifest metadata. Treating it as a subproject
+ * would list the project as a dependency of itself under a second purl.
+ *
+ * @param {object|undefined} overrideParent Parent built from the options
+ * @param {object|undefined} detectedParent Parent the generator derived
+ * @returns {boolean} true when both describe the same project
+ */
+const overrideNamesDetectedParent = (overrideParent, detectedParent) => {
+  if (!overrideParent || !detectedParent?.purl) {
+    return false;
+  }
+  return (
+    overrideParent.name === detectedParent.name &&
+    (overrideParent.group || "") === (detectedParent.group || "") &&
+    `${overrideParent.version}` === `${detectedParent.version}`
+  );
+};
+
 /**
  * Re-anchor a dependency graph onto a caller-supplied parent component.
  *
@@ -338,7 +365,8 @@ export const componentToSimpleFullName = (comp) => {
 /**
  * Strips transient keys (`evidence`, `_integrity`, `license`, `qualifiers`,
  * `repository`, `homepage`) from a parent component while preserving licenses
- * and external references (bug #1519).
+ * and external references (bug #1519). External references whose URL is not a
+ * valid IRI reference are dropped.
  *
  * @param {object} comp Parent component to clean in place
  * @returns {object} The cleaned parent component
@@ -356,10 +384,15 @@ export const cleanParentComponent = (comp) => {
   }
   delete comp.license;
   delete comp.qualifiers;
-  if (comp.repository || comp.homepage) {
+  // Components get their references validated in listComponents. The parent
+  // skips that conversion, so validate here too: an unusable URL taken from a
+  // manifest must not make the whole document invalid.
+  if (comp.repository || comp.homepage || comp.externalReferences?.length) {
     const externalReferences = addExternalReferences(comp);
     if (externalReferences?.length) {
       comp.externalReferences = externalReferences;
+    } else {
+      delete comp.externalReferences;
     }
   }
   delete comp.repository;
@@ -454,12 +487,18 @@ export function addMetadata(parentComponent = {}, options = {}, context = {}) {
       // name-based bom-ref, and blindly copying that here manufactured invalid
       // purls such as `"purl": "swift-smoke"`. CycloneDX requires `purl` to be
       // a valid Package URL when present, so absent is the only correct answer.
+      // A bom-ref holds the decoded purl (`pkg:npm/app@1.0.0+build`), so it is
+      // split on its separators and rebuilt rather than escaped wholesale,
+      // which would also escape the `@` before the version.
       if (!parentComponent["purl"] && parentComponent["bom-ref"]) {
-        const candidate = encodeForPurl(parentComponent["bom-ref"]);
-        if (isValidPurl(candidate)) {
+        const candidate = canonicalPurlFromLooseString(
+          parentComponent["bom-ref"],
+        );
+        if (candidate) {
           parentComponent["purl"] = candidate;
         }
       }
+      setNpmCleanedVersionProperty(parentComponent);
     }
     if (parentComponent?.components) {
       parentComponent.components = listComponents(
@@ -841,6 +880,7 @@ export function addExternalReferences(opkg) {
     }
   }
   return externalReferences
+    .filter((reference) => typeof reference?.url === "string")
     .map((reference) => ({ ...reference, url: reference.url.trim() }))
     .filter((reference) => isValidIriReference(reference.url));
 }
@@ -1014,13 +1054,16 @@ export function addComponent(
     let purl = pkg.purl;
     if (!purl && ptype) {
       try {
+        // Raw values: cdx-purl escapes each component itself, so escaping
+        // them here first turned `@scope` into `%2540scope` and
+        // `libstdc++6` into `libstdc%252B%252B6`.
         purl = new Purl({
           type: ptype,
-          namespace: encodeForPurl(group) || null,
-          name: encodeForPurl(name),
+          namespace: group || null,
+          name,
           version: version || null,
           qualifiers: pkg.qualifiers || null,
-          subpath: encodeForPurl(pkg.subpath) || null,
+          subpath: pkg.subpath || null,
         });
       } catch {
         // purl construction may fail for types requiring a namespace (maven,
@@ -1071,9 +1114,10 @@ export function addComponent(
         } else {
           compScope = "required";
         }
-      } else if (impPkgs.length && compScope !== "excluded") {
-        compScope = "optional";
       }
+      // A package missing from the imports keeps its scope. Usage analysis
+      // only promotes: the ecosystem passes have already scoped the package
+      // list, and a missing import is not evidence that a package is optional.
     }
     let component = {
       author,
@@ -1089,6 +1133,11 @@ export function addComponent(
       purl: purlString,
       externalReferences: addExternalReferences(pkg),
     };
+    // A CPE from the collector (caxa records one for the bundled Node.js
+    // runtime) is how NVD-based scanners match the component.
+    if (typeof pkg.cpe === "string" && pkg.cpe.length) {
+      component.cpe = pkg.cpe;
+    }
     if (options.specVersion >= 1.5) {
       component.pedigree = pkg.pedigree || undefined;
     }
@@ -1102,6 +1151,13 @@ export function addComponent(
       // than bundled with the product. The schema defaults it to false, so it
       // is only worth emitting when true.
       component.isExternal = pkg.isExternal ? true : undefined;
+      // A range describes an external dependency named without a resolved
+      // version, such as the Ruby a gem requires. The schema allows it only
+      // on an external component, and never next to a version.
+      component.versionRange =
+        pkg.isExternal && !pkg.version
+          ? pkg.versionRange || undefined
+          : undefined;
     }
     component["type"] = determinePackageType(pkg);
     // `version` is optional in every spec version cdxgen emits. An empty string
@@ -1131,9 +1187,16 @@ export function addComponent(
     if (options.specVersion >= 1.6 && component.author) {
       const authorsList = [];
       for (const aauthor of component.author.split(",")) {
-        authorsList.push({ name: aauthor });
+        // Registries hand out comma separated lists without a consistent
+        // spacing, so `A, B` and `A,B` must produce the same names
+        const name = aauthor.trim();
+        if (name.length) {
+          authorsList.push({ name });
+        }
+      }
+      if (authorsList.length) {
+        component.authors = authorsList;
       }
-      component.authors = authorsList;
       delete component.author;
     }
     // Downgrade authors section for < 1.5 :(
@@ -1169,6 +1232,7 @@ export function addComponent(
     if (pkg.properties?.length) {
       component.properties = pkg.properties;
     }
+    setNpmCleanedVersionProperty(component);
     if (isTypeOnlyPkg) {
       component.properties = component.properties || [];
       if (
@@ -1285,6 +1349,25 @@ export function determinePackageType(pkg) {
       ) {
         return "library";
       }
+      // A gem is a framework only when the curated list names that very gem:
+      // the prefix matches below took rails-html-sanitizer and sinatra-contrib
+      // for their frameworks, and the bare words meant for other ecosystems
+      // turned childprocess ("chi") and jquery-rails ("jquery") into
+      // frameworks. Any other gem is a library, unless it ships executables,
+      // which makes it an application (discussions 4405 and 4408). A
+      // description or keyword that merely mentions a framework is no evidence
+      // of one: every gem whose summary says "tracing framework" would
+      // otherwise become a framework component.
+      if (purl.type === "gem") {
+        if (frameworksList.all.includes(`pkg:gem/${purl.name}`)) {
+          return "framework";
+        }
+        const hasExecutables = pkg.properties?.some(
+          (prop) =>
+            prop.name === "cdx:gem:executables" && prop.value?.trim().length,
+        );
+        return hasExecutables ? "application" : "library";
+      }
       for (const cf of frameworksList.all) {
         if (
           pkg.purl.startsWith(cf) ||
@@ -1466,7 +1549,14 @@ export const buildBomNSData = (options, pkgInfo, ptype, context) => {
   }
   const nsMapping = context.nsMapping || {};
   const services = context.services || [];
-  const overrideParent = determineParentComponent(options);
+  let overrideParent = determineParentComponent(options);
+  // A caller-supplied parentComponent is always honoured as given
+  if (
+    overrideParent !== options.parentComponent &&
+    overrideNamesDetectedParent(overrideParent, context.parentComponent)
+  ) {
+    overrideParent = undefined;
+  }
   const parentComponent = overrideParent || context.parentComponent;
   const metadata = addMetadata(parentComponent, options, context);
   const components = listComponents(options, allImports, pkgInfo, ptype);

package/lib/cli/cliOptions.js

@@ -15,6 +15,10 @@ import { join, resolve } from "node:path";
 
 import { isSecureMode, readEnvironmentVariable } from "../core/activity.js";
 import { PROJECT_TYPE_ALIASES } from "../core/env.js";
+import {
+  METADATA_PROPERTY_CONFIG_KEYS,
+  parseMetadataProperties,
+} from "../core/metadataProperties.js";
 import {
   DEFAULT_CDX_SPEC_VERSION,
   normalizeCycloneDxComponentTypeFilter,
@@ -120,6 +124,80 @@ export function isUserProvided(value, yaDefault) {
   return value !== undefined && value !== yaDefault;
 }
 
+/**
+ * Combine the custom metadata properties of every source (discussion 4391):
+ * the `--metadata-property` flag, the CDXGEN_METADATA_PROPERTY and
+ * CDXGEN_METADATA_PROPERTIES environment variables, and a config file's
+ * `metadata-property` or `metadataProperties` entry.
+ *
+ * yargs would let the highest-precedence source replace the others outright,
+ * so each is read on its own and they are merged instead. A name set by more
+ * than one source takes its values from the one that wins in the usual order
+ * — the command line, then the environment, then the config file — while a
+ * source may repeat a name for a multi-valued property.
+ *
+ * @param {object} args Parsed yargs argv
+ * @param {object} [context]
+ * @param {string[]} [context.argv] Raw command-line arguments, which tell a
+ *   flag on the command line from one yargs filled in from elsewhere
+ * @param {object} [context.projectConfig] The sanitized config file contents.
+ *   Without it, a programmatic caller's `args` are taken as the config.
+ * @returns {{name: string, value: string}[]} The merged properties
+ */
+export function resolveMetadataProperties(
+  args,
+  { argv = process.argv, projectConfig } = {},
+) {
+  const flagGiven = argv.some((argument) =>
+    ["--metadata-property", "--metadataProperty"].includes(
+      `${argument}`.split("=")[0],
+    ),
+  );
+  const fromConfig = projectConfig
+    ? METADATA_PROPERTY_CONFIG_KEYS.flatMap((key) =>
+        parseMetadataProperties(projectConfig[key]),
+      )
+    : flagGiven
+      ? []
+      : [
+          ...parseMetadataProperties(args?.metadataProperty),
+          ...parseMetadataProperties(args?.metadataProperties),
+        ];
+  const sources = [
+    flagGiven ? parseMetadataProperties(args?.metadataProperty) : [],
+    [
+      ...parseMetadataProperties(
+        readEnvironmentVariable("CDXGEN_METADATA_PROPERTY"),
+      ),
+      ...parseMetadataProperties(
+        readEnvironmentVariable("CDXGEN_METADATA_PROPERTIES"),
+      ),
+    ],
+    fromConfig,
+  ];
+  const properties = [];
+  const claimedNames = new Set();
+  for (const source of sources) {
+    const sourceNames = new Set();
+    for (const aprop of source) {
+      if (
+        claimedNames.has(aprop.name) ||
+        properties.some(
+          (prop) => prop.name === aprop.name && prop.value === aprop.value,
+        )
+      ) {
+        continue;
+      }
+      properties.push(aprop);
+      sourceNames.add(aprop.name);
+    }
+    for (const name of sourceNames) {
+      claimedNames.add(name);
+    }
+  }
+  return properties;
+}
+
 /**
  * Apply command-name-based defaults to the raw parsed args. When cdxgen is
  * invoked via a symlink or alias (e.g. `obom`, `cbom`, `spdxgen`, `aibom`),
@@ -162,6 +240,8 @@ export function applyCommandNameDefaults(args, invokedCommandName) {
  * @param {object} context
  * @param {string} context.filePath          Resolved source path
  * @param {boolean} context.isRemoteOrPurl   True when source is a URL or purl
+ * @param {string[]} [context.argv]          Raw command-line arguments
+ * @param {object} [context.projectConfig]   Sanitized config file contents
  * @returns {object} The initial options object
  */
 /**
@@ -221,8 +301,12 @@ function resolveIntrospectOption(args, argv) {
 
 export function buildInitialOptions(
   args,
-  { filePath, isRemoteOrPurl, argv = process.argv },
+  { filePath, isRemoteOrPurl, argv = process.argv, projectConfig },
 ) {
+  const metadataProperties = resolveMetadataProperties(args, {
+    argv,
+    projectConfig,
+  });
   const res = Object.assign({}, args, {
     projectType: args.type,
     multiProject: args.recurse,
@@ -235,6 +319,9 @@ export function buildInitialOptions(
     include: args.include || args.includeRegex,
     noIgnore: args.noIgnore,
     gitAiNotesRef: args.gitAiNotesRef || "refs/notes/ai",
+    metadataProperties: metadataProperties.length
+      ? metadataProperties
+      : undefined,
     // Introspection: the flag or the documented environment opt-in. An
     // explicit --no-introspect stays `false` and beats both, while an
     // unmentioned flag stays undefined so a profile can still enable it.
@@ -598,6 +685,9 @@ export function applyAdvancedOptions(options, context = {}) {
  *                                             passed `--spec-version`
  * @param {boolean} [context.isDryRun=false]   Dry-run mode
  * @param {boolean} [context.isSecureMode]     Secure mode
+ * @param {object} [context.projectConfig]     Sanitized config file contents,
+ *                                             whose metadata properties merge
+ *                                             with the other sources'
  * @returns {{ options: object, warnings: OptionsWarning[] }}
  */
 export function buildOptionsFromArgs(args, context) {
@@ -607,12 +697,14 @@ export function buildOptionsFromArgs(args, context) {
     isRemoteOrPurl,
     userSetSpecVersion,
     isDryRun = false,
+    projectConfig,
   } = context;
 
   const expandedArgs = applyCommandNameDefaults(args, invokedCommandName);
   const options = buildInitialOptions(expandedArgs, {
     filePath,
     isRemoteOrPurl,
+    projectConfig,
   });
   const phase3Warnings = applyPostConstructionOverrides(options, {
     invokedCommandName,

package/lib/cli/index.js

@@ -84,6 +84,7 @@ import {
   exportArchive,
   exportImage,
   getPkgPathList,
+  isImageReference,
   parseImageName,
 } from "../managers/docker.js";
 import {
@@ -1900,17 +1901,49 @@ export async function createDynamicBom(path, options) {
     blockExec: options.traceBlockExec,
     traceCrypto: options.traceCrypto,
     cbom: options.cbom,
+    proxyEgress: options.traceProxyEgress,
+    allowLoopback: options.traceAllowLoopback,
+    dryRun: options.traceDryRun,
+    policy: options.tracePolicy,
+    policyFile: options.tracePolicyFile,
+    blockInterpreters: options.traceBlockInterpreters,
+    denyPersistenceWrites: options.traceDenyPersistenceWrites,
+    privateTmp: options.tracePrivateTmp,
+    protectHome: options.traceProtectHome,
   };
 
-  const { components: pkgList, services: traceServices } =
-    await buildDynamicComponents(commandStr, workingDir, traceOptions);
+  const {
+    components: pkgList,
+    services: traceServices,
+    dryRunSummary,
+  } = await buildDynamicComponents(commandStr, workingDir, traceOptions);
 
-  return buildBomNSData(options, pkgList, "generic", {
+  const bomNSData = buildBomNSData(options, pkgList, "generic", {
     src: workingDir,
     projectType: "dynamic",
     filename: commandStr,
     services: traceServices,
   });
+  // A dry run denies every side effect, so the attempted-operation counts are
+  // the result. Only counts are recorded, never the paths or targets.
+  if (dryRunSummary && bomNSData?.bomJson?.metadata) {
+    const metadata = bomNSData.bomJson.metadata;
+    metadata.properties = metadata.properties || [];
+    metadata.properties.push({ name: "cdx:dynamic:dryRun", value: "true" });
+    metadata.properties.push({
+      name: "cdx:dynamic:dryRun:captured",
+      value: dryRunSummary.captured === false ? "false" : "true",
+    });
+    for (const [key, value] of Object.entries(dryRunSummary)) {
+      if (Number.isInteger(value)) {
+        metadata.properties.push({
+          name: `cdx:dynamic:dryRun:${key}`,
+          value: String(value),
+        });
+      }
+    }
+  }
+  return bomNSData;
 }
 
 /**
@@ -2561,7 +2594,13 @@ async function createBomForPath(path, options) {
   } else if (
     (options.projectType &&
       !options.projectType?.includes("universal") &&
-      hasAnyProjectType(["oci"], options, false)) ||
+      hasAnyProjectType(["oci"], options, false) &&
+      // Explicit container types accept every documented image reference
+      // style (postgres:15-alpine, shiftleft/scan-slim, registry:5000/ns/img),
+      // but only for inputs that cannot be a local path: existing files and
+      // directories keep flowing to the tar, oci-dir and source scanners.
+      !safeExistsSync(path) &&
+      isImageReference(path)) ||
     path.startsWith("docker.io") ||
     path.startsWith("quay.io") ||
     path.startsWith("ghcr.io") ||

package/lib/cli/jsBom.js

@@ -24,7 +24,10 @@ import {
   rewriteExtractedArchivePaths,
 } from "../ecosystems/asarutils.js";
 import { parseBunLock } from "../ecosystems/bunutils.js";
-import { parseCaxaMetadata } from "../ecosystems/caxa.js";
+import {
+  enrichCaxaMetadataFromApp,
+  parseCaxaMetadata,
+} from "../ecosystems/caxa.js";
 import {
   CHROME_EXTENSION_PURL_TYPE,
   collectChromeExtensionsFromPath,
@@ -77,6 +80,7 @@ import {
 } from "../inventory/analyzer.js";
 import {
   markNpmTypesPackagesAsExcluded,
+  markTypeOnlyDependenciesOptional,
   mergeDependencies,
   mergeServices,
   propagateRequiredScopeFromDependencies,
@@ -567,7 +571,16 @@ export async function createNodejsBom(path, options) {
         recordSensitiveFileRead(npmrcFile, {
           label: "npm registry configuration",
         });
-        const npmrcObj = parseNpmrc(npmrcData);
+        let npmrcObj = {};
+        try {
+          npmrcObj = parseNpmrc(npmrcData);
+        } catch (e) {
+          // A malformed .npmrc must degrade to a warning, never abort the scan.
+          console.warn(
+            `Unable to parse ${npmrcFile}. Continuing without it. ${e?.message || ""}`,
+          );
+          npmrcObj = {};
+        }
         for (const [key, value] of Object.entries(npmrcObj)) {
           const baseKey = key.replace(/^(?:\/\/[^/]+\/|@[^:]+:)/, "");
           if (
@@ -957,8 +970,12 @@ export async function createNodejsBom(path, options) {
   ) {
     // Rush.js creates node_modules inside common/temp directory
     const nmDir = join(path, "common", "temp", "node_modules");
-    // Do rush install if we don't have node_modules directory
-    if (!safeExistsSync(nmDir)) {
+    // Do rush install if we don't have node_modules directory. `rush install`
+    // drives pnpm without cdxgen's --ignore-scripts hardening and
+    // --bypass-policy disables rush's own policy gate, so it must respect
+    // --no-install-deps and the pre-build lifecycle like every other
+    // installer.
+    if (!safeExistsSync(nmDir) && options.installDeps !== false) {
       console.log("Executing 'rush install --no-link'", path);
       const result = safeSpawnSync(
         "rush",
@@ -1036,6 +1053,7 @@ export async function createNodejsBom(path, options) {
       }
       pkgList = propagateRequiredScopeFromDependencies(pkgList, dependencies);
       pkgList = markNpmTypesPackagesAsExcluded(pkgList);
+      pkgList = markTypeOnlyDependenciesOptional(pkgList, dependencies);
       return buildBomNSData(options, pkgList, "npm", {
         allImports,
         allExports,
@@ -1120,25 +1138,25 @@ export async function createNodejsBom(path, options) {
               );
               workspacePackages.push(workspaceRef);
               workspaceSrcFiles[workspaceRef] = relativePkgJsonFile;
-              if (pkgData?.dependencies || pkgData?.devDependencies) {
-                const dlist = new Set();
-                for (const [k, v] of Object.entries({
-                  ...(pkgData.dependencies || {}),
-                  ...(pkgData.devDependencies || {}),
-                })) {
-                  if (v.match(/^\d/)) {
-                    dlist.add(`pkg:npm/${k}@${v}`);
-                  } else {
-                    dlist.add(`pkg:npm/${k}`);
-                  }
-                }
-                workspaceDirectDeps[workspaceRef] = Array.from(dlist);
-                for (const dep of workspaceDirectDeps[workspaceRef]) {
-                  if (!depsWorkspaceRefs[dep]) {
-                    depsWorkspaceRefs[dep] = [];
-                  }
-                  depsWorkspaceRefs[dep].push(workspaceRef);
+              // The declared name and range of each direct dependency, which
+              // parseYarnLock resolves against the lock file to link the
+              // member into the dependency tree.
+              const declaredDeps = {
+                ...(pkgData.dependencies || {}),
+                ...(pkgData.optionalDependencies || {}),
+                ...(pkgData.devDependencies || {}),
+              };
+              if (Object.keys(declaredDeps).length) {
+                workspaceDirectDeps[workspaceRef] = declaredDeps;
+              }
+              for (const [k, v] of Object.entries(declaredDeps)) {
+                const dep = /^\d/.test(String(v))
+                  ? `pkg:npm/${k}@${v}`
+                  : `pkg:npm/${k}`;
+                if (!depsWorkspaceRefs[dep]) {
+                  depsWorkspaceRefs[dep] = [];
                 }
+                depsWorkspaceRefs[dep].push(workspaceRef);
               }
             }
           }
@@ -1495,6 +1513,7 @@ export async function createNodejsBom(path, options) {
   );
   pkgList = propagateRequiredScopeFromDependencies(pkgList, dependencies);
   pkgList = markNpmTypesPackagesAsExcluded(pkgList);
+  pkgList = markTypeOnlyDependenciesOptional(pkgList, dependencies);
   if (exactAiInventoryType === "mcp") {
     pkgList = trimComponents(filterInventorySubjectsByTypes(pkgList, ["mcp"]));
     dependencies = filterInventoryDependencies(
@@ -1624,8 +1643,14 @@ export async function createCaxaBom(path, options) {
     if (DEBUG_MODE) {
       console.log(`Parsing ${mfile}`);
     }
-    const { parentComponent, components, dependencies } =
-      await parseCaxaMetadata(mfile);
+    let mdata = await parseCaxaMetadata(mfile);
+    if (options.caxaAppDir) {
+      mdata = await enrichCaxaMetadataFromApp(
+        mdata,
+        resolve(options.caxaAppDir),
+      );
+    }
+    const { parentComponent, components, dependencies } = mdata;
     if (parentComponent) {
       if (!finalParentComponent) {
         finalParentComponent = parentComponent;