Nexus IQ for GitLab CI

Download

Download the Docker image here:  GitLab Nexus IQ Docker image

Overview

CI/CD pipeline jobs in GitLab leverage custom docker images to perform desired actions in the context of the GitLab project's build workspace.  As such, the GitLab Nexus IQ docker image provides the ability to run Nexus policy evaluation against build artifacts in GitLab and produces an evaluation report with policy violation counts and a link to a detailed report on the IQ server.

The IQ policy evaluation will pass/fail a GitLab pipeline based on the policy action defined in IQ for the given application and stage.  See the IQ server documentation for details on setting up policies and policy actions.

In addition, Nexus IQ for GitLab can assist with the remediation of identified vulnerabilities.  See Nexus IQ for SCM for more information on how to enable and use this capability.


Project Configuration

Any project that wants to leverage GitLab's CI/CD pipeline must include a .gitlab-ci.yml pipeline definition file in the root of the project.  Documentation on the various options for pipeline and job definitions is available here.  A GitLab pipeline job that performs Nexus IQ policy evaluation consists of the following elements and would look something like this:

iq_policy_eval:
  stage: test
  image: sonatype/gitlab-nexus-iq-pipeline:1.106.0-01
  script:
    - /sonatype/evaluate -i WebAppX target/web-app-x.war
  artifacts:
    name: "policy-eval-$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - WebAppX-policy-eval-report.html

Let's explore some of these elements in more detail:

  • iq_policy_eval - the name of the job and can be anything you like
  • stage: test  - the pipeline stage in which to run the policy evaluation;  can be any one of the built-in stages or any custom stage defined earlier in the pipeline definition file
  • image: sonatype/gitlab-nexus-iq-pipeline:1.106.0-01 - the docker image that will be used during the execution of this pipeline job. Available versions can be found in the GitLab Nexus IQ docker image repository.
  • script - the script statements that will be run in the context of the given docker image;  in this case, the following minimal elements are required:
    • /sonatype/evaluate is the shell script inside the docker container that executes the policy evaluation
    • -i WebAppX is the unique ID of the application being evaluated, as defined in the Nexus IQ server
    • target/web-app-x.war is a list of one or more artifacts from the build environment to perform the evaluation against
    • See the documentation provided with the image on Docker Hub for details about other options available during policy evaluation
  • artifacts - list of directories or files that will be zipped and archived with the executed pipeline;  see the GitLab documentation for more information on how long these artifacts live and how to access them
    • name - the name to give the artifact zip file (note: pipeline variables can be used to create the name, as shown in the above example)
    • paths - references to one or more files or directories in the build environment to include in the archive
      • WebAppX-policy-eval-report.html - this is the name of the report generated by the policy evaluation and is comprised of '<app id>-policy-eval-report.html'

In order to make GitLab CI/CD pipeline job artifacts available across jobs you should add them to the pipeline cache, which could be defined a little further up in the file, as so:

cache:
  paths:
    - target/
    - <submodule1>/target/
    - <submodule2>/target/

Here is a typical output for a policy evaluation job configured as above (some lines were omitted for brevity):

Commencing Nexus IQ policy evaluation...
 [INFO] Validating IQ Server version http://192.168.1.201:8070...
 [INFO] Validating application ID repo-a with the IQ Server http://192.168.1.201:8070...
 [INFO] Discovered commit hash 'c857286a3c4bc332e9b4c279fa7fab8dcb9377e3' via environment variable CI_COMMIT_SHA
 [INFO] Starting scan...
 [INFO] Scan target: /builds/root/repo-a/target/dependency/commons-fileupload-1.4.jar
...
 [INFO] 2021-04-09T15:34:33.869Z Finished scanning target: /builds/root/repo-a/target/sonatype-clm/module.xml
 [INFO] 2021-04-09T15:34:33.869Z Scanned 1455 total files
 [INFO] Fingerprinting completed in 1 seconds for 8 archives, 1296 total files
 [INFO] Discovered repository url 'http://172.100.0.2/root/repo-a' via environment variable CI_PROJECT_URL
 [INFO] Waiting for policy evaluation to complete...
 [INFO] Assigned scan ID 361b686717f94080a73ccb9c0a2d99cb
 [INFO] Policy evaluation completed in 10 seconds.
 [INFO] 
 [ERROR] The IQ Server reports policy failing due to 
 Policy(Sev-Critical) [
  Component(displayName=org.apache.logging.log4j : log4j-core : 2.3, hash=58a3e964db5307e30650) [
   Constraint(Severity) [Security Vulnerability Severity >= 8 because: Found security vulnerability CVE-2017-5645 with severity >= 8 (severity = 9.8), on condition 0] ]]
 [ERROR] The IQ Server reports policy failing due to 
 Policy(Sev-High) [
  Component(displayName=Junit : junit : 4.12, hash=2973d150c0dc1fefe998) [
   Constraint(Severity) [Security Vulnerability Severity >= 4 because: Found security vulnerability CVE-2020-15250 with severity >= 4 (severity = 5.5), on condition 0] ]]
