diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 9c8e15f7614b51b6c63034335b7a3fc205b6a07f..8d24c53d352f26c1529b4fd4bfb3677331585dcd 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -158,6 +158,7 @@ The following API resources are available outside of project and group contexts | [Code snippets](snippets.md) | `/snippets` | | [Code suggestions](code_suggestions.md) | `/code_suggestions` | | [Custom attributes](custom_attributes.md) | `/users/:id/custom_attributes` (also available for groups and projects) | +| [Dependency list exports](dependency_list_export.md) **(ULTIMATE ALL)** | `/pipelines/:id/dependency_list_exports`, `/projects/:id/dependency_list_exports`, `/groups/:id/dependency_list_exports`, `/security/dependency_list_exports/:id`, `/security/dependency_list_exports/:id/download` | | [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) | | [Deploy tokens](deploy_tokens.md) | `/deploy_tokens` (also available for projects and groups) | | [Events](events.md) | `/events`, `/users/:id/events` (also available for projects) | diff --git a/doc/api/dependency_list_export.md b/doc/api/dependency_list_export.md new file mode 100644 index 0000000000000000000000000000000000000000..79bf5f1a68f4b284177d6b8579aba6489f47deab --- /dev/null +++ b/doc/api/dependency_list_export.md @@ -0,0 +1,149 @@ +--- +stage: Govern +group: Threat Insights +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Dependency list export API **(ULTIMATE ALL)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333463) in GitLab 16.4. + +Every call to this endpoint requires authentication. + +## Create a pipeline-level dependency list export + +Create a new CycloneDX JSON export for all the project dependencies detected in a pipeline. + +If an authenticated user doesn't have permission to +[read_dependency](../user/permissions.md#custom-role-requirements), +this request returns a `403 Forbidden` status code. + +SBOM exports can be only accessed by the export's author. + +```plaintext +POST /pipelines/:id/dependency_list_exports +``` + +| Attribute | Type | Required | Description | +| ------------------- | ----------------- | ---------- | -----------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of the pipeline which the authenticated user has access to. | +| `export_type` | string | yes | This must be set to `sbom`. | + +```shell +curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/pipelines/1/dependency_list_exports" --data "export_type=sbom" +``` + +The created dependency list export is automatically deleted after 1 hour. + +Example response: + +```json +{ + "id": 2, + "has_finished": false, + "self": "http://gitlab.example.com/api/v4/dependency_list_exports/2", + "download": "http://gitlab.example.com/api/v4/dependency_list_exports/2/download" +} +``` + +## Get single dependency list export + +Get a single dependency list export. + +```plaintext +GET /security/dependency_list_exports/:id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the dependency list export. | + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/security/dependency_list_exports/2" +``` + +The status code is `202 Accepted` when the dependency list export is being generated, and `200 OK` when it's ready. + +Example response: + +```json +{ + "id": 4, + "has_finished": true, + "self": "http://gitlab.example.com/api/v4/dependency_list_exports/4", + "download": "http://gitlab.example.com/api/v4/dependency_list_exports/4/download" +} +``` + +## Download dependency list export + +Download a single dependency list export. + +```plaintext +GET /security/dependency_list_exports/:id/download +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the dependency list export. | + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/security/dependency_list_exports/2/download" +``` + +The response is `404 Not Found` if the dependency list export is not finished yet or was not found. + +Example response: + +```json +{ + "bomFormat": "CycloneDX", + "specVersion": "1.4", + "serialNumber": "urn:uuid:aec33827-20ae-40d0-ae83-18ee846364d2", + "version": 1, + "metadata": { + "tools": [ + { + "vendor": "Gitlab", + "name": "Gemnasium", + "version": "2.34.0" + } + ], + "authors": [ + { + "name": "Gitlab", + "email": "support@gitlab.com" + } + ], + "properties": [ + { + "name": "gitlab:dependency_scanning:input_file", + "value": "package-lock.json" + } + ] + }, + "components": [ + { + "name": "com.fasterxml.jackson.core/jackson-core", + "purl": "pkg:maven/com.fasterxml.jackson.core/jackson-core@2.9.2", + "version": "2.9.2", + "type": "library", + "licenses": [ + { + "license": { + "id": "MIT", + "url": "https://spdx.org/licenses/MIT.html" + } + }, + { + "license": { + "id": "BSD-3-Clause", + "url": "https://spdx.org/licenses/BSD-3-Clause.html" + } + } + ] + } + ] +} + +``` diff --git a/doc/tutorials/export_sbom.md b/doc/tutorials/export_sbom.md new file mode 100644 index 0000000000000000000000000000000000000000..cbbb1421283f726ade7807de41ef9d42965f57f7 --- /dev/null +++ b/doc/tutorials/export_sbom.md @@ -0,0 +1,95 @@ +--- +stage: Secure +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Tutorial: Export dependency list in SBOM format **(ULTIMATE ALL)** + +Dependency Scanning output can be exported to the CycloneDX JSON format. + +This tutorial shows you how to generate a CycloneDX JSON SBOM for a pipeline, and then to upload it as a CI job artifact. + +## Prerequisites + +Set up Dependency Scanning. For detailed instructions, follow [the Dependency Scanning tutorial](dependency_scanning.md). + +## Create configuration files + +1. Create a [snippet](../api/snippets.md) with the following code. + + Filename: `export.sh` + + ```shell + #! /bin/sh + + function create_export { + curl --silent \ + --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" \ + -X 'POST' --data "export_type=sbom" \ + "http://gitlab.localdev:3000/api/v4/pipelines/$CI_PIPELINE_ID/dependency_list_exports" \ + | jq '.id' + } + + function check_status { + curl --silent \ + --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" \ + --write-out "%{http_code}" --output /dev/null \ + http://gitlab.localdev:3000/api/v4/dependency_list_exports/$1 + } + + function download { + curl --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" \ + --output "gl-sbom-merged-$CI_PIPELINE_ID.cdx.json" \ + "http://gitlab.localdev:3000/api/v4/dependency_list_exports/$1/download" + } + + function export_sbom { + local ID=$(create_export) + + for run in $(seq 0 3); do + local STATUS=$(check_status $ID) + # Status is 200 when JSON is generated. + # Status is 202 when generate JSON job is running. + if [ $STATUS -eq "200" ]; then + download $ID + + exit 0 + elif [ $STATUS -ne "202" ]; then + exit 1 + fi + + echo "Waiting for JSON to be generated" + sleep 5 + done + + exit 1 + } + + export_sbom + ``` + + The above script works in the following steps: + + 1. Create a CycloneDX SBOM export for the current pipeline. + 1. Check the status of that export, and stop when it's ready. + 1. Download the CycloneDX SBOM file. + +1. Update `.gitlab-ci.yml` with the following code. + + ```yaml + export-merged-sbom: + before_script: + - apk add --update jq curl + stage: .post + script: + - curl --output export.sh --url "https://gitlab.example.com/api/v4/snippets//raw" + - /bin/sh export.sh + artifacts: + paths: + - "gl-sbom-merged-*.cdx.json" + ``` + +1. Go to **Build > Pipelines** and confirm that the latest pipeline completed successfully. + +In the job artifacts, `gl-sbom-merged-.cdx.json` file should be present. diff --git a/doc/tutorials/secure_application.md b/doc/tutorials/secure_application.md index 54235d0a6dca682837aa32e0a925b940f25a1a7b..96a4107e36c30ca6eac1f1b60494bee9dd86ec9d 100644 --- a/doc/tutorials/secure_application.md +++ b/doc/tutorials/secure_application.md @@ -11,6 +11,7 @@ GitLab can check your application for security vulnerabilities and that it meets | Topic | Description | Good for beginners | |-------|-------------|--------------------| | [Set up dependency scanning](dependency_scanning.md) | Learn how to detect vulnerabilities in an application's dependencies. | **{star}** | +| [Export Dependency List in SBOM format](export_sbom.md) | Learn how to export an application's dependencies to the CycloneDX SBOM format. | **{star}** | | [Create a compliance pipeline](compliance_pipeline/index.md) | Learn how to create compliance pipelines for your groups. | **{star}** | | [Set up a scan result policy](scan_result_policy/index.md) | Learn how to configure a scan result policy that takes action based on scan results. | **{star}** | | [Scan a Docker container for vulnerabilities](container_scanning/index.md) | Learn how to use container scanning templates to add container scanning to your projects. | **{star}** | diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 481fc7748857f5c00a5153442978adf5b0d13b4c..dbad5ff9c11691bce685ea2d738fd7bea17e3358 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -117,4 +117,10 @@ You can download your group's or project's list of dependencies and their detail ### Using the API +#### List project Dependencies + You can download your project's list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the [Gemnasium family of analyzers](../dependency_scanning/index.md#dependency-analyzers) and not any other of the GitLab dependency analyzers. + +#### Export pipeline dependency list + +You can download your project's list of dependencies identified in a pipeline [using the API](../../../api/dependency_list_export.md).