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)
`callflow-analysis`	`false`	Runs callflow analysis. (Optional)
`callflow-analysis-namespaces`		Runs callflow analysis for the given namespaces. (Optional)
`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)
`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)

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

Create Vulnerability Report

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.

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.

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:

Input	Default Value	Description
`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`	`["sonatype-evaluation"]`	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-vulnerability-report. It can be used in other jobs' needs clauses and in Sonatype components' ci-needs parameters to enforce an execution order.

Fetch a Software Bill of Materials (SBOM)

A GitLab pipeline component for retrieving a Software Bill of Materials (SBOM) associated with a Sonatype IQ Server evaluation. It supports both CycloneDX and SPDX standards.

The downloaded SBOM file is stored as a pipeline artifact and is named using the following convention: sbom.<sbom-standard>.<sbom-format>.

For GitLab Ultimate customers, the SBOM file is automatically used to update the Dependency List page, which is part of the GitLab Ultimate Security UI.

Pre-requisites

Even though it is not required, we recommend setting up the following variables in the CI/CD section of your GitLab 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.

Usage Example

include:
  - component: $CI_SERVER_FQDN/sonatype-integrations/components/fetch-sbom@main
    inputs:
      application-id: iq-app
      scan-id: d266e0b80eb24a6c875edb8f3820dbbf
      sbom-version: "1.5" 
      sbom-standard: cycloneDx

Parameters

Use the following parameters to configure the component:

Parameter Name	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)
`application-id`		ID of the application on the IQ Server. (Required)
`scan-id`		ID of the IQ Server scan. (Required)
`sbom-standard`		The SBOM standard: `spdx` or `cycloneDx`. (Required)
`sbom-version`		The version of the SBOM (Available CycloneDX Versions: `1.2`, `1.3`, `1.4`, `1.5`, and `1.6`. Available SPDX version: 2.3). (Required)
`sbom-format`	`json`	Accepted values: `json`, `xml`. (Optional)
`update-dependency-list`	`false`	Enhance the SBOM with metadata needed for GitLab's Dependency List feature. Defaults to false if not provided. (Optional)

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-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-fetch-sbom. It can be used in other jobs' needs clauses and in Sonatype components' ci-needs parameters to enforce an execution order.

Run Policy Evaluation - GitLab Ultimate

A GitLab CI component that runs policy evaluations against a Sonatype IQ Server, and also generates the vulnerability report and retrieves the Software Bill of Materials (SBOM) in a single step.

The vulnerability report and SBOM are automatically used to update the Vulnerability Report and Dependency List pages, which are part of the GitLab Ultimate Security UI. Both files are also stored as artifacts and can be viewed or downloaded from the GitLab UI, with the vulnerability report named vulnerability-report.json and the SBOM named sbom-cdx.json, respectively.

The retrieved SBOM is a CycloneDX file, version 1.6, in JSON format, which is the most recent version supported by GitLab for Dependency List updates.

Pre-requisites

Even though it is not required, we recommend setting up the following variables in the CI/CD section of your GitLab 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-ultimate@main
    inputs:
      application-id: iq-app
      scan-targets:
        - package.json
        - package-lock.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)
`callflow-analysis`	`false`	Runs callflow analysis. (Optional)
`callflow-analysis-namespaces`		Runs callflow analysis for the given namespaces. (Optional)
`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)
`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)

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-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)

Run Policy Evaluation and Fetch SBOM

A GitLab CI component that runs policy evaluations against a Sonatype IQ Server and uploads the Software Bill of Materials (SBOM) as an artifact.

This component is particularly useful for customers who are not on the GitLab Ultimate tier. For those who are GitLab Ultimate customers, this component serves as a better alternative.

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-sbom@main
    inputs:
      application-id: iq-app
      scan-targets:
        - pom.xml
      result-file: evaluation-result.json
      sbom-standard: cycloneDx
      sbom-version: "1.5"

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)
`callflow-analysis`	`false`	Runs callflow analysis. (Optional)
`callflow-analysis-namespaces`		Runs callflow analysis for the given namespaces. (Optional)
`debug`	`false`	Enable debug logs. WARNING: This may expose sensitive information in the logs. (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)
`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)
`system-properties`		Set system properties: multiple `key=value` are supported. (Optional)
`sbom-standard`		The SBOM standard: `spdx` or `cycloneDx`. (Required)
`sbom-version`		The version of the SBOM (Available CycloneDX Versions: `1.2`, `1.3`, `1.4`, `1.5`, and `1.6`. Available SPDX version: 2.3). (Required)
`sbom-format`	`json`	Accepted values: `json`, `xml`. (Optional)

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-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)

CI Components - Sonatype for GitLab CI

Usage

Run Policy Evaluation

Pre-requisites

Usage Example

Parameters

Additional Parameters

Create Vulnerability Report

Pre-requisites

Usage Example

Parameters

Additional Parameters

Fetch a Software Bill of Materials (SBOM)

Pre-requisites

Usage Example

Parameters

Additional Parameters

Run Policy Evaluation - GitLab Ultimate

Pre-requisites

Usage Example

Parameters

Additional Parameters

Run Policy Evaluation and Fetch SBOM

Usage Example

Parameters

Additional Parameters

Search results