...
 [ERROR] The IQ Server reports policy failing due to 
 Policy(Sev-High) [
  Component(displayName=commons-io : commons-io : 2.2, hash=83b5b8a7ba1c08f9e8c8) [
   Constraint(Severity) [Security Vulnerability Severity < 8 because: Found security vulnerability sonatype-2018-0705 with severity < 8 (severity = 7.8), on condition 0] ]]
 [INFO] 
 [INFO] 
 [INFO] *********************************************************************************************
 [INFO] Policy Action: Failure
 [INFO] Stage: build
 [INFO] Number of components affected: 1 critical, 3 severe, 0 moderate
 [INFO] Number of open policy violations: 1 critical, 12 severe, 0 moderate
 [INFO] Number of grandfathered policy violations: 0
 [INFO] Number of components: 8
 [INFO] The detailed report can be viewed online at http://192.168.1.201:8070/ui/links/application/repo-a/report/361b686717f94080a73ccb9c0a2d99cb
 [INFO] *********************************************************************************************
 [INFO] Processing policy evaluation results...
 ...Nexus IQ policy evaluation complete

The policy evaluation job's output lists all the files that are considered for evaluation. If there are policy violations, they are listed as errors. Each policy violation states its severity, the component that triggered the violation, and the failed policy details.

The policy evaluation summary can be found at the end of the job's output. It also contains a link to a detailed report in Nexus IQ.

Nexus IQ Server Connection Information

The required connection information for the IQ server can be specified at either the group or project level using the CI/CD settings, as so:

The following three environment variables must be defined if not set explicitly in the job definition via script parameters:

NEW IN RELEASE 1.125.0-02A

An optional environment variable, named NEXUS_IQ_REPORT_FORMAT, can be set to control the content of the generated evaluation report. If the variable is set to 'summary', the evaluation report will contain a brief summary information and a link to the detailed report on the IQ server. Otherwise, the evaluation report will contain a summary header, which includes a link to the detailed report on the IQ server, and details about the components that trigger policy actions, accompanied by policy violation details.


Problems with the IQ server connection will show up in, and can be diagnosed from, the pipeline job output, as so:

Self-signed Certificates

If the IQ Server uses a self-signed certificate, additional configuration is needed to make Nexus IQ for GitLab CI work.

There are two approaches that could be taken to make that happen:

  • Add the self-signed certificate to the Docker container created from the GitLab Nexus IQ Docker image on the fly, or
  • Create a custom Docker image from the GitLab Nexus IQ Docker image, add the self-signed certificate to the new image, and use this newly created image to run policy evaluations against IQ Server.

Add the self-signed certificate on the fly

In order to achieve that the self-signed certificate must be available during the pipeline execution. It could be checked in to the repository, or pulled at runtime from a common location (e.g. using wget or similar tools).

Below you can see a stripped down pipeline that adds the self-signed certificate to the Docker container on the fly, assuming the certificate (i.e. iq-server.cert) is checked in to the root folder of the repository:

iq_policy_eval:
  stage: test
  image: sonatype/gitlab-nexus-iq-pipeline:latest
  before_script:
    - keytool -keystore /opt/java/openjdk/lib/security/cacerts -storepass changeit -noprompt -trustcacerts -importcert -alias iq-server -file iq-server.cert
  script:
    - /sonatype/evaluate -i WebAppX target/web-app-x.war
  artifacts:
    name: "policy-eval-$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - WebAppX-policy-eval-report.html

Create a custom Docker image

Here's a working Dockerfile that can be used to build a custom image, which contains the self-signed certificate:

FROM sonatype/gitlab-nexus-iq-pipeline
COPY iq-server.cert /certs/
RUN keytool -keystore /opt/java/openjdk/lib/security/cacerts -storepass changeit -noprompt -trustcacerts -importcert -alias iq-server -file /certs/iq-server.cert

The image can be built (replace your-org and the image version with meaningful values) e.g.

docker build -t your-org/gitlab-nexus-iq-pipeline:1.0.0 .

Then it can be published and used for policy evaluations e.g.

iq_policy_eval:
  stage: test
  image: your-org/gitlab-nexus-iq-pipeline:1.0.0
  script:
    - /sonatype/evaluate -i WebAppX target/web-app-x.war
  artifacts:
    name: "policy-eval-$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
    paths:
      - WebAppX-policy-eval-report.html

