Configuring the Unified Agent for Maven

The following article outlines best practices and configuration recommendations when using the Unified Agent to scan Maven projects.

Best Practices

Before scanning a Maven project, ensure the following for the most accurate results:

1. You have Maven installed on the machine on which you are running the Mend scan.

2. The project can be built successfully on the machine where you are running the scan.

3. Your project has a pom.xml file available for scanning.

Configuring Unified Agent Parameters

The following parameters should always be set to the following for the most accurate results:

maven.resolveDependencies=true (default value)

maven.ignoreMvnTreeErrors=false (default value)

maven.downloadMissingDependencies=true (default value)

maven.environmentPath - Set this parameter to the appropriate value for your environment if the environment path does not match the M2_HOME environment variable

maven.m2RepositoryPath  - Set to the path to .m2 folder, in the case that it is not available in the default location

Multi Module Parameters

maven.aggregateModules  - Set this to 'true' if you wish to aggregate all of your POM files into one project. Aggregation of POM modules will cause the results to show as a flat list instead of a hierarchy tree. For ease of addressing vulnerabilities, set this parameter to 'false' and review each POM results individually.

maven.ignorePomModules - Set this to 'false' if you use a Super POM and would like it included in your results.

Optional Parameters

maven.ignoredScopes - Set this parameter to the scopes you wish to ignore. By default, the Unified Agent ignores direct dependencies with scope 'test' and 'provided'.

maven.ignoreSourceFiles  - Set to 'true' if you wish to ignore source files with extensions such as: ".java", ".class".

maven.runPreStep - Set to 'true' unless you have already run 'mvn clean install' on your project prior to the Mend scan.

maven.projectNameFromDependencyFile- Set to 'true' if you wish for the project name to be taken from the pom.xml's 'artifactId' field. This parameter works only when the maven resolver is the only active resolver ('resolveAllDependencies' is set to 'false').

failErrorLevel - When set to ‘ALL’, the Unified Agent returns an error code for all errors in the scan. We recommend you keep this parameter set to the default values.

maven.additionalArguments - Set to the parameters starting with '-' or '--' that you would like to be added to the end of the Maven commands during the scan. For example, -s=path/to/settings.xml.

maven.allowPartialTree - Set this parameter to ‘true’ if you wish to allow the scan to finish even if maven dependencies resolution is incomplete.

NOTE: Enabling maven.allowPartialTree means you are accepting maven’s dependency resolution as is. This may result in incorrect detection of transitive dependency versions, which in turn may lead to false positive or false negative vulnerability alerts.

Maven Dependency Plugin and the -Dverbose flag

Before version 22.4.2 of the Unified Agent and version 22.5.1 of our repo integrations, we did not support version 3.2.0 of the Maven Dependency Plugin. This is because of the following Maven commend the Mend scan would execute:

mvn dependency:tree -DoutputFile=whitesource_mvn_dependency_tree.txt -Dverbose -DoutputType=text -T1

The reason for this is, Mend detects the Maven dependencies based on the Apache Maven Dependency Plugin. A bug was found in the latest dependency plugin version 3.2.0 while running the dependency command with the -Dverbose parameter. This bug can cause the mvn dependency:tree -Dverbose command to take an extraordinarily long time to complete or eventually timeout.

If you are running versions older than the ones mentioned above, we have one fix and two workarounds to avoid the behavior:

Fix [Recommended] - Upgrade the Unified Agent

We highly recommend upgrading the Unified Agent to version 22.4.2 or later to correct the behavior. In this version and moving forward, we implemented a fix that will allow the Unified Agent to resolve Maven dependencies, regardless of the Maven dependency plugin version.

Workaround One - Update/Remove Plugin Definition

For customers who are unable to upgrade the Unified Agent and have projects that don’t require the Maven dependency plugin version 3.2.0 to build, it’s recommended to remove the plugin definition or override the plugin version in the parent pom.xml file.

The following example declares plugin version 2.10.0:

<plugins>
	<plugin>
		<groupId>org.apache.maven.plugins</groupId>
		<artifactId>maven-dependency-plugin</artifactId>
		<version>2.10.0</version>
	</plugin>
</plugins>

Workaround Two - Disabling -Dverbose

For customers who are unable to upgrade the Unified Agent and are require to use the maven dependency plugin version 3.2.0, it’s recommended to disable the -Dverbose option by setting the following parameter in the Unified Agent configuration file:

maven.additionalArguments=-Dverbose=false

Please note that not using the -Dverbose flag may cause dependencies to be excluded from the scan in case they're used in both compile and test/provided scopes. This is because they may be omitted due to duplicates by Maven, and omitted by Mend due to their scopes (as test and provided scopes are excluded by default).

Frequently Asked Questions

My project is taking too long to scan, is there a way to improve scan performance?

When the Unified Agent scan is running longer than expected, typically the Maven pre-step and downloading of dependencies take up a significant portion of the scan time. To reduce scan time, we recommend that you ensure that all dependencies are available in the local cache prior to scanning. This will prevent the scan from reaching out to Maven Central to download missing dependencies. To reduce runtime even further, include a step prior to the scan that runs ‘mvn clean install' and then set the parameter 'maven.runPreStep' to 'false'.

How should I set up my configuration file to scan my project that uses a Super POM?

You have a few options for scanning a multi module project that includes a Super POM.

Option 1: maven.aggregateModules  set to true and maven.ignorePomModules set to false

This will aggregate all of your POM files' dependencies (Super POM included) into one project in Mend. The benefit of this approach is a reduced number of projects in Mend, making it easier to keep track of projects. The downside of this approach is that you will not be able to see the hierarchy view of the dependencies for this project

Option 2: maven.aggregateModules  set to false and maven.ignorePomModules set to false

Each POM file will correspond to a project within Mend and the project that corresponds to the Super POM will be an aggregate of all of the other POMs referenced in the Super POM. You will be able to see the hierarchical view of the dependencies, but will have more projects to manage in Mend.

Option 3: maven.aggregateModules  set to true and maven.ignorePomModules set to true

Each POM file will correspond to a project within Mend and the project that corresponds to the Super POM will not be created.

My .jar files in the /target directory are not being scanned. Why not?

Beginning in Unified Agent v23.9.1, the /target folder is excluded from scans of Java projects. This change affects scans in Mend’s repository integrations as well. If you need to scan these files, please move them to a different directory.

Additional Resources

You can find more information about scanning Maven projects in the following document:

Unified Agent - documentation on how to use the Unified Agent