Sonatype Platform Plugin for Jenkins - Lifecycle

Sonatype Platform Plugin for Jenkins (previously known as the Nexus Platform Plugin for Jenkins) integrates Jenkins with Lifecycle to perform SCA open-source evaluations during the application build and to push the CI analysis back to CSM pull request.

This integration also works with Nexus Repository.

Release Notes

jenkins-plugin

jenkins-plugin

Changelog

Version 3.34.2 (July 13, 2026)

• Improved container scan error reporting by preserving the underlying failure cause

Version 3.34.1 (July 08, 2026)

• Fixed an issue where the “Test Connection” button in Nexus Repository settings failed with newer versions of Nexus Repository
• Fixed Maven upload failures from Jenkins agent workspaces when an HTTP proxy is configured

Version 3.34.0 (June 04, 2026)

• Added support for .NET reachability analysis
• Added support for reachability analysis evidence

Version 3.33.2 (May 27, 2026)

• Maintenance release

Version 3.33.1 (May 14, 2026)

• Maintenance release

Version 3.33.0 (May 08, 2026)

• Added support for .NET reachability analysis
• Fixed scanning-error handling so failBuildOnScanningErrors: false is honored, preventing unparseable files from incorrectly marking builds as unstable or failed

Version 3.32.0 (April 09, 2026)

• Added support for API-based CI configuration
• Updated the default scanner mode to Sonatype Container Scanner
• Improved upload performance to NXRM from remote agents
• Fixed an issue where Reachability Analysis could hang on Jenkins Kubernetes pod agents

Version 3.31.0 (March 06, 2026)

• Jenkins temporary workspace folder is now used correctly instead of the default Java temporary folder
• Builds no longer default to Unstable on reachability errors when Fail on Build is set to false
• Added support for proxy configurations without credentials
• Added a Project Directory input field in the JavaScript Reachability Configuration UI
• Fixed issue where pipelines were incorrectly marked as failed when reachability analysis did not run

Version 3.30.2 (February 05, 2026)

• Maintenance release

Compatibility

Prerequisites

The Sonatype Platform Plugin for Jenkins uses the HTTP proxy settings defined in Manage Jenkins > Manage Plugins > Advanced. These settings take precedence over any JVM proxy settings and are applied consistently by both Nexus Repository and IQ Server. If no Jenkins proxy settings are configured in the UI, the plugin falls back to the JVM proxy settings, for example:

-Dhttp.proxyHost=127.0.0.1
-Dhttp.proxyPort=8080
-Dhttp.nonProxyHosts="*.demo"

To bypass the HTTP proxy server you must update the non-proxy host to include the IQ Server.

Installation and Configuration

Go to the Installation and Configuration page for steps to install and set up Sonatype Platform Plugin for Jenkins.

Adding an Evaluation to a Build

Pipeline refers to both Declarative and Scripted Jenkins Pipelines.

Project (or Job) refers to a Jenkins item, such as a Freestyle project, Multi-configuration project, or Maven project, that allows selecting an explicit build__step from a drop-down menu and filling in form field values inside the build configuration.

The scan patterns applied by default are **/*.jar, **/*.war, **/*.ear, **/*.zip, **/*.tar.gz.

To use other patterns, a manual override of iqScanPatterns is required, as described in the pipeline build step below.

Adding Pipeline Build Step

Use the following steps to add a Lifecycle Policy Evaluation build step to a pipeline build:

1. On the Pipeline project page, click Pipeline Syntax in the left menu to open the Snippet Generator.
2. In Snippet Generator > Steps, under Sample Step, select nexusPolicyEvaluation: Invoke Sonatype Policy Evaluation.
3. Fill in the values for the policy evaluation.
4. Click the Generate Pipeline Script button.
5. Copy the generated script and paste it into the desired stage of your pipeline script.

Example Pipeline Script

nexusPolicyEvaluation(
     iqApplication: 'SampApp',
     iqInstanceId: 'MyIQServer1',
     iqStage: 'build'
)

Example Pipeline Script with Scan Patterns to Override Defaults

nexusPolicyEvaluation(
     iqApplication: 'SampApp',
     iqInstanceId: 'MyIQServer1',
     iqScanPatterns: [[scanPattern: '**/*.js'], [scanPattern: '**/*.zip']],
     iqStage: 'build',
     iqOrganization: '55040769ec08424e84049356a3362d07'
)

The scan patterns support exclude patterns. The exclude patterns start with a '!' character and must be specified after all other included patterns. For example, the following scan patterns will consider for evaluation all files except those under the '.git' directory:

iqScanPatterns: [[scanPattern: '**'], [scanPattern: '!.git/**']]

Example Pipeline Script Overriding Most Advanced Options

nexusPolicyEvaluation(
     advancedProperties: 'test=value',
     enableDebugLogging: true,
     failBuildOnNetworkError: true,
     failBuildOnScanningErrors: true,
     iqApplication: selectedApplication('sandbox-application'),
     iqInstanceId: 'MyIQServer1',
     iqModuleExcludes: [[moduleExclude: '**/module-2-exclude/module.xml'], [moduleExclude: '**/module-1-exclude/module.xml']],
     iqScanPatterns: [[scanPattern: '**/other/*.jar'], [scanPattern: '**/special/*.jar']],
     iqStage: 'build',
     jobCredentialsId: 'iq-server-localhost'
)

