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 allows users to evaluate any Maven-based software projects, in the same way our integrated tools (e.g. Nexus Pro, Eclipse, Hudson/Jenkins) do.

This means you can access the same robust, reporting features no matter what toolset you use. It can be run on a command line interface and can therefore be executed on any continuous integration server, as well as a number of popular IDEs.

How you use the Sonatype CLM for Maven plugin widely depends on how you enforce policy. However, in general, when using the plugin on a multi-module project in most cases 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. Again, this will largely depend on what your CLM policy is enforcing and what you want to validate.

In the following sections, we’ll provide details on these goals and their usage:

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.

Evaluate

The evaluate goal can trigger an evaluation directly against a Nexus IQ Server.

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 username 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 password 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 JVM for authentication.

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:

    • 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

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 is not recommended. It 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:

mvn com.sonatype.clm:clm-maven-plugin:evaluate -Dclm.additionalScopes=test,provided,system -Dclm.applicationId=test -Dclm.serverUrl=http://localhost:8070 -Dclm.username=<IQ username> -Dclm.password=<IQ password>

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.7.0-01:evaluate (default) @ test-app ---
[INFO] Starting scan...
[INFO] Scanning ../repository/org/codehaus/plexus/plexus-utils/3.0/plexus-utils-3.0.jar...
[INFO] Scanning ../repository/org/apache/maven/maven-settings/3.0/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
[INFO] Uploading scan to http://localhost:8070 ...
[INFO] Evaluating policies... (ETA 5s)
[INFO] Policy Action: None
Summary of policy violations: 0 critical, 0 severe, 0 moderate
The detailed report can be viewed online at
http://localhost:8070/ui/links/application/test/report/f4582a1570634dc2ac8

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 happen to 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, but 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.7.0-01</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.7.0-01: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.

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.

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.7.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.7.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 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.7.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 the IQ Server.

To speed the build up you can skip the test compilation and execution by passing -Dmaven.test.skip=true on the command line invocation, since it is not needed for the CLM evaluation.

IntelliJ IDEA

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.