Container Scanning for Registry

Summary

The Container Scanning for Registry feature enables the automatic execution of a container scanning job whenever a new image is pushed to the GitLab container registry. This feature helps in identifying vulnerabilities in container images early in the development process.

Motivation

Container Scanning scans Docker images when they are created during the pipeline. Images are then stored in the GitLab Container Registry, and can be reused by other pipelines and deployment processes as stable images that will land in production.

Security status can change at any time even if there are no code changes, for example if an unknown vulnerability is disclosed to the public.

Developers and security teams need to know the current security status of the images stored in the GitLab Container Registry. When the advisory database is updated, they need to know when new vulnerabilities apply to existing images. Similarly, they also need to know when new vulnerabilities are introduced when a new image is pushed into the registry.

Goal

The primary goal of the Container Scanning for Registry feature is to enhance the security of containerized applications by automating the scanning process. This involves:

1. Automating the Detection Process: Ensuring that every new image pushed to the GitLab container registry is automatically scanned for vulnerabilities.
2. Early Identification of Vulnerabilities: Detecting and reporting vulnerabilities as soon as they are introduced.
3. Facilitate adoption of Container Scanning: Perform Container Scanning without requiring to configure a CI job in the .gitlab-ci.yml configuration file. A working runner is still required to execute the pipeline.
4. Providing Comprehensive View*: Offering a detailed view of vulnerabilities that are accessible through a dedicated tab on the Vulnerability Report page.

Design and implementation details

How it’s working

1. Trigger: When a new image is pushed to the GitLab container registry, a CI pipeline is automatically created with a container scanning job.
2. Report Generation: The reports generated by this job are marked with the report type container_scanning_for_registry.
3. Vulnerability Reporting: The vulnerabilities identified by this job are displayed under Secure > Vulnerability Report page in Container Registry Vulnerabilities tab.

Implementation Details

Event Triggering

• Event Class: When a new image is pushed to the container registry, an event is fired using the class ContainerRegistryEvent.
  • Source Code: ContainerRegistryEvent

Image Pushed Event

• Condition: If the image tag is a supported tag, the necessary permissions and licenses are present, and the rate limit of 50 images scanned per project has not been exceeded, it publishes another event called ContainerRegistry::ImagePushedEvent.
  • Source Code: ImagePushedEvent

CI Pipeline Creation

• Worker: The ImagePushedEvent triggers the ScanImageWorker, which schedules a CI pipeline via ScanImageService.
  • Source Code: ScanImageService

Container Scanning Tool Configuration

• Environment Variable: Based on the CI environment variable REGISTRY_TRIGGERED: true, the container scanning tool sets the GitLab property name to container_scanning_for_registry in the SBOM (Software Bill of Materials).
  • Source Code: SBOM Converter

Report Ingestion

• Property Check: During report ingestion, the system checks the property type and sets the sbom_occurrence.source_type to container_scanning_for_registry.
  • Source Code: CycloneDX Properties Parser

Vulnerability Creation

• Report Type: During the creation of vulnerabilities, the vulnerability#report_type is set to container_scanning_for_registry based on sbom_occurrence.source_type. This report type filter is used by the frontend to distinguish these vulnerabilities from other types.
  • Source Code: ContainerScanning FindingBuilder

Architecture Diagram

graph TD;
    A[Image Push to GitLab Container Registry] --> B[ContainerRegistryEvent Trigger]
    B --> C[ContainerRegistry::ImagePushedEvent]
    C --> D[ScanImageWorker Starts]
    D --> E[ScanImageService Schedules CI Pipeline]
    E --> F[Container Scanning Job in CI Pipeline]
    F --> G[Set Property container_scanning_for_registry in SBOM]
    G --> H[Report Ingestion Checks Property Type]
    H --> I[Set report_type to container_scanning_for_registry]
    I --> J[Vulnerabilities Displayed in Secure > Vulnerability Report]

    subgraph Container Registry
        A
    end

    subgraph GitLab CI/CD Pipeline
        E
        F
    end

    subgraph Vulnerability Management
        H
        I
        J
    end

This diagram captures the flow from the moment an image is pushed to the registry, through the event handling and CI pipeline, to the reporting and display of vulnerabilities. The various classes and services involved are highlighted at each step, providing a clear overview of the architecture.

Outline of the diagram

1. Image Push Event:

   • When a new image is pushed to the GitLab Container Registry.

2. ContainerRegistryEvent Trigger:

   • The ContainerRegistryEvent class fires an event.

3. ContainerRegistry::ImagePushedEvent:

   • If the image tag is supported and permissions are valid, it triggers ContainerRegistry::ImagePushedEvent.

4. ScanImageWorker:

   • ImagePushedEvent starts ScanImageWorker.

5. ScanImageService:

   • ScanImageWorker schedules a CI pipeline via ScanImageService.

6. Container Scanning Job:

   • CI pipeline includes a container scanning job.

7. SBOM Configuration:

   • Based on REGISTRY_TRIGGERED: true, sets the property container_scanning_for_registry.

8. Report Ingestion:

   • During ingestion, sets report_type to container_scanning_for_registry.

9. Vulnerability Report:

   • Vulnerabilities are displayed in the Secure > Vulnerability Report page under Container Registry Vulnerabilities tab.

View page source - Edit this page - please contribute.