Adding Project Step

Use the following steps to add a Lifecycle Policy Evaluation build step to a project:

1. On the project page, click Configure in the left menu.
2. Click Build Steps.
3. Click the Add Build Step button.
4. Select Invoke Sonatype Policy Evaluation.
5. Fill in the values for the policy evaluation.
6. Click Save.

Policy Evaluation Values and Advanced Options

• IQ Instance: Select an IQ Server that will be used to run the policy evaluation.
• Stage: Select Develop, Source, Build, Stage Release, Release, or Operate. This controls the stage the policy evaluation is run against on the IQ Server. Only the stages you are licensed to appear in the list.

Note

The severity of the IQ Server Policy Actions for a Stage determines the final build result. A Warn action equates to an UNSTABLE build. A Fail action equates to a FAILURE.

• Organization (optional): Select an organization from the list. If automatic application creation is enabled and the application does not exist, it will be created under the selected organization. If both the application and the organization IDs are provided, and the application already exists under a different organization, the evaluation process stops with an error message. This mechanism is in place to prevent accidental configurations, which could unintentionally alter the evaluation history of existing applications.
• Application: Select an application from the list of available IQ Server applications. This determines the policy elements (policies, labels, and license threat groups) to associate with this build and is managed via the IQ Server. An application can also be specified that is not on the list. If automatic application creation is enabled, an application with the specified ID will automatically be created if it does not already exist in the IQ Server.
• Scan Targets: The plugin is configured by default to scan the following targets within your workspace: **/*.jar, **/*.war, **/*.ear, **/*.zip, **/*.tar.gz. Any special non-archive files like manifests may incur special handling depending on the version of the plugin used. Each scan target field takes an Apache Ant-styled pattern (i.e. **/*.js). Supplying custom scan targets will limit scanning to only those files matching the scan targets.
• Reachability Analysis: If enabled, this feature will identify vulnerable components that can be reached by executing the application.
• Advanced Options:
  • Module excludes in workspace: Here you can exclude any of the module.xml files from evaluation. Module Excludes takes Apache Ant-styled patterns (i.e. **/sonatype-clm/module.xml). Once you define your module excludes, click Add.

Note

Module Excludes is only for excluding module.xml files generated by Sonatype CLM for Maven and is not an option for excluding scan targets.

• Fail build when unable to communicate with IQ Server:failBuildOnNetworkError - Enabling the option will fail the build when the IQ Server is unreachable.
• Fail build when there are scanning errors:failBuildOnScanningErrors - Enabling this option will fail the build when there are scanning errors, e.g. malformed files that could not be read. Otherwise, the build status will be UNSTABLE.
• Unstable build when there are scanning warnings:unstableBuildOnScanningWarnings - Disabling this option will mark the Jenkins job as SUCCESS instead of UNSTABLE if the policy evaluation has alerts with a warn action. The option is enabled by default.
• Use job specific credentials: This allows overriding the global credential configuration with job-specific authentication credentials. Select any of the existing credentials or click Add and select Jenkins to open the Jenkins Credentials Provider pop-up.
• Enable debug logging: Increase the verbosity of the plugin-specific job logging to aid in diagnosing scanning problems or verifying scanning configuration.
• Advanced properties: In a few cases, Sonatype support may provide additional parameters to the plugin using this input.

Evaluating Docker Images

Use the container prefix in the scan pattern to scan the docker images you want to scan.

nexusPolicyEvaluation iqApplication: 'appId', iqInstanceId: 'MyIQServer1', iqScanPatterns: [[scanPattern: 'container:namespace/image:image-tag']], iqStage: 'build'

Reviewing Evaluation Results

Once the build is complete, a summary is shown on the project page. The three boxes (red, orange, and yellow) located below the link give you counts for policy violations and are based on the associated severity (critical, severe, and moderate).

A historical graph is also shown to indicate policy health over time.

Additionally, a build report is available within Jenkins by clicking the IQ Build Report in the left-hand navigation. This build report shows which components caused a 'warn' or 'fail' action on a particular build.

Returned Pipeline Stage Statuses

When an evaluation is performed by the plugin, the stage status depends on the configured policy actions.

• Jenkins shows unstable for the build when the policy action is set to WARN
• Jenkins shows failed for the build when the policy action is set to FAIL
• When the policy action is set to No Action, discovered policy violations will have no effect on the Jenkins build state.

Use the variable currentBuild.result to examine the value returned within the pipeline script.

Using Policy Evaluation Results

Utilizing the Sonatype for Jenkins plugin provides full component intelligence and the ability to run policy against your application. Jenkins pipelines let you invoke a build step as part of the build process and use the results for complex workflows. For example, objects returned from a build pipeline step can be used to provide feedback in the application about the process of an evaluation.

Reachability Analysis

See Reachability Analysis with Jenkins for how to enable Reachability in Pipeline/Multi-branch jobs, including required plugin versions, the parameters and Pipeline snippet, and the entry point strategy with tips for narrowing scope via namespaces.