From bd83e3322aad102a2adcb76518dd4f5aa0170804 Mon Sep 17 00:00:00 2001 From: Zamir Martins Filho Date: Thu, 11 Dec 2025 18:25:54 -0500 Subject: [PATCH 1/4] Add documentation for multi image scan --- .../container_scanning/_index.md | 7 + .../multi_container_scanning.md | 246 ++++++++++++++++++ 2 files changed, 253 insertions(+) create mode 100644 doc/user/application_security/container_scanning/multi_container_scanning.md diff --git a/doc/user/application_security/container_scanning/_index.md b/doc/user/application_security/container_scanning/_index.md index 8ff5b923acea0f..d0236c0aee3539 100644 --- a/doc/user/application_security/container_scanning/_index.md +++ b/doc/user/application_security/container_scanning/_index.md @@ -986,6 +986,13 @@ To configure a custom scanner image: The GitLab Security Policy Bot will use the specified image when it triggers a scan. +## Container Scanning options + +GitLab provides two approaches for container scanning: + +- **Standard Container Scanning**: Scan a single container image per job. Best for simple and distributed workflows. +- **[Multi-Container Scanning](multi_container_scanning.md)**: Scan multiple images in parallel using a single configuration file. Best for scanning multiple images efficiently. + ## Vulnerabilities database All analyzer images are [updated daily](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/blob/master/README.md#image-updates). diff --git a/doc/user/application_security/container_scanning/multi_container_scanning.md b/doc/user/application_security/container_scanning/multi_container_scanning.md new file mode 100644 index 00000000000000..e07765429042f6 --- /dev/null +++ b/doc/user/application_security/container_scanning/multi_container_scanning.md @@ -0,0 +1,246 @@ +--- +stage: Application Security Testing +group: Composition Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +title: Multi-Container Scanning +description: Image vulnerability scanning, configuration, customization, and reporting. +--- + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3139) in GitLab 18.7 as an experimental feature. + +Use Multi-Container Scanning to scan multiple container images in a single pipeline. +This feature enables you to: + +- Scan multiple images in parallel +- Configure scanning targets in a single configuration file +- Integrate with existing container scanning workflows + +Multi-Container Scanning uses [dynamic child pipelines](../../../ci/pipelines/downstream_pipelines.md#dynamic-child-pipelines) to run scans +concurrently, reducing overall pipeline execution time. + +## Requirements + +- GitLab Runner with Docker executor +- A `.gitlab-multi-image.yml` configuration file in your repository root +- At least one container image to scan + +## Supported images + +Multi-Container Scanning supports: + +- Images from public registries (Docker Hub, GitLab Container Registry, etc.) +- Images from private registries (with authentication configured) +- Multi-architecture images + +## Enable Multi-Container Scanning + +To enable Multi-Container Scanning: + +1. Create a `.gitlab-multi-image.yml` file in your repository root: + +```yaml + scanTargets: + - name: alpine + tag: latest + - name: python + tag: 3.9-slim +``` + +1. Include the template in your `.gitlab-ci.yml`: + +```yaml + include: + - template: Jobs/Multi-Container-Scanning.latest.gitlab-ci.yml +``` + +1. Commit and push your changes. The pipeline runs the scans automatically. + +## Configuration + +Configure Multi-Container Scanning by editing `.gitlab-multi-image.yml`. + +### Basic configuration + +```yaml +scanTargets: + - name: alpine + tag: "3.19" + - name: ubuntu + tag: "22.04" +``` + +### Complete configuration example + +```yaml +# Include license information in reports +includeLicenses: true + +# Configure registry authentication +auths: + registry.example.com: + username: ${REGISTRY_USER} + password: ${REGISTRY_PASSWORD} + +# Allow insecure connections (not recommended for production) +allowInsecure: false + +# Additional CA certificates for custom registries +additionalCaCertificateBundle: | + -----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE----- + +# Images to scan +scanTargets: + - name: registry.example.com/myapp + tag: "v1.2.3" + - name: postgres + tag: "15-alpine" +``` + +### Configuration options + +| Option | Type | Required | Description | +|--------|------|----------|-------------| +| `scanTargets` | Array | Yes | List of container images to scan | +| `scanTargets[].name` | String | Yes | Image name (with optional registry) | +| `scanTargets[].tag` | String | No | Image tag (default: `latest`) | +| `scanTargets[].registry` | String | No | Registry override | +| `includeLicenses` | Boolean | No | Include license information in reports | +| `auths` | Object | No | Registry authentication credentials | +| `allowInsecure` | Boolean | No | Allow insecure HTTPS connections | +| `additionalCaCertificateBundle` | String | No | Additional CA certificates in PEM format | + +## Common scenarios + +### Scan images from different registries + +```yaml +scanTargets: + - name: docker.io/library/nginx + tag: "1.25" + - name: registry.gitlab.com/mygroup/myapp + tag: "main" + - name: gcr.io/myproject/service + tag: "prod" +``` + +### Use private registry authentication + +```yaml +auths: + registry.gitlab.com: + username: ${CI_REGISTRY_USER} + password: ${CI_REGISTRY_PASSWORD} + docker.io: + username: ${DOCKERHUB_USER} + password: ${DOCKERHUB_TOKEN} + +scanTargets: + - name: registry.gitlab.com/private/image + tag: latest +``` + +### Scan specific versions for compliance + +```yaml +scanTargets: + - name: postgres + tag: "14.10" + - name: redis + tag: "7.2.3" + - name: nginx + tag: "1.25.3" +``` + +## CI/CD variables + +You can customize Multi-Container Scanning behavior with CI/CD variables. + +| Variable | Default | Description | +|----------|---------|-------------| +| `CONTAINER_SCANNING_DISABLED` | - | Set to `true` or `1` to disable scanning | +| `AST_ENABLE_MR_PIPELINES` | `true` | Enable scanning in merge request pipelines | +| `CS_SCANNER_IMAGE` | `registry.gitlab.com/.../multiple-container-scanner:0` | Scanner image to use | + +### Disable Multi-Container Scanning + +To disable scanning temporarily: + +```yaml +variables: + CONTAINER_SCANNING_DISABLED: "true" +``` + +### Disable MR pipeline scanning + +```yaml +variables: + AST_ENABLE_MR_PIPELINES: "false" +``` + +## View scan results + +After the pipeline completes: + +1. Go to your merge request or pipeline details page +1. Select the **Security** tab +1. View detected vulnerabilities from all scanned images + +Each scanned image generates: + +- A container scanning report +- A CycloneDX SBOM (Software Bill of Materials) +- License information (if `includeLicenses: true`) + +### Pipeline structure + +Multi-Container Scanning creates two jobs: + +- `multi-cs::generate-scan`: Generates the scanning configuration +- `multi-cs::trigger-scan`: Triggers a child pipeline with parallel scan jobs + +The child pipeline contains one job per image in `scanTargets`. + +## Troubleshooting + +### Pipeline fails with "configuration file not found" + +**Cause**: The `.gitlab-multi-image.yml` file is missing or in the wrong location. + +**Solution**: Ensure `.gitlab-multi-image.yml` exists in your repository root. + +### Authentication fails for private registry + +**Cause**: Invalid credentials or missing authentication configuration. + +**Solution**: + +1. Verify credentials are correct +1. Use CI/CD variables for sensitive data: + +```yaml + auths: + registry.example.com: + username: ${REGISTRY_USER} + password: ${REGISTRY_PASSWORD} +``` + +1. Define variables in **Settings > CI/CD > Variables** + +### Scan takes too long + +**Cause**: Multiple large images being scanned sequentially. + +**Solution**: Multi-Container Scanning already runs scans in parallel. Consider: + +- Using smaller base images +- Scanning only specific image versions +- Adjusting GitLab Runner concurrency settings + +### Child pipeline doesn't show reports + +**Cause**: Missing `strategy: mirror` in trigger configuration. + +**Solution**: This is configured by default in the template. If you've customized +the template, ensure the trigger job includes `strategy: mirror`. -- GitLab From 360fdc50d47954e8bb1be352be545c03010d408e Mon Sep 17 00:00:00 2001 From: Zamir Martins Date: Fri, 12 Dec 2025 16:06:34 -0500 Subject: [PATCH 2/4] Apply a good amount of changes proposed by the reviewer --- .../container_scanning/_index.md | 6 +- .../multi_container_scanning.md | 89 ++++++++++--------- 2 files changed, 51 insertions(+), 44 deletions(-) diff --git a/doc/user/application_security/container_scanning/_index.md b/doc/user/application_security/container_scanning/_index.md index d0236c0aee3539..06f89db3911b80 100644 --- a/doc/user/application_security/container_scanning/_index.md +++ b/doc/user/application_security/container_scanning/_index.md @@ -986,12 +986,12 @@ To configure a custom scanner image: The GitLab Security Policy Bot will use the specified image when it triggers a scan. -## Container Scanning options +## Optimization GitLab provides two approaches for container scanning: -- **Standard Container Scanning**: Scan a single container image per job. Best for simple and distributed workflows. -- **[Multi-Container Scanning](multi_container_scanning.md)**: Scan multiple images in parallel using a single configuration file. Best for scanning multiple images efficiently. +- **Standard container scanning**: Scan a single container image per job. Best for simple and distributed workflows. +- **[Multi-container scanning](multi_container_scanning.md)**: Scan multiple images in parallel using a single configuration file. Best for scanning multiple images efficiently. ## Vulnerabilities database diff --git a/doc/user/application_security/container_scanning/multi_container_scanning.md b/doc/user/application_security/container_scanning/multi_container_scanning.md index e07765429042f6..67c4c86e29bcba 100644 --- a/doc/user/application_security/container_scanning/multi_container_scanning.md +++ b/doc/user/application_security/container_scanning/multi_container_scanning.md @@ -2,13 +2,13 @@ stage: Application Security Testing group: Composition Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments -title: Multi-Container Scanning +title: Multi-container scanning description: Image vulnerability scanning, configuration, customization, and reporting. --- -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3139) in GitLab 18.7 as an experimental feature. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3139) as an [experiment](../../policy/development_stages_support.md) in GitLab 18.7. -Use Multi-Container Scanning to scan multiple container images in a single pipeline. +Use Multi-container scanning to scan multiple container images in a single pipeline. This feature enables you to: - Scan multiple images in parallel @@ -18,48 +18,48 @@ This feature enables you to: Multi-Container Scanning uses [dynamic child pipelines](../../../ci/pipelines/downstream_pipelines.md#dynamic-child-pipelines) to run scans concurrently, reducing overall pipeline execution time. -## Requirements - -- GitLab Runner with Docker executor -- A `.gitlab-multi-image.yml` configuration file in your repository root -- At least one container image to scan - ## Supported images -Multi-Container Scanning supports: +Multi-container scanning supports: -- Images from public registries (Docker Hub, GitLab Container Registry, etc.) +- Images from public registries (Docker Hub, GitLab Container Registry, and others) - Images from private registries (with authentication configured) - Multi-architecture images -## Enable Multi-Container Scanning +## Enable multi-container scanning + +Prerequisites: + +- GitLab Runner with Docker executor. +- A `.gitlab-multi-image.yml` configuration file in your repository root. +- At least one container image to scan. -To enable Multi-Container Scanning: +To enable Multi-container scanning: 1. Create a `.gitlab-multi-image.yml` file in your repository root: -```yaml - scanTargets: - - name: alpine - tag: latest - - name: python - tag: 3.9-slim -``` + ```yaml + scanTargets: + - name: alpine + tag: latest + - name: python + tag: 3.9-slim + ``` 1. Include the template in your `.gitlab-ci.yml`: -```yaml - include: - - template: Jobs/Multi-Container-Scanning.latest.gitlab-ci.yml -``` + ```yaml + include: + - template: Jobs/Multi-Container-Scanning.latest.gitlab-ci.yml + ``` 1. Commit and push your changes. The pipeline runs the scans automatically. ## Configuration -Configure Multi-Container Scanning by editing `.gitlab-multi-image.yml`. +Configure multi-container scanning by editing the `.gitlab-multi-image.yml` file. -### Basic configuration +### Basic configuration example ```yaml scanTargets: @@ -113,6 +113,8 @@ scanTargets: ## Common scenarios +The following sections describe some example scenarios that you can adapt to suit your needs. + ### Scan images from different registries ```yaml @@ -155,7 +157,7 @@ scanTargets: ## CI/CD variables -You can customize Multi-Container Scanning behavior with CI/CD variables. +You can customize multi-container scanning behavior by using CI/CD variables. | Variable | Default | Description | |----------|---------|-------------| @@ -163,7 +165,7 @@ You can customize Multi-Container Scanning behavior with CI/CD variables. | `AST_ENABLE_MR_PIPELINES` | `true` | Enable scanning in merge request pipelines | | `CS_SCANNER_IMAGE` | `registry.gitlab.com/.../multiple-container-scanner:0` | Scanner image to use | -### Disable Multi-Container Scanning +### Disable multi-container scanning To disable scanning temporarily: @@ -183,9 +185,10 @@ variables: After the pipeline completes: -1. Go to your merge request or pipeline details page -1. Select the **Security** tab -1. View detected vulnerabilities from all scanned images +1. On the top bar, select **Search or go to** and find your project. +1. Go to your merge request or pipeline details page. +1. Select the **Security** tab. +1. View detected vulnerabilities from all scanned images. Each scanned image generates: @@ -195,7 +198,7 @@ Each scanned image generates: ### Pipeline structure -Multi-Container Scanning creates two jobs: +Multi-container scanning creates two jobs: - `multi-cs::generate-scan`: Generates the scanning configuration - `multi-cs::trigger-scan`: Triggers a child pipeline with parallel scan jobs @@ -204,6 +207,8 @@ The child pipeline contains one job per image in `scanTargets`. ## Troubleshooting +When working with multi-container scanning, you might encounter the following issues. + ### Pipeline fails with "configuration file not found" **Cause**: The `.gitlab-multi-image.yml` file is missing or in the wrong location. @@ -216,23 +221,25 @@ The child pipeline contains one job per image in `scanTargets`. **Solution**: -1. Verify credentials are correct +1. Verify credentials are correct. 1. Use CI/CD variables for sensitive data: -```yaml - auths: - registry.example.com: - username: ${REGISTRY_USER} - password: ${REGISTRY_PASSWORD} -``` + ```yaml + auths: + registry.example.com: + username: ${REGISTRY_USER} + password: ${REGISTRY_PASSWORD} + ``` -1. Define variables in **Settings > CI/CD > Variables** +1. Define variables in **Settings** > **CI/CD > **Variables**. ### Scan takes too long **Cause**: Multiple large images being scanned sequentially. -**Solution**: Multi-Container Scanning already runs scans in parallel. Consider: +**Solution**: Multi-container scanning already runs scans in parallel. + +Consider: - Using smaller base images - Scanning only specific image versions -- GitLab From aedce74c8655a30c91afed8099844964fc4c6f20 Mon Sep 17 00:00:00 2001 From: Zamir Martins Filho Date: Fri, 12 Dec 2025 17:17:19 -0500 Subject: [PATCH 3/4] Address reviewer's comments and suggestions --- .../container_scanning/_index.md | 14 +++++----- .../multi_container_scanning.md | 26 +++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/doc/user/application_security/container_scanning/_index.md b/doc/user/application_security/container_scanning/_index.md index 06f89db3911b80..4f881c602e0626 100644 --- a/doc/user/application_security/container_scanning/_index.md +++ b/doc/user/application_security/container_scanning/_index.md @@ -177,6 +177,13 @@ Additional ways to see container scanning results: - [Vulnerability report](../vulnerability_report/_index.md): Shows confirmed vulnerabilities on the default branch. - [Container scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscontainer_scanning) +## Optimization + +GitLab provides two approaches for container scanning: + +- **Standard container scanning**: Scan a single container image per job. Best for simple and distributed workflows. +- **[Multi-container scanning](multi_container_scanning.md)**: Scan multiple images in parallel using a single configuration file. Best for scanning multiple images efficiently. + ## Roll out After you are confident in the container scanning results for a single project, you can extend its implementation to additional projects: @@ -986,13 +993,6 @@ To configure a custom scanner image: The GitLab Security Policy Bot will use the specified image when it triggers a scan. -## Optimization - -GitLab provides two approaches for container scanning: - -- **Standard container scanning**: Scan a single container image per job. Best for simple and distributed workflows. -- **[Multi-container scanning](multi_container_scanning.md)**: Scan multiple images in parallel using a single configuration file. Best for scanning multiple images efficiently. - ## Vulnerabilities database All analyzer images are [updated daily](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/blob/master/README.md#image-updates). diff --git a/doc/user/application_security/container_scanning/multi_container_scanning.md b/doc/user/application_security/container_scanning/multi_container_scanning.md index 67c4c86e29bcba..bed52d2b93c538 100644 --- a/doc/user/application_security/container_scanning/multi_container_scanning.md +++ b/doc/user/application_security/container_scanning/multi_container_scanning.md @@ -6,7 +6,7 @@ title: Multi-container scanning description: Image vulnerability scanning, configuration, customization, and reporting. --- -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3139) as an [experiment](../../policy/development_stages_support.md) in GitLab 18.7. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3139) as an [experiment](../../../policy/development_stages_support.md) in GitLab 18.7. Use Multi-container scanning to scan multiple container images in a single pipeline. This feature enables you to: @@ -15,8 +15,9 @@ This feature enables you to: - Configure scanning targets in a single configuration file - Integrate with existing container scanning workflows -Multi-Container Scanning uses [dynamic child pipelines](../../../ci/pipelines/downstream_pipelines.md#dynamic-child-pipelines) to run scans -concurrently, reducing overall pipeline execution time. +Multi-container scanning uses +[dynamic child pipelines](../../../ci/pipelines/downstream_pipelines.md#dynamic-child-pipelines) to +run scans concurrently, reducing overall pipeline execution time. ## Supported images @@ -211,18 +212,17 @@ When working with multi-container scanning, you might encounter the following is ### Pipeline fails with "configuration file not found" -**Cause**: The `.gitlab-multi-image.yml` file is missing or in the wrong location. +Cause: The `.gitlab-multi-image.yml` file is missing or in the wrong location. -**Solution**: Ensure `.gitlab-multi-image.yml` exists in your repository root. +Solution: Ensure `.gitlab-multi-image.yml` exists in your repository root. ### Authentication fails for private registry -**Cause**: Invalid credentials or missing authentication configuration. +Cause: Invalid credentials or missing authentication configuration. -**Solution**: +Solution: -1. Verify credentials are correct. -1. Use CI/CD variables for sensitive data: +1. Verify that credentials are correct and configured correctly. ```yaml auths: @@ -235,9 +235,9 @@ When working with multi-container scanning, you might encounter the following is ### Scan takes too long -**Cause**: Multiple large images being scanned sequentially. +Cause: Multiple large images being scanned sequentially. -**Solution**: Multi-container scanning already runs scans in parallel. +Solution: Multi-container scanning already runs scans in parallel. Consider: @@ -247,7 +247,7 @@ Consider: ### Child pipeline doesn't show reports -**Cause**: Missing `strategy: mirror` in trigger configuration. +Cause: Missing `strategy: mirror` in trigger configuration. -**Solution**: This is configured by default in the template. If you've customized +Solution: This is configured by default in the template. If you've customized the template, ensure the trigger job includes `strategy: mirror`. -- GitLab From cac33bd273908154413c7e5e4682a260601009f5 Mon Sep 17 00:00:00 2001 From: Russell Dickenson Date: Sat, 13 Dec 2025 20:05:38 +1000 Subject: [PATCH 4/4] Apply 5 suggestion(s) to 2 file(s) --- .../container_scanning/_index.md | 4 ++-- .../multi_container_scanning.md | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/user/application_security/container_scanning/_index.md b/doc/user/application_security/container_scanning/_index.md index 4f881c602e0626..391cd6c6326795 100644 --- a/doc/user/application_security/container_scanning/_index.md +++ b/doc/user/application_security/container_scanning/_index.md @@ -181,8 +181,8 @@ Additional ways to see container scanning results: GitLab provides two approaches for container scanning: -- **Standard container scanning**: Scan a single container image per job. Best for simple and distributed workflows. -- **[Multi-container scanning](multi_container_scanning.md)**: Scan multiple images in parallel using a single configuration file. Best for scanning multiple images efficiently. +- Standard container scanning: Scan a single container image per job. Best for simple and distributed workflows. +- [Multi-container scanning](multi_container_scanning.md): Scan multiple images in parallel using a single configuration file. Best for scanning multiple images efficiently. ## Roll out diff --git a/doc/user/application_security/container_scanning/multi_container_scanning.md b/doc/user/application_security/container_scanning/multi_container_scanning.md index bed52d2b93c538..bdd31fb156d140 100644 --- a/doc/user/application_security/container_scanning/multi_container_scanning.md +++ b/doc/user/application_security/container_scanning/multi_container_scanning.md @@ -8,12 +8,12 @@ description: Image vulnerability scanning, configuration, customization, and rep > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3139) as an [experiment](../../../policy/development_stages_support.md) in GitLab 18.7. -Use Multi-container scanning to scan multiple container images in a single pipeline. +Use multi-container scanning to scan multiple container images in a single pipeline. This feature enables you to: -- Scan multiple images in parallel -- Configure scanning targets in a single configuration file -- Integrate with existing container scanning workflows +- Scan multiple images in parallel. +- Configure scanning targets in a single configuration file. +- Integrate with existing container scanning workflows. Multi-container scanning uses [dynamic child pipelines](../../../ci/pipelines/downstream_pipelines.md#dynamic-child-pipelines) to @@ -35,7 +35,7 @@ Prerequisites: - A `.gitlab-multi-image.yml` configuration file in your repository root. - At least one container image to scan. -To enable Multi-container scanning: +To enable multi-container scanning: 1. Create a `.gitlab-multi-image.yml` file in your repository root: @@ -193,9 +193,9 @@ After the pipeline completes: Each scanned image generates: -- A container scanning report -- A CycloneDX SBOM (Software Bill of Materials) -- License information (if `includeLicenses: true`) +- A container scanning report. +- A CycloneDX SBOM (Software Bill of Materials). +- License information (if `includeLicenses: true`). ### Pipeline structure -- GitLab