Sonatype CLM for Maven
The rebranding and renaming of Sonatype CLM to Nexus IQ Server started with the 1.17 release. You will see references to "Sonatype CLM" in the Maven plugin. We realize this may cause some confusion, and appreciate your patience as we move forward.
Overview
Sonatype CLM for Maven is a Maven plugin that allows users to evaluate any Maven-based software projects in the same way as our integrated tools (e.g. Nexus Pro, Eclipse, Hudson/Jenkins). This means you can access the same reporting features no matter what toolset you use. It can be run on a command line interface, which means it can be run on any continuous integration server as well as a number of popular IDEs.
In general, when using the plugin on a multi-module project, you will only configure an execution for the modules that produce components that will be deployed as an application.
Typically these are ear
files or war
files for deployment on application servers, or tar.gz
or other archives that are used for production deployments or distribution to users. That said, you can also analyze all modules of a project.
In the following sections, we’ll provide details on the first three goals and their usage:
evaluate | The evaluate goal can trigger an evaluation directly against a Nexus IQ Server. |
index | The index goal of the plugin allows you to prepare data for analysis with Sonatype CLM for CI. |
attach | The attach goal aids your integration with Sonatype Nexus CLM Edition and the release process using the staging tools of Nexus. |
help | The help goal provides documentation for all the goals and parameters and you can invoke it with an execution like mvn com.sonatype.clm:clm-maven-plugin:help |
Evaluating Project Components with Nexus IQ Server
The evaluate
goal scans the dependencies and build artifacts of a project and directly submits the information to a Nexus IQ Server for policy evaluation. If a policy violation is found and the CLM stage is configured to Fail
, the Maven build will fail. If invoked for an aggregator project, dependencies of all child modules will be considered.
The evaluate
goal requires the Nexus IQ Server URL as well as the application ID to be configured. Optionally, a CLM stage can be configured.
The command line arguments are:
clm.serverUrl | The URL for the CLM server, this parameter is required. |
clm.serverId | Used for authentication and must match the id given to the CLM Server specified in your Maven settings. |
clm.username | The "User Code" given to you by IQ Server when you created a user token, used to authenticate access to the CLM server. This is not required when using clm.serverId , but can be used to overwrite those settings. |
clm.password | The "Passcode" given to you by IQ Server when you created a user token, for the username indicated above. This is not required when using clm.serverId , but can be used to overwrite those settings. |
clm.pkiAuthentication | Delegate to the Java Virtual Machine for authentication. |
NEW IN VERSION 2.33clm.organizationId | The organization identifier under which the application will be created if the automatic application creation is enabled and the application does not exist. |
clm.applicationId | The application identifier for the application to run policy against. This parameter is required. If the application does not exist and automatic application creation is enabled, then a new application with that identifier will be created. |
clm.resultFile | The path for specifying the location of a JSON file where the following information will be stored:
|
clm.stage | The stage to run policy against, with the possible values of develop , build , stage-release , release and operate with a default value of build . Note that using the Lifecycle " develop " stage will not produce reports, since it is intended only for use with IDE integrations. |
clm.additionalScopes | The additional scopes you would like CLM to include components from during the evaluation. Values include test , provided , and system . In cases where you want to include more than one of these, separate the list using a comma (see examples below). |
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>
By default, only dependencies in the compile
and runtime
scopes will be 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.
You can avoid specifying the parameters on the command line 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>
Sonatype CLM for Maven can be executed 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.
The evaluate
goal logs its activity and provides the location of the generated report.
[INFO] --- clm-maven-plugin:2.41.0-02: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] ------------------------------------------------------------------------
The evaluate goal cannot be bound to a lifecycle phase.
After a successful build, the report can be accessed in the Nexus IQ Server under the application that was configured. A direct link is provided on the log.
Authentication
To configure authentication to the Nexus IQ Server, you will need to add your Nexus IQ Server 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>
In our example we have not encrypted our password. As a best practice, the password should be encrypted. The Apache Maven project provides instructions for password encryption. Additionally, username and password can still be specified at the command line, and will be used in place of these settings.
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
When evaluating a Maven-based software project, Sonatype CLM for Maven can take advantage of the dependency information contained in the project’s pom.xml
files and the information about transitive dependencies available to Maven.
The index
goal of Sonatype CLM for Maven allows you to identify component dependencies and makes this information available to IQ Server CI tools (e.g. IQ for Hudson/Jenkins or Bamboo). You can invoke an execution of the index
goal manually as part of your command line invocation by executing the index goal after the package phase:
mvn clean install com.sonatype.clm:clm-maven-plugin:index
Alternatively you can 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.41.0-02</version> <executions> <execution> <goals> <goal>index</goal> </goals> </execution> </executions> </plugin> </plugins> </build>
With the above configuration a normal Maven build execution with e.g. mvn clean install
will trigger the CLM plugin to be executed in the package
phase and result in a log output similar to
[INFO] --- clm-maven-plugin:2.41.0-02:index (default) @ test-app --- [INFO] Saved module information to /opt/test-app/target/sonatype-clm/module.xml
If you want to manually configure the lifecycle phase to execute the plugin, you have to choose a phase after package
.
The generated module.xml
file contains the information that will be picked up by IQ Server for CI and incorporated into the IQ Server evaluation. This improves the analysis since Sonatype CLM for Maven is able to create a complete dependency list rather than relying on binary build artifacts.
Excluding Module Information Files in Continuous Integration Tools
When using the Sonatype CLM for Maven plugin and the index goal, module information files are created. If desired, you can exclude some of the modules from being evaluated. For example, you may want to exclude modules that support your tests, and don’t contribute to the distributed application binary.
The default location where the module information files are stored is ${project.build.directory}/sonatype-clm/module.xml
.
In the supported CI tool, you will see a section labeled Module Excludes. On this area, use a comma-separated list of Apache Ant styled patterns relative to the workspace root that denote the module information files ( **/sonatype-clm/module.xml
) 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.
Creating a Component Info Archive for Nexus Repository Manager 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 Manager 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.41.0-02</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.41.0-02: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 the deployment repository manager or the Nexus staging repository ending with -sonatype-clm-scan.xml.gz
. This file will be picked up by Nexus Repository Manager Pro and used in the policy analysis during the staging process. It improves the analysis since Sonatype CLM for Maven is able to create a complete dependency list rather than relying on binary build artifacts.
Using Sonatype CLM for Maven with Other IDEs
While the integration with Eclipse offered by IQ Server is the most powerful tooling for developers available, users of other popular integrated development environments are not left without support. All common Java IDEs have powerful integration with Apache Maven and therefore can be used together with Sonatype CLM for Maven to evaluate projects against your IQ Server.
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 the IQ server 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.41.0-02</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 the IQ Server.
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
Nexus IQ 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 the IQ Server. 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 the IQ Server in the Output window. Policy violations can be configured to result in a build failure.
By default only dependencies in the compile
and runtime
scopes will be considered, since this reflects what other Maven packaging plugins typically include. Dependencies with the scopes test
, provided
and system
must be manually added, and are described in the previous section.