Sonatype Platform Plugin for Jenkins

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 supported 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.

The Step user interface is identical for Jenkins Projects Build configuration and Pipeline Snippet Generator. Use the available Step names for the latest version of the plugin listed on the Sonatype Platform Plugin Steps Reference page.

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 severities (critical, severe, and moderate).

In addition to the summary, a historical graph is shown to indicate policy health over time.

The Application Report is accessible from the summary by clicking "view report" or "Lifecycle Policy Evaluation" in the left-hand navigation. Additionally, a Build Report is available within Jenkins by clicking the "IQ Build Report" in the left-hand nav. This build report shows which components caused a 'warn' or 'fail' action on a particular build.

If you are looking for previous report results, navigate to a specific build report in the Build History. Click on the link View Report to view the build report in IQ Server.

Various advanced options allow you more details when configuring your policy evaluation.

Scan Targets: The plugin scans all files in the workspace by default. 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. Only one scan target can be placed on each line.

Modules in the workspace: The Sonatype CLM for Maven has an index goal that can be used to create a module.xml file with all an application's components. By default, any module.xml file within its default directory will be scanned and evaluated for policy evaluation.

The default directories that the Jenkins plugin scans for module.xml files are **/sonatype-clm and **/nexus-iq . Any module.xml file located elsewhere in the scan targets will be ignored.

Module excludes:

The Module Excludes feature can be used to exclude any of these module.xml files from evaluation. Module Excludes takes Apache Ant-styled patterns (i.e. **/sonatype-clm/module.xml).

Fail build when unable to communicate with IQ Server: Enabling this option will fail the build when the IQ Server is unreachable.

Fail build when there are scanning errors: Enabling this option will fail the build when there are scanning errors, e.g. malformed files that could not be read.

Use job-specific credentials: This allows overriding the global credential configuration with job-specific authentication credentials.

Advanced properties: In a few cases, Sonatype support may provide additional parameters to the plugin using this input.

Enable debug logging: Increase the verbosity of the plugin-specific job logging to aid in diagnosing scanning problems or verifying scanning configuration.

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'

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.

Example: Set up a pipeline build that uses the results of a policy evaluation to push data to a GitHub pull request.

stage('Build') {
  postGitHub commitId, 'pending', 'build', 'Build is running'

  try {
    sh  "${mvnHome}/bin/mvn clean package"
    postGitHub commitId, 'success', 'build', 'Build succeeded'
  } catch (error) {
    postGitHub commitId, 'failure', 'build', 'Build failed'
    throw error
  }
}

3. Add a call to the GitHub API to update the status. To do this, set and declare the gitHubApiToken and project variables and then create the following function:

def postGitHub(commitId, state, context, description, targetUrl) {
  def payload = JsonOutput.toJson(
    state: state,
    context: context,
    description: description,
    target_url: targetUrl
  )
  sh "curl -H \"Authorization: token ${gitHubApiToken}\" --request POST --data '${payload}'
  https://api.github.com/repos/${project}/statuses/${commitId} > /dev/null"
}

4. After the build, we need to run a Lifecycle Analysis to determine the policy evaluation results. This will let GitHub know Lifecycle Analysis is running and then do the policy evaluation.

The easiest way to do this is by using the Jenkins Pipeline Syntax helper to generate a Groovy script:

Click the Pipeline Syntax link on your build configuration screen to open the Pipeline Syntax helper. Select nexusPolicyEvaluation as the sample step, select the IQ instance, stage and application you’d like to evaluate against, and then click Generate Pipeline Script. Copy the script and paste it into your pipeline script.

5. To process the evaluation results, set a policyEvaluation variable to the result. Like with the build, you’ll want to look at whether the build result is a failure or not to determine how to update your GitHub pull request. You can also add a link to the Application Composition Report. Having this available in your pull request lets you go directly to the evaluation, see why it failed, and perform remediation. An example Lifecycle Analysis script is shown below:

stage('Lifecycle Analysis') {
  postGitHub commitId, 'pending', 'analysis', 'Lifecycle Analysis is running'

  try {
    def policyEvaluation = nexusPolicyEvaluation iqApplication: 'webgoat', iqInstanceId: 'MyIQServer1', iqStage: 'build'
        postGitHub commitId, 'success', 'analysis', 'Lifecycle Analysis succeeded', "${policyEvaluation.applicationCompositionReportUrl}"
  } catch (error) {
    def policyEvaluation = error.policyEvaluation
    postGitHub commitId, 'failure', 'analysis', 'Lifecycle Analysis failed', "${policyEvaluation.applicationCompositionReportUrl}"
    throw error
  }
}

6. Save your pipeline and then run the build. When the build has been completed, you should see successful steps for Build and Lifecycle Analysis. In your GitHub pull request, you will see the successful checks and you can click the details link to view your report and address alerts or reevaluate policy.

org.jenkinsci.plugins.scriptsecurity.sandbox.RejectedAccessException: Scripts not permitted to

use method com.sonatype.nexus.api.iq.ApplicationPolicyEvaluation getApplicationCompositionReportUrl

In the above example, we utilized cURL to interact with the GitHub API and provide analysis feedback to GitHub. Many companies use GitHub for code review, and noting the status of CI builds in your pull request is a powerful analysis tool.

In addition to GitHub, you can use the object returned from the policy evaluation with almost anything that provides an interactive API or other Jenkins plugins.

A nexusPolicyEvaluation Pipeline step returns an evaluation result data model from which your Pipeline script may read additional information:

public class ApplicationPolicyEvaluation {
        private final List<PolicyAlert> policyAlerts;
        private final int affectedComponentCount;
        private final int criticalComponentCount;
        private final int severeComponentCount;
        private final int moderateComponentCount;
        private final String applicationCompositionReportUrl;
}

public class PolicyAlert {
        private final PolicyFact trigger;
        private final List<? extends Action> actions;
}

public class Action {
        private final String actionTypeId;
        private final String target;
        private final String targetType;
}

public class PolicyFacts {
        private final String policyId;
        private final String policyName;
        private final int threatLevel;
}