@cdxgen/cdxgen 13.1.0 → 13.3.0

package/lib/ecosystems/gradleutils.js

@@ -1,9 +1,10 @@
 import { Buffer } from "node:buffer";
-import { chmodSync } from "node:fs";
+import { chmodSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { basename, join, resolve } from "node:path";
 
 import { build } from "@cdxgen/cdx-purl";
+import * as toml from "smol-toml";
 
 import {
   DEBUG_MODE,
@@ -23,7 +24,7 @@ import { thoughtLog } from "../core/logger.js";
 import { isWin } from "../core/paths.js";
 import { collectJarNS } from "../inventory/deps.js";
 import { minimumGradleVersionForJava } from "../inventory/jvmToolEnv.js";
-import { applyPurl } from "../inventory/purl.js";
+import { applyPurl, tryBuildPurl } from "../inventory/purl.js";
 import { parsePkgJson } from "./parsers-js.js";
 
 /**
@@ -40,19 +41,33 @@ function isJvmToolPinned() {
 /**
  * Method to return the gradle command to use.
  *
+ * Project-local wrapper scripts (`gradlew`) are attacker-controlled files in
+ * the scanned project, so they are only used when dependency tooling is
+ * allowed (`options.installDeps !== false`); otherwise the system Gradle is
+ * used.
+ *
  * @param {string} srcPath Path to look for gradlew wrapper
  * @param {string|null} rootPath Root directory to look for gradlew wrapper
+ * @param {Object} [options] CLI options (`installDeps` gates wrapper use)
  */
-export function getGradleCommand(srcPath, rootPath) {
+export function getGradleCommand(srcPath, rootPath, options = {}) {
   let gradleCmd = "gradle";
   const pinnedToolSelected = isJvmToolPinned();
+  // Introspection mode exists to observe the project's own toolchain, so it
+  // keeps using wrappers even when dependency installation is disabled.
+  const allowProjectWrappers =
+    options.installDeps !== false || options.introspect === true;
 
   let findGradleFile = "gradlew";
   if (platform() === "win32") {
     findGradleFile = "gradlew.bat";
   }
 
-  if (!pinnedToolSelected && safeExistsSync(join(srcPath, findGradleFile))) {
+  if (
+    allowProjectWrappers &&
+    !pinnedToolSelected &&
+    safeExistsSync(join(srcPath, findGradleFile))
+  ) {
     // Use local gradle wrapper if available
     // Enable execute permission
     try {
@@ -71,6 +86,7 @@ export function getGradleCommand(srcPath, rootPath) {
       reason: `Selected project-local Gradle wrapper ${gradleCmd}.`,
     });
   } else if (
+    allowProjectWrappers &&
     !pinnedToolSelected &&
     rootPath &&
     safeExistsSync(join(rootPath, findGradleFile))
@@ -379,8 +395,9 @@ export function executeParallelGradleProperties(
   dir,
   allProjectsStr,
   extraArgs = [],
+  options = {},
 ) {
-  const gradleCmd = getGradleCommand(dir, null);
+  const gradleCmd = getGradleCommand(dir, null, options);
   const gradleArgs = buildGradleCommandArguments(
     extraArgs.concat(
       readEnvironmentVariable("GRADLE_ARGS")
@@ -1204,11 +1221,16 @@ export async function collectGradleDependencies(
 /**
  * Method to return the mill command to use.
  *
+ * The project-local `mill` script is an attacker-controlled file in the
+ * scanned project, so it is only used when dependency tooling is allowed
+ * (`options.installDeps !== false`).
+ *
  * @param {string} srcPath Path to look for mill wrapper
+ * @param {Object} [options] CLI options (`installDeps` gates wrapper use)
  */
-export function getMillCommand(srcPath) {
+export function getMillCommand(srcPath, options = {}) {
   let millCmd = `mill${platform() === "win32" ? ".bat" : ""}`;
-  if (safeExistsSync(join(srcPath, millCmd))) {
+  if (options.installDeps !== false && safeExistsSync(join(srcPath, millCmd))) {
     // Use local mill wrapper if available
     // Enable execute permission
     try {
@@ -1225,15 +1247,24 @@ export function getMillCommand(srcPath) {
 /**
  * Method to return the maven command to use.
  *
+ * Project-local wrapper scripts (`mvnw`) are attacker-controlled files in the
+ * scanned project, so they are only used when dependency tooling is allowed
+ * (`options.installDeps !== false`); otherwise the installed Maven is used.
+ *
  * @param {string} srcPath Path to look for maven wrapper
  * @param {string} rootPath Root directory to look for maven wrapper
+ * @param {Object} [options] CLI options (`installDeps` gates wrapper use)
  */
-export function getMavenCommand(srcPath, rootPath) {
+export function getMavenCommand(srcPath, rootPath, options = {}) {
   let mavenCmd = "mvn";
   // Check if the wrapper script is both available and functional
   let isWrapperReady = false;
   let isWrapperFound = false;
   const pinnedToolSelected = isJvmToolPinned();
+  // Introspection mode exists to observe the project's own toolchain, so it
+  // keeps using wrappers even when dependency installation is disabled.
+  const allowProjectWrappers =
+    options.installDeps !== false || options.introspect === true;
   let findMavenFile = "mvnw";
   let mavenWrapperCmd = null;
   if (platform() === "win32") {
@@ -1246,7 +1277,11 @@ export function getMavenCommand(srcPath, rootPath) {
     }
   }
 
-  if (!pinnedToolSelected && safeExistsSync(join(srcPath, findMavenFile))) {
+  if (
+    allowProjectWrappers &&
+    !pinnedToolSelected &&
+    safeExistsSync(join(srcPath, findMavenFile))
+  ) {
     // Use local maven wrapper if available
     // Enable execute permission
     try {
@@ -1266,6 +1301,7 @@ export function getMavenCommand(srcPath, rootPath) {
       reason: `Found Maven wrapper candidate ${mavenWrapperCmd}.`,
     });
   } else if (
+    allowProjectWrappers &&
     !pinnedToolSelected &&
     rootPath &&
     safeExistsSync(join(rootPath, findMavenFile))
@@ -1386,3 +1422,143 @@ export function getMavenCommand(srcPath, rootPath) {
   }
   return mavenCmd;
 }
+
+/**
+ * Parse a Gradle version catalog (`gradle/libs.versions.toml`).
+ *
+ * A catalog declares coordinates the build scripts then reference by alias.
+ * It is a declaration, not a resolution: entries may go unused, and their
+ * versions may be references into the `[versions]` table. Because of that,
+ * catalog components are emitted only as a fallback when Gradle itself
+ * produced no dependency information, and every component carries a
+ * `cdx:gradle:catalog=true` property so consumers can tell declared catalog
+ * entries from a resolved graph.
+ *
+ * Only libraries whose version resolves to a literal (inline or via
+ * `version.ref`) are emitted; rich or unresolved versions would produce purls
+ * that identify no artifact. Plugins are skipped because they are build-time
+ * only.
+ *
+ * @param {string} catalogFile Path to `libs.versions.toml`
+ * @returns {Object[]} Package records for resolvable library entries
+ */
+export function parseGradleVersionCatalog(catalogFile) {
+  let catalog;
+  try {
+    catalog = toml.parse(readFileSync(catalogFile, "utf-8"));
+  } catch (error) {
+    console.warn(`Failed to parse ${catalogFile}: ${error.message}`);
+    return [];
+  }
+  const versions =
+    catalog?.versions && typeof catalog.versions === "object"
+      ? catalog.versions
+      : {};
+  const libraries =
+    catalog?.libraries && typeof catalog.libraries === "object"
+      ? catalog.libraries
+      : {};
+  const pkgList = [];
+  for (const entry of Object.values(libraries)) {
+    const coordinate = catalogCoordinate(entry);
+    if (!coordinate) {
+      continue;
+    }
+    const version = resolveCatalogVersion(entry, versions);
+    if (!version) {
+      continue;
+    }
+    const { group, name } = coordinate;
+    // A catalog is authored input, but a malformed coordinate must cost the
+    // one entry, not the whole scan.
+    const purl = tryBuildPurl({
+      type: "maven",
+      namespace: group,
+      name,
+      version,
+    });
+    if (!purl) {
+      continue;
+    }
+    pkgList.push({
+      group,
+      name,
+      version,
+      type: "library",
+      scope: "required",
+      purl,
+      "bom-ref": decodeURIComponent(purl),
+      properties: [
+        { name: "internal:SrcFile", value: catalogFile },
+        { name: "cdx:gradle:catalog", value: "true" },
+      ],
+      evidence: {
+        identity: {
+          field: "purl",
+          confidence: 0.5,
+          methods: [
+            {
+              technique: "source-code-analysis",
+              confidence: 0.5,
+              value: `Filename ${catalogFile}`,
+            },
+          ],
+        },
+      },
+    });
+  }
+  return pkgList;
+}
+
+/**
+ * Read the Maven coordinate of one catalog entry.
+ *
+ * A catalog writes the coordinate either as `module = "group:name"` or as a
+ * separate `group` and `name` pair; both forms are equivalent and both appear
+ * in real catalogs.
+ *
+ * @param {object} entry Catalog library entry
+ * @returns {{group: string, name: string}|undefined} Coordinate, or undefined
+ */
+function catalogCoordinate(entry) {
+  const module = typeof entry?.module === "string" ? entry.module : undefined;
+  if (module?.includes(":")) {
+    const separator = module.indexOf(":");
+    return {
+      group: module.slice(0, separator),
+      name: module.slice(separator + 1),
+    };
+  }
+  if (typeof entry?.group === "string" && typeof entry?.name === "string") {
+    return { group: entry.group, name: entry.name };
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the version of one catalog entry.
+ *
+ * An entry may pin `version = "1.2.3"` directly or reference the versions
+ * table with `version.ref = "alias"`. Version references that are missing, or
+ * that carry Gradle rich-version syntax (ranges, `!!`, separators), resolve
+ * to nothing and the entry is skipped.
+ *
+ * @param {object} entry Catalog library entry
+ * @param {object} versions Parsed `[versions]` table
+ * @returns {string|undefined} Concrete version, or undefined
+ */
+function resolveCatalogVersion(entry, versions) {
+  const raw =
+    typeof entry?.version === "string"
+      ? entry.version
+      : typeof entry?.version?.ref === "string"
+        ? versions[entry.version.ref]
+        : undefined;
+  if (typeof raw !== "string" || !raw) {
+    return undefined;
+  }
+  if (/[[\](),!]|->|\.\./u.test(raw)) {
+    return undefined;
+  }
+  return raw;
+}

package/lib/ecosystems/jsEvidence.js

@@ -8,9 +8,9 @@
 
 import { join, resolve } from "node:path";
 
-import { DEBUG_MODE } from "../core/activity.js";
 import { safeExistsSync } from "../core/fs.js";
 import { createOccurrenceEvidence } from "../inventory/evidenceUtils.js";
+import { isPkgTypeOnlyImport, setNpmTypeOnlyProperty } from "./npmutils.js";
 import { parsePkgJson } from "./parsers-js.js";
 
 const NPM_BIN_IMPORT_PREFIX = "cdx:npm:bin/";
@@ -109,8 +109,11 @@ function applyNpmBinCommandEvidence(pkg, allImports) {
  *
  * For each component, resolves its module aliases (including the deno jsr
  * specifier), records imported/exported modules as properties, attaches
- * occurrence evidence, and adjusts the component scope to "required" when the
- * package is used or "optional" when it is not.
+ * occurrence evidence, and promotes the component scope to "required" when the
+ * package is used. A package with no observed usage keeps the scope its
+ * manifest parser assigned: static import analysis cannot see packages loaded
+ * from configuration, bundler entrypoints, stylesheets, or plugins, so a
+ * missing import is not evidence that a package is optional.
  *
  * @param {Array<object>} pkgList Package components to enrich.
  * @param {object} allImports Map of import specifier to usage evidence objects.
@@ -128,10 +131,6 @@ export async function addEvidenceForImports(
   const impPkgs = Object.keys(allImports);
   const exportedPkgs = Object.keys(allExports);
   for (const pkg of pkgList) {
-    if (impPkgs?.length) {
-      // Assume that all packages are optional until we see an evidence
-      pkg.scope = "optional";
-    }
     const { group, name } = pkg;
     // Evidence belonging to a type must be associated with the package
     if (group === "@types") {
@@ -155,7 +154,6 @@ export async function addEvidenceForImports(
         aliases.push(jsrSpecifier);
       }
     }
-    let isImported = false;
     for (const alias of aliases) {
       const isWasmAlias = /\.wasm([?#].*)?$/i.test(alias);
       const all_includes = impPkgs.filter(
@@ -213,11 +211,22 @@ export async function addEvidenceForImports(
       }
       // Identify all the imported modules of a component
       if (impPkgs.includes(alias) || all_includes.length) {
-        isImported = true;
         let importedModules = new Set();
         let wasmExportedModules = new Set();
         const seenOccurrenceLocations = new Set();
-        pkg.scope = "required";
+        // A package imported only for its types is erased at compile time.
+        // Scoping it excluded here, rather than when the BOM is assembled,
+        // keeps propagateRequiredScopeFromDependencies from promoting what it
+        // depends on. A package whose bin command is used is still required.
+        if (
+          isPkgTypeOnlyImport(allImports, group, name) &&
+          !getNpmBinCommandEvidenceKeys(allImports, pkg).length
+        ) {
+          pkg.scope = "excluded";
+          setNpmTypeOnlyProperty(pkg);
+        } else {
+          pkg.scope = "required";
+        }
         for (const subevidence of all_includes) {
           const evidences = allImports[subevidence];
           for (const evidence of evidences) {
@@ -273,16 +282,6 @@ export async function addEvidenceForImports(
         }
         break;
       }
-      if (
-        impPkgs?.length > 0 &&
-        !isImported &&
-        DEBUG_MODE &&
-        pkg?.scope !== "optional"
-      ) {
-        console.debug(
-          `\x1b[1;35mNotice: Package ${pkg.name} has no usage in code. Check if it is needed.\x1b[0m`,
-        );
-      }
       // Capture metadata such as description from local node_modules in deep mode
       if (deep && !pkg.description && pkg.properties) {
         let localNodeModulesPath;