Release Notes

Version 1.139.0-01 (June 2022)

Version 1.138.0-01 (May 2022)

Version 1.137.0-05 (May 2022)

Version 1.135.0-01 (March 2022)

Version 1.134.0-02 (March 2022)

Version 1.133.0-02 (March 2022)

Version 1.132.0-02 (January 2022)

  • Provide the latest features for Nexus Lifecycle 132
  • Bug Fix for False Positives in Image Scans

Version 1.130.0-01 (December 2021)

  • Update logback Library Version in IQ
    • Nexus IQ Server does not use log4j versions and uses logback instead. It is therefore not at risk from vulnerabilities impacting log4j.
      However, because of a low/moderate vulnerability existing in "logback", we're taking precautionary measures by updating the logback library version used in Nexus IQ products.
  • Cran and Cargo Matching Improvements
  • Conda Matching Improvements

Version 1.125.0-02a (October 2021)

  • An optional environment variable, NEXUS_IQ_REPORT_FORMAT, can be set to control the content of the generated evaluation report

Version 1.125.0-02 (October 2021)

  • Conan Matching Improvements
    • Conan data and matching have been improved for both Lifecycle and Firewall.
  • Dependency Information Improvements for NPM
    • NPM Dependency Information detection has been improved to display more accurate results.

Version 1.123.0-01 (September 2021)

  • Fixed an issue with some NPM scans that was causing IQ Server 122 evaluations to fail when reading dependency information.

Version 1.122.0-01 (September 2021)

Version 1.121.0-01 (August 2021)

  • Support for container scanning via Nexus Container

Version 1.119.0-03 (July 2021)

  • SBOM Improvements and Bug Fixes:
    • CycloneDX SBOM scans have been improved to display better results

Version 1.118.0-01 (June 2021)

  • Swift Application Analysis:
    • IQ Server can now be used to evaluate policies against components from the dependency file of a Swift application.

Version 1.117.0-01 (June 2021)

Version 1.116.0-01 (June 2021)

  • Improvements to Python Application Analysis:
    • IQ Server now supports evaluating policies against Python components defined in poetry.lock files.

Version 1.114.0-01 (May 2021)

Version 1.107.0-01 (March 2021)

  • Java Manifest Application Analysis:
    • IQ Server now supports evaluating policies against Java components in pom.xml and build.gradle files

Version 1.106.0-01 (March 2021)

  • Improvements to manifest analysis:
    • Updated CLI scanner to exclude development dependencies when scanning package-lock.json files.
    • Updated CLI scanner to parse package-lock.json files stored inside an archive.
    • Fixed parsing errors when scanning yarn.lock and *.csproj files.

Version 1.105.0-01 (Feb 2021)

  • Fixed initialization error in NuGet manifest scanning

Version 1.104.0-02 (Jan 2021)

Version 1.103.0-01 (Dec 2020)

  • Added support for analyzing Java 14 and 15 bytecode.

Version 1.101.0-01 (Nov 2020)

  • Nexus IQ CLI no longer supports Lifecycle XC.  IQ Server now has native support for all languages that were supported in Lifecycle XC. 

Version 1.98.0-01 (Sep 2020)

  • Application analysis of components for:

Version 1.97.0-01 (Aug 2020)

  • Application analysis of components for:

Version 1.94.0-01 (Jun 2020)

  • Now releasing in sync with Nexus IQ Server releases (which may or may not include updates relevant to this docker image's release)
  • Application analysis of components for:
    • C/C++ conanfile.py Files
    • Yum
    • Alpine
    • Debian
    • Drupal
    • R (CRAN)
    • Rust (Cargo)

Version 1.88.0-02 (Mar 2020)

  • Application analysis of components for:
    • Swift/Objective-C CocoaPods
    • Conda

Version 1.87.0-02 (Mar 2020)

  • Identify components based on SHA-1 value (content hash)
  • Application analysis of components for:
    • C/C++ Conan
    • PHP Composer
    • RubyGems
    • CycloneDX application analysis extended to support submitting component vulnerabilities

Version 1.2 (Sep 2019)

  • pushed environment variables into processes for automated onboarding of applications for Nexus IQ for SCM

Version 1.1 (Apr 2019)

  • expanded coverage option (-xc) fixed
  • application ID added to the report filename
  • policy violation counts added to the html report

Version 1.0 (Apr 2019)

  • Known issues:
    • Using the expanded coverage option (-xc) will incorrectly cause the pipeline job to fail
    • Multiple evaluations in the same job will incorrectly append report information to the same policy-eval-report.html file