Skip to main content

Sonatype CLM for Maven

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:

  • ear or war files for deployment on application servers

  • tar.gz archives 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 help goal provides documentation for all the goals and parameters.

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.

  • Not required when using clm.serverId. Including will overwrite Maven settings.

clm.password

see description

The password or passcode for authenticate access with IQ Server.

  • Not required when using clm.serverId. Including will overwrite Maven settings.

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.

  • Use automatic application creation to add new applications when an unused id is provided.

clm.resultFile

The path for specifying the location of a JSON file where the following information will be stored:

    • applicationId : Application ID

    • scanId : Organization ID

    • reportHtmlUrl : URL to the HTML version of the report

    • reportPdfUrl : URL to the PDF version of the report

    • reportDataUrl : URL to the Data version of the report (for use via CURL, or similar tool)

clm.stage

'build'

The stage to run policy against.

  • Possible values: develop , build , stage-release , release, and operate.

  • The " develop " stage will produce a temporary report which is not retained in the UI.

clm.additionalScopes

The additional scopes to include components from during the evaluation.

  • Possible values: test , provided , system .

  • Separate the list using commas for more than one additional scope.

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.

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::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>

Note

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.xml file 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.47.14-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.47.14-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.47.14-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.47.14-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 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.47.14-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.

Note

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

Note

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 the 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:

126657204.png

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.

126657203.png

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 the Example Configuration of Sonatype CLM for Maven.

126657201.png

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.

126657200.png

After selecting 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.