@cdxgen/cdxgen 13.2.0 → 13.4.0

package/lib/audit/index.js

@@ -390,6 +390,27 @@ function targetSlug(target) {
   return `${target.type}-${normalized || "package"}-${version}-${digest}`;
 }
 
+/**
+ * Build a deterministic directory name for a repository checkout, keyed by
+ * the repository URL and the ref it is cloned at.
+ *
+ * Keying by the coordinates rather than the package means the packages of
+ * one monorepo share a single checkout instead of each cloning the whole
+ * repository, while a different ref, which is a different snapshot of the
+ * tree, never shares one.
+ *
+ * @param {string} repoUrl Repository URL
+ * @param {string | undefined} gitRef Ref the checkout is cloned at
+ * @returns {string} slug string
+ */
+function repositoryCheckoutSlug(repoUrl, gitRef) {
+  const digest = createHash("sha256")
+    .update(`${repoUrl}\n${gitRef || ""}`)
+    .digest("hex")
+    .slice(0, 16);
+  return `repo-${digest}`;
+}
+
 /**
  * Ensure a parent directory exists before writing a file.
  *
@@ -1378,7 +1399,12 @@ async function ensureCheckout(target, resolution, workspaceDir, gitRef) {
   if (!safeExistsSync(resolvedWorkspaceDir)) {
     safeMkdirSync(resolvedWorkspaceDir, { recursive: true });
   }
-  const cloneDir = join(resolvedWorkspaceDir, targetSlug(target));
+  // One checkout per repository and ref, so packages of the same monorepo
+  // share it; each package still keeps its own cache and report directory.
+  const cloneDir = join(
+    resolvedWorkspaceDir,
+    repositoryCheckoutSlug(resolution.repoUrl, gitRef),
+  );
   if (safeExistsSync(join(cloneDir, ".git"))) {
     return {
       cleanup: false,
@@ -2635,11 +2661,17 @@ export async function runAuditFromBoms(inputBoms, options) {
       total: extractedTargets.targets.length,
       type: "run:start",
     });
-    // Every target's repository lookup is known here, before the first clone,
-    // so they are resolved in one round rather than one per iteration below.
-    await prefetchGitUrlSources(
-      extractedTargets.targets.map((target) => target.purl),
-    );
+    // Every target's repository lookup is known here, before the first
+    // clone, so they are resolved in one round rather than one per iteration
+    // below. A target whose cached child BOM already answers it is resolved
+    // from the workspace alone, so only the targets that will be cloned take
+    // part in the round.
+    const purlsToResolve = extractedTargets.targets
+      .filter((target) => !loadCachedChildBom(options.workspaceDir, target))
+      .map((target) => target.purl);
+    if (purlsToResolve.length) {
+      await prefetchGitUrlSources(purlsToResolve);
+    }
   }
   for (const [index, target] of extractedTargets.targets.entries()) {
     const targetIndex = index + 1;

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,