Sonatype CLM for Maven
Overview
Sonatype CLM for Maven is a Maven plugin that allows users to evaluate any Maven-based software projects (e.g. Nexus Repository 3 Pro, Eclipse, Hudson/Jenkins). Run Sonatype CLM for Maven from a command line interface to integrate with any continuous integration server or IDE.
When using the plugin on a multi-module project, only configure an execution for the modules that produce components deployed as an application.
For example:
earorwarfiles for deployment on application serverstar.gzarchives distributed to users- any modules of a project
The following sections are details on the goals to use.
evaluate | The evaluate goal triggers an evaluation to Lifecycle. |
index | The index goal of the plugin allows you to prepare data for analysis with Lifecycle for CI. |
attach | The attach goal aids your integration with Sonatype Platform Plugin and the release process using the staging tools of Nexus Repository 3 Pro. |
help | The mvn com.sonatype.clm:clm-maven-plugin:help |
Evaluating Project Components with Sonatype Lifecycle
The evaluate goal scans the dependencies and build artifacts of a project and directly submits the information to Sonatype Lifecycle for policy evaluation.
- The Maven build will fail when the analysis results trigger the failing action on the provided stage.
- Dependencies of all child modules will be considered when invoked for a multi-module / aggregator project.
- The evaluate goal cannot be bound to a lifecycle phase.
- The results can be accessed in Lifecycle under the application's lastest report or through the provided link.
The command line arguments are:
| Parameter | Required / Default | Description |
|---|---|---|
clm.serverUrl | required | The Sonatype Lifecycle URL |
clm.serverId | Used for authentication and must match the id given to the IQ Server configuration specified in your Maven settings. | |
clm.username | see description | The user for authenticate access with IQ Server. Consider replacing with a user token.
|
clm.password | see description | The password or passcode for authenticate access with IQ Server.
|
clm.pkiAuthentication | Delegate to the Java Virtual Machine for authentication. | |
clm.organizationId | The organization identifier to use during automatic application creation. | |
clm.applicationId | required | The application identifier for the application to run policy against. This parameter is required.
|
clm.resultFile | The path for specifying the location of a JSON file where the following information will be stored:
| |
clm.stage | 'build' | The stage to run policy against.
|
clm.additionalScopes | The additional scopes to include components from during the evaluation.
|
Included Dependencies
Only dependencies in the compile and runtime scopes are considered, since this reflects what other Maven packaging plugins typically include. Dependencies with the scopes test , provided and system must be manually added.
Review Maven documentation about scopes and here.
Evaluating a multi-module / aggregator project
The Sonatype CLM for Maven analysis can be called against an aggregator project. When executed in an aggregator project, it calculates the dependencies and transitive dependencies of all child modules and takes all of them into account for the policy evaluation.
Evaluate goal invocation example
An example invocation is below.
mvn com.sonatype.clm:clm-maven-plugin:evaluate -Dclm.additionalScopes=test,provided -Dclm.applicationId=test -Dclm.serverUrl=http://localhost:8070 -Dclm.username=<IQ username> -Dclm.password=<IQ password>
Evaluate goal example results
The evaluate goal logs its activity and provides the location of the generated report.
[INFO] --- clm-maven-plugin:2.46.0-01:evaluate (default-cli) @ line-comm-03 ---
[INFO] Starting scan...
...
[INFO] Evaluating policies on http://localhost:8070 ...
[ERROR] Sonatype IQ reports policy 'Security-Critical' failing for
component 'org.apache.logging.log4j:log4j-core:2.9.0' with hash '052f6548ae1688e126c2' due to
constraint 'Critical risk CVSS score':
Security Vulnerability Severity >= 9 because: Found security vulnerability CVE-2021-44228 with severity >= 9 (severity = 10.0)
[ERROR] Sonatype IQ reports policy 'Security-Critical' failing for
component 'org.apache.logging.log4j:log4j-core:2.9.0' with hash '052f6548ae1688e126c2' due to
constraint 'Critical risk CVSS score':
Security Vulnerability Severity >= 9 because: Found security vulnerability CVE-2021-45046 with severity >= 9 (severity = 9.0)
[WARNING] Sonatype IQ reports policy 'Security-Low' warning for
component 'org.apache.logging.log4j:log4j-core:2.9.0' with hash '052f6548ae1688e126c2' due to
constraint 'Low risk CVSS score':
Security Vulnerability Severity >= 0 because: Found security vulnerability CVE-2020-9488 with severity >= 0 (severity = 3.7)
Security Vulnerability Severity < 4 because: Found security vulnerability CVE-2020-9488 with severity < 4 (severity = 3.7)
[INFO] ------------------------------------------------------------------------
[INFO] Policy Action: Failure
[INFO] Number of components affected: 1 critical, 0 severe, 0 moderate
[INFO] Number of open policy violations: 2 critical, 0 severe, 1 moderate
[INFO] Number of grandfathered policy violations: 0
[INFO] Number of components evaluated: 5
[INFO] The detailed report can be viewed at: http://localhost:8070/ui/links/application/local-iq-app/report/755d19e970fd491ca2e23f21bea35d58
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 13.666 s
[INFO] Finished at: 2022-08-22T09:11:08-04:00
[INFO] ------------------------------------------------------------------------Including parameters in Maven settings
You may specify parameters by adding them to your settings.xml or pom.xml as properties.
<properties> <clm.serverUrl>http://localhost:8070</clm.serverUrl> <clm.applicationId>test</clm.applicationId> </properties>
Authentication
You may add your Lifecycle authentication information to your Maven settings.xml file:
<settings>
...
<servers>
<server>
<id>clm_server</id>
<username>my__clm_login</username>
<password>my_clm_password</password>
<!--username and password are not required if using JVM (PKI) authentication-->
</server>
...
</servers>
...
</setting>The password should be encrypted as a best practice. See the Apache Maven project instructions for password encryption or specify authentication at the command line.
Simplifying Command Line Invocations
If you use the plugin frequently by running it manually on the command line and want to shorten the command line even more, you can add a plugin group entry to your Maven settings.xml file:
<settings>
...
<pluginGroups>
<pluginGroup>com.sonatype.clm</pluginGroup>
...
</pluginGroups>
...
</settings>This enables you to invoke the plugin using its shorthand prefix form:
mvn ... clm:evaluate
Skipping Executions
The clm.skip parameter can be used when a CLM plugin execution is configured in your project’s pom.xml file and you want to avoid the execution for a particular build. An example execution is:
mvn clean install -Dclm.skip=true
The parameter can also be set in your IDE configuration for Maven build executions or as a property in your settings.xml or pom.xml :
<properties> <clm.skip>true</clm.skip> </properties>
Creating a Component Index
The index goal of Sonatype CLM for Maven allows you to identify component dependencies and makes this information available to Lifecycle's CI integrations. Invoke an execution of the index goal after the package phase.
- The generated
module.xmlfile will be included by Lifecycle during the CI evaluation - To manually configure the lifecycle phase to execute the plugin, you have to choose a phase after
package - The default location where the module information files are stored is
${project.build.directory}/sonatype-clm/module.xml
mvn clean install com.sonatype.clm:clm-maven-plugin:index
Alternatively, configure the execution in the pom.xml files build section or in a profile 's build section.
<build>
<plugins>
<plugin>
<groupId>com.sonatype.clm</groupId>
<artifactId>clm-maven-plugin</artifactId>
<version>2.46.0-01</version>
<executions>
<execution>
<goals>
<goal>index</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>With the above configuration a normal Maven build execution will trigger the plugin to be executed in the package phase.
[INFO] --- clm-maven-plugin:2.46.0-01:index (default) @ test-app --- [INFO] Saved module information to /opt/test-app/target/sonatype-clm/module.xml
Excluding Modules in Continuous Integration Integrations
Use the Module Excludes property in the CI configuration to exclude modules from being evaluated during an CI evaluation.
A comma-separated list of Apache Ant styled patterns relative to the workspace root will denote the module information files to be ignored.
Here’s an example of the pattern described above:
**/my-module/target/**, **/another-module/target/**
If unspecified, all modules will contribute dependency information (if any) to the evaluation.
Including a Bill of Materials in Nexus Repository 3 Pro
The attach goal scans the dependencies and build artifacts of a project and attaches the results to the project as another artifact in the form of a scan.xml.gz file. It contains all the checksums for the dependencies and their classes and further meta information and can be found in the target/sonatype-clm directory. A separate scan.xml.gz file is generated for each maven module in an aggregator project in which the plugin is executed.
This attachment causes the file to be part of any Maven install and deploy invocation. When the deployment is executed against a Nexus Repository 3 Pro server the artifact is used to evaluate policies against the components included in the evaluation.
To use this goal, add an execution for it in the POM, e.g. as part of a profile used during releases:
<build>
<plugins>
<plugin>
<groupId>com.sonatype.clm</groupId>
<artifactId>clm-maven-plugin</artifactId>
<version>2.46.0-01</version>
<executions>
<execution>
<goals>
<goal>attach</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>Once configured in your project, the build log will contain messages similar to
[INFO] --- clm-maven-plugin:2.46.0-01:attach (default) @ test-app --- [INFO] Starting scan... [INFO] Scanning ...plexus-utils-3.0.jar [INFO] Scanning ...maven-settings-3.0.jar... [INFO] Scanning target/test-app-1.0-SNAPSHOT.jar... [INFO] Saved module scan to /opt/test-app/target/sonatype-clm/scan.xml.gz
The attachment of the scan.xml.gz file as a build artifact causes it to be stored in the local repository as well as being deployed to Nexus Repository 3 Pro.
Using Sonatype CLM for Maven with IDEs
All common Java IDEs have integrations with Apache Maven and therefore can be used together with Sonatype CLM for Maven to evaluate projects against Sonatype Lifecycle.
This section showcases the integration with IntelliJ IDEA from JetBrains and NetBeans IDE from Oracle.
Maven Plugin Setup
In our example setup for the usage with other IDE’s we are going to add a plugin configuration for Sonatype CLM for Maven into the pom.xml file of the project we want to analyze as documented in the following Example Configuration of Sonatype CLM for Maven. This configuration defines the serverUrl of the IQ Server to be contacted for the evaluation, the applicationId used to identify the application in Lifecycle to evaluate against and the stage configuration to use for the evaluation.
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>com.sonatype.clm</groupId>
<artifactId>clm-maven-plugin</artifactId>
<version>2.46.0-01</version>
<configuration>
<serverUrl>http://localhost:8070</serverUrl>
<applicationId>test</applicationId>
<stage>develop</stage>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>With this configuration in place a user can kick off an evaluation with the command line mvn package clm:evaluate .
This will result in an output detailing the components to be analyzed, any policy violations and a link to the resulting report in Lifecycle.
To speed the build up you can skip the test compilation and execution by passing -Dmaven.test.skip on the command line invocation, since it is not needed for the CLM evaluation.
IntelliJ IDEA
Sonatype Lifecycle for IDEA is the recommended integration for IntelliJ IDEA, being the most powerful tooling available for IDEA users.
IntelliJ IDEA supports Maven projects natively and you can simply open a project in the IDE by opening the pom.xml file.
Once your project is open and you have added the plugin configuration for Sonatype CLM for Maven from Example Configuration of Sonatype CLM for Maven, you can create a configuration to run the desired Maven command.
Select Edit Configurations from the Run menu, press the + button and select Maven to add a new configuration. Enter the command line and other desired details as displayed in the following image:
After pressing OK in the dialog, the new configuration will be available in the run configuration drop down as well the Maven Projects view. You can open the view using the View menu, selecting Tools Window and pressing Maven Projects. You will see the window appear in the IDE looking similar to the image below. It displays the run configuration selector with the green play button on the top as well as the Maven project with the CLM evaluation run configuration.
You can press the green play button beside the run configuration, or the configuration entry itself in the Maven Projects window, to start a build. The build will run in an embedded console window in the IDE, and show all the output from the Maven build including any error messages and the link to the produced report in Lifecycle. Policy violations can be configured to result in a build failure.
NetBeans IDE
NetBeans IDE supports Maven projects natively and you can simply open a project in the IDE by choosing Open Project from the File menu and navigating to the directory that contains your project.
Once your project is opened, you can expand the Project Files section in the Projects window. Double-click on the pom.xml file and add the plugin configuration for Sonatype CLM for Maven from Example Configuration of Sonatype CLM for Maven.
If you right-click on the pom.xml file, you can choose Run Maven and Goals to open the Run Maven dialog. Enter the configuration as displayed and don’t forget to select Remember as: providing a name. This will allow you to simply start this defined configuration from the Run Maven context menu of the pom.xml file.
After pressing OK the defined Maven execution will start and display the output including any error messages and the link to the produced report in Lifecycle in the Output window. Policy violations can be configured to result in a build failure.