CI Components - Sonatype for GitLab CI

The component set currently contains several top-level, single-purpose components:

Run a policy evaluation against a Sonatype IQ Server instance.
Create a vulnerability report based on a previous policy evaluation.
Fetch a Software Bill of Materials (SBOM) from a Sonatype IQ Server instance.

Additionally, two convenience components are also provided, which wrap the above components:

Run a policy evaluation against a Sonatype IQ Server instance, and also get a vulnerability report and the SBOM in a single step (GitLab Ultimate users only).
Run a policy evaluation against a Sonatype IQ Server instance, and also get the SBOM in a single step.

Usage

Here's a typical usage example that evaluates an npm project against a Sonatype IQ Server instance:

include: - component: $CI_SERVER_FQDN/sonatype-integrations/components/evaluate@main 
  inputs: 
    application-id: iq-app 
    scan-targets: 
      - package.json 
      - package-lock.json

Note
The above example assumes that the IQ Server URL and credentials are provided via pipeline environment variables.
For more details on the supported parameters for each component, refer to the individual component documentation.

Run Policy Evaluation

A GitLab CI component that runs policy evaluations against a Sonatype IQ Server.

Pre-requisites

Even though it is not required, we recommend setting up the following variables in GitLab's CI/CD section of your project or group settings:

Variable Name	Description
`NEXUS_IQ_URL`	IQ Server URL.
`NEXUS_IQ_USERNAME`	IQ Server authentication username.
`NEXUS_IQ_PASSWORD`	IQ Server authentication password.
`NEXUS_IQ_REPORT_FORMAT`	Policy evaluation report format. Default is `enhanced`.

Usage Example

include: - component: $CI_SERVER_FQDN/sonatype-integrations/components/evaluate@main 
  inputs: 
    application-id: iq-app 
    scan-targets: 
      - pom.xml 
    result-file: evaluation-result.json

Parameters

Use the following parameters to configure the component:

Parameter Name	Default Value	Description
`application-id`		ID of the application on the IQ Server. (Required)
`scan-targets`		List of files to scan. Supports Ant-style patterns. (Required)
`server-url`		The location of your IQ Server. If not provided, the `NEXUS_IQ_URL` environment variable will be used instead, if set; otherwise, the execution fails. (Required)
`authentication`		IQ Server credentials, format `username:password`. If not provided, the `NEXUS_IQ_USERNAME` and `NEXUS_IQ_PASSWORD` environment variables will be used instead, if set; otherwise, the execution fails. (Required)
`debug`	`false`	Enable debug logs. WARNING: This may expose sensitive information in the logs. (Optional)
`system-properties`		Set system properties: multiple `key=value` are supported. (Optional)
`fail-on-policy-warnings`	`false`	Fail the build if a policy warning is found. (Optional)
`ignore-system-errors`	`false`	Ignore system errors: IO, network, server, etc. (Optional)
`ignore-scanning-errors`	`false`	Ignore scanning errors: corrupt files or malformed files, etc. (Optional)
`ignore-reachability-errors`	`false`	Ignore reachability analysis errors. If set to true, the pipeline status is not affected by reachability analysis failures. (Optional)
`organization-id`		ID of the organization on the IQ Server. (Optional)
`proxy`		Proxy to use, format `host[:port]`. (Optional)
`proxy-user`		Credentials for the proxy, format `username:password`. (Optional)
`report-format`		Controls the verbosity of policy evaluation reports. If not provided, the `NEXUS_IQ_REPORT_FORMAT` environment variable will be used instead. (Optional)
`result-file`	`scan-result.json`	Name of a JSON file where the results of the policy evaluation will be stored in a machine-readable format. (Optional)
`report-name`	`evaluation-report.html`	Name of the policy evaluation HTML report file. (Optional)
`stage`	`build`	The stage to run analysis against. Options: `source`, `develop`, `build`, `stage-release`, `release`, `operate`. (Optional)

Reachability Analysis Parameters

See Reachability Analysis with Gitlab CI.

Additional Parameters

In addition to the above parameters, you can use the following low-level parameters to further configure the component:

Input	Default Value	Description
`ci-image-registry`	`docker.io`	The specified registry of the underlying job image. (Optional)
`ci-image-name`	`sonatype/gitlab-nexus-iq-pipeline`	The underlying job image name. (Optional)
`ci-image-version`	`latest`	The underlying job image version. (Optional)
`ci-stage`	`test`	The pipeline stage in which this component is executed. (Optional)
`ci-needs`	`[]`	The pipeline job that has to finish before the component execution starts. (Optional)

The name of the job used internally by this component is sonatype-evaluate. It can be used in other jobs' needs clauses and in Sonatype components' ci-needs parameters to enforce an execution order.

A GitLab CI component that creates a vulnerability report based on the results of a Sonatype IQ evaluation. The generated report is also stored as a pipeline artifact.

For GitLab Ultimate customers, the generated file is automatically used to update the Vulnerability Report page, which is part of the GitLab Ultimate Security UI.

Prerequisites

The IQ Server user configured for this component must have the READ and EVALUATE_COMPONENT permissions. In the IQ Server user interface, these correspond to the View IQ Elements and Evaluate Individual Components permissions.

If the same GitLab CI user also runs the policy evaluation step before creating the vulnerability report, the user must also have the EVALUATE_APPLICATION permission. In the IQ Server user interface, this corresponds to the Evaluate Applications permission.

For GitLab CI pipelines, consider creating a custom IQ Server role, such as GitLab CI, containing the permissions required by the pipeline steps you use. A pipeline that runs a policy evaluation, creates a vulnerability report, and fetches an SBOM requires READ, EVALUATE_COMPONENT, and EVALUATE_APPLICATION.

Usage Example

include: - component: $CI_SERVER_FQDN/sonatype-integrations/components/create-vulnerability-report@main 
  inputs: 
    result-file: evaluation-result.json 
    report-file: gitlab-vulnerability-report.json

Parameters

Use the following parameters to configure the component:

Input	Default Value	Description
`server-url`		The location of your IQ Server. If not provided, the `NEXUS_IQ_URL` environment variable will be used instead, if set; otherwise, the execution fails. (Required)
`authentication`		IQ Server credentials, format `username:password`. If not provided, the `NEXUS_IQ_USERNAME` and `NEXUS_IQ_PASSWORD` environment variables will be used instead, if set; otherwise, the execution fails. (Required)
`result-file`		Path to a JSON file where the results of the previous Sonatype IQ evaluation are stored. (Required)
`report-file`		Path to a JSON file where the generated Vulnerability Report will be stored. (Required)

Additional Parameters

In addition to the above parameters, you can use the following low-level parameters to further configure the component: