Snyk Maven CLI Plugin

Common errors

• Error: Cannot find module 'snyk-mvn-plugin' or its corresponding type declarations.

  cause The package is not installed in the project or the import path is incorrect.
  fix Install the package using `npm install snyk-mvn-plugin` or `yarn add snyk-mvn-plugin`. Verify the import path is exactly `snyk-mvn-plugin`.

• Error: Must be run with Node.js version >= 20.0.0

  cause The Node.js version in use is older than the minimum required by the package.
  fix Upgrade your Node.js environment to version 20 or newer. Use a Node.js version manager (like `nvm` or `volta`) to manage different Node.js versions.

• Error: Command failed: mvn -B dependency:tree

  cause The Maven executable (`mvn` or `mvnw`) was not found in the system PATH or is not accessible, preventing dependency tree analysis.
  fix Ensure that Maven is installed on your system and its binary directory is added to your system's PATH environment variable. Alternatively, ensure `mvnw` is present and executable in the project root.

• TypeError: inspect is not a function

  cause Attempting to use a CommonJS `require` syntax with an ESM-only package, or incorrect named import for an ESM module.
  fix Use ESM `import { inspect } from 'snyk-mvn-plugin';` syntax. Ensure your project's `package.json` specifies `"type": "module"` if it's a pure ESM project, or use a bundler that correctly handles ESM/CJS interop.

Warnings

• gotcha This package (`snyk-mvn-plugin`) is an internal component intended for use by the Snyk CLI tool. It is not designed for standalone vulnerability scanning without the Snyk CLI. For direct Maven build integration, refer to the `snyk-maven-plugin`.
  Fix: Ensure the Snyk CLI is installed and configured if attempting to perform security analysis. If integrating with Maven builds, consider using `io.snyk:snyk-maven-plugin` directly in your `pom.xml`.
• breaking The package explicitly requires Node.js v20 or higher, as indicated by its `engines` field. Running with older Node.js versions (e.g., v18) will result in runtime errors.
  Fix: Upgrade your Node.js environment to version 20 or newer. Use a Node.js version manager like `nvm` to easily switch versions.
• gotcha The `inspect` function relies on a local Maven installation (or `mvnw` wrapper) being available in the environment and accessible in the system PATH to perform dependency resolution.
  Fix: Ensure Maven is installed and configured in your system's PATH, or that a `mvnw` executable exists and is runnable in your project's root directory.
• gotcha When enabling `includeProvenance` for artifact fingerprinting, the Maven artifacts must already be downloaded and available in the configured local or custom Maven repository. The plugin does not perform artifact downloads itself.
  Fix: Run a standard Maven build command (e.g., `mvn install` or `mvn dependency:resolve`) beforehand to ensure all necessary artifacts are present in your local Maven repository.
• breaking Versions prior to `2.31.3` (specifically `2.2.0` to `2.31.2`) were vulnerable to Command Injection (CVE-2022-40764, CVE-2022-22984) due to an incomplete fix. This could allow attackers to run arbitrary commands on the host system, particularly in CI/CD pipelines.
  Fix: Upgrade to `snyk-mvn-plugin` version `2.31.3` or higher immediately. For CI/CD environments, ensure Snyk Docker images are updated as of 2022-11-29 or later.

Install

• npm install snyk-mvn-plugin npm
• yarn add snyk-mvn-plugin yarn
• pnpm add snyk-mvn-plugin pnpm

Imports

• inspect
  wrong:

  const { inspect } = require('snyk-mvn-plugin');

  correct:

  import { inspect } from 'snyk-mvn-plugin';

  The package primarily exports an `inspect` function. As of Node.js 20+ requirement, it is best used with ESM `import` syntax. Direct `require` might fail if the package is pure ESM.
• MavenOptions

  import type { MavenOptions } from 'snyk-mvn-plugin';

  For TypeScript users, import `MavenOptions` (and potentially `InspectResult` or other types) for type safety when configuring the `inspect` function.

Quickstart

Demonstrates how to use the `inspect` function to analyze a Maven `pom.xml` file, including options for provenance and algorithm selection.

import { inspect } from 'snyk-mvn-plugin';
import * as path from 'path';
import * as fs from 'fs';

async function runSnykMavenInspection() {
  const projectRoot = process.cwd(); // Assume running from project root
  const targetPom = path.join(projectRoot, 'pom.xml');

  if (!fs.existsSync(targetPom)) {
    console.error(`Error: pom.xml not found at ${targetPom}`);
    console.error('Please ensure you run this from a Maven project root or specify targetFile.');
    process.exit(1);
  }

  console.log(`Inspecting Maven project at: ${projectRoot}`);
  console.log(`Using target file: ${targetPom}`);

  try {
    const options = {
      dev: false, // Do not include development dependencies
      includeProvenance: true, // Generate cryptographic fingerprints for artifacts
      fingerprintAlgorithm: 'sha256', // Use SHA-256 for fingerprinting
      // mavenRepository: '/path/to/custom/repo' // Uncomment and adjust if you have a custom local Maven repository
    };

    const result = await inspect(projectRoot, targetPom, options);

    console.log('Inspection complete.');
    console.log(`Found ${result.pkgs ? result.pkgs.length : 0} packages.`);
    if (result.pkgs && result.pkgs.length > 0 && result.pkgs[0].info.purl) {
      console.log('First package PURL with checksum:', result.pkgs[0].info.purl);
    }
    // Uncomment the line below for full JSON output
    // console.log(JSON.stringify(result, null, 2));
  } catch (error: any) {
    console.error('Error during inspection:', error.message);
    process.exit(1);
  }
}

runSnykMavenInspection();