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 you are running the WhiteSource scan on

  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 WhiteSource 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.

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 WhiteSource. The benefit of this approach is a reduced number of projects in WhiteSource, 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 WhiteSource 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 WhiteSource.

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

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

 

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