# CI Components - Sonatype for GitLab CI

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

- [Run a policy evaluation](https://help.sonatype.com/en/ci-components---sonatype-for-gitlab-ci.html#run-policy-evaluation "Run Policy Evaluation") against a Sonatype IQ Server instance.
- [Create a vulnerability report](https://help.sonatype.com/en/ci-components---sonatype-for-gitlab-ci.html#-282180 " ") based on a previous policy evaluation.
- [Fetch a Software Bill of Materials (SBOM)](https://help.sonatype.com/en/ci-components---sonatype-for-gitlab-ci.html#fetch-a-software-bill-of-materials--sbom- "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](https://help.sonatype.com/en/ci-components---sonatype-for-gitlab-ci.html#run-policy-evaluation---gitlab-ultimate "Run Policy Evaluation - GitLab Ultimate") 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](https://help.sonatype.com/en/ci-components---sonatype-for-gitlab-ci.html#run-policy-evaluation-and-fetch-sbom "Run Policy Evaluation and Fetch SBOM") 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](https://help.sonatype.com/en/reachability-analysis-with-gitlab-ci.html#using-java-reachability-analysis-450772 "Using Java Reachability Analysis").

### 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: