Merge branch '330712-add-running-container-scanning-template' into 'master'

Add Cluster Image Scanning CI Template

See merge request gitlab-org/gitlab!64220

doc/development/integrations/secure.md

@@ -29,7 +29,13 @@ in the [CI documentation](../../ci/yaml/index.md#image).
 
 For consistency, scanning jobs should be named after the scanner, in lower case.
 The job name is suffixed after the type of scanning:
-`_dependency_scanning`,  `_container_scanning`, `_dast`, and `_sast`.
+
+- `_dependency_scanning`
+- `_cluster_image_scanning`
+- `_container_scanning`
+- `_dast`
+- `_sast`
+
 For instance, the dependency scanning job based on the "MySec" scanner would be named `mysec_dependency_scanning`.
 
 ### Image
@@ -69,7 +75,15 @@ so the [`allow_failure`](../../ci/yaml/index.md#allow_failure) parameter should
 
 Scanning jobs must declare a report that corresponds to the type of scanning they perform,
 using the [`artifacts:reports`](../../ci/yaml/index.md#artifactsreports) keyword.
-Valid reports are: `dependency_scanning`, `container_scanning`, `dast`, `api_fuzzing`, `coverage_fuzzing`, and `sast`.
+Valid reports are:
+
+- `dependency_scanning`
+- `container_scanning`
+- `cluster_image_scanning`
+- `dast`
+- `api_fuzzing`
+- `coverage_fuzzing`
+- `sast`
 
 For example, here is the definition of a SAST job that generates a file named `gl-sast-report.json`,
 and uploads it as a SAST report:
@@ -90,9 +104,15 @@ it's declared under the `reports:sast` key in the job definition, not because of
 
 Certain GitLab workflows, such as [AutoDevOps](../../topics/autodevops/customize.md#disable-jobs),
 define CI/CD variables to indicate that given scans should be disabled. You can check for this by looking
-for variables such as `DEPENDENCY_SCANNING_DISABLED`, `CONTAINER_SCANNING_DISABLED`,
-`SAST_DISABLED`, and `DAST_DISABLED`. If appropriate based on the scanner type, you should then
-disable running the custom scanner.
+for variables such as:
+
+- `DEPENDENCY_SCANNING_DISABLED`
+- `CONTAINER_SCANNING_DISABLED`
+- `CLUSTER_IMAGE_SCANNING_DISABLED`
+- `SAST_DISABLED`
+- `DAST_DISABLED`
+
+If appropriate based on the scanner type, you should then disable running the custom scanner.
 
 GitLab also defines a `CI_PROJECT_REPOSITORY_LANGUAGES` variable, which provides the list of
 languages in the repository. Depending on this value, your scanner may or may not do something different.
@@ -194,6 +214,19 @@ using the variables `DOCKER_USER` and `DOCKER_PASSWORD`.
 If these are not defined, then the scanner should use
 `CI_REGISTRY_USER` and `CI_REGISTRY_PASSWORD` as default values.
 
+#### Cluster Image Scanning
+
+To be consistent with the official `cluster_image_scanning` for GitLab, scanners must scan the
+Kubernetes cluster whose configuration is given by `KUBECONFIG`.
+
+If you use the `CIS_KUBECONFIG` CI/CD variable, then the
+`KUBECONFIG` variable is ignored and the cluster specified in the
+`CIS_KUBECONFIG` variable is scanned instead. If you don't provide
+the `CIS_KUBECONFIG` CI/CD variable, the value defaults to the value of
+`$KUBECONFIG`. `$KUBECONFIG` is a predefined CI/CD variable configured when the project is assigned to a
+Kubernetes cluster. When multiple contexts are provided in the `KUBECONFIG` variable, the context
+selected as `current-context` will be used to fetch vulnerabilities.
+
 #### Configuration files
 
 While scanners may use `CI_PROJECT_DIR` to load specific configuration files,
@@ -282,7 +315,8 @@ The format is extensively described in the documentation of
 [SAST](../../user/application_security/sast/index.md#reports-json-format),
 [DAST](../../user/application_security/dast/#reports),
 [Dependency Scanning](../../user/application_security/dependency_scanning/index.md#reports-json-format),
-and [Container Scanning](../../user/application_security/container_scanning/index.md#reports-json-format).
+[Container Scanning](../../user/application_security/container_scanning/index.md#reports-json-format),
+and [Cluster Image Scanning](../../user/application_security/cluster_image_scanning/index.md#reports-json-format).
 
 You can find the schemas for these scanners here:
 
@@ -310,7 +344,12 @@ We recommend that you generate a UUID and use it as the `id` field's value.
 #### Category
 
 The value of the `category` field matches the report type:
-`dependency_scanning`, `container_scanning`, `sast`, and  `dast`.
+
+- `dependency_scanning`
+- `cluster_image_scanning`
+- `container_scanning`
+- `sast`
+- `dast`
 
 #### Scanner
 
@@ -480,6 +519,31 @@ so these attributes are mandatory.
 The `image` is also mandatory.
 All other attributes are optional.
 
+#### Cluster Image Scanning
+
+The `location` of a `cluster_image_scanning` vulnerability has a `dependency` field. It also has
+an `operating_system` field. For example, here is the `location` object for a vulnerability
+affecting version `2.50.3-2+deb9u1` of Debian package `glib2.0`:
+
+```json
+{
+    "dependency": {
+        "package": {
+            "name": "glib2.0"
+        },
+    },
+    "version": "2.50.3-2+deb9u1",
+    "operating_system": "debian:9",
+    "image": "index.docker.io/library/nginx:1.18"
+}
+```
+
+The affected package is found when scanning the image of the pod `index.docker.io/library/nginx:1.18`.
+
+The location fingerprint of a Cluster Image Scanning vulnerability combines the
+`operating_system` and the package `name`, so these attributes are mandatory. The `image` is also
+mandatory. All other attributes are optional.
+
 #### SAST
 
 The `location` of a SAST vulnerability must have a `file` and a `start_line` field,

doc/development/integrations/secure_partner_integration.md

@@ -90,6 +90,7 @@ and complete an integration with the Secure stage.
      - Documentation for [SAST reports](../../user/application_security/sast/index.md#reports-json-format).
      - Documentation for [Dependency Scanning reports](../../user/application_security/dependency_scanning/index.md#reports-json-format).
      - Documentation for [Container Scanning reports](../../user/application_security/container_scanning/index.md#reports-json-format).
+     - Documentation for [`cluster_image_scanning` reports](../../user/application_security/cluster_image_scanning/index.md#reports-json-format).
      - See this [example secure job definition that also defines the artifact created](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml).
      - If you need a new kind of scan or report, [create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new#)
        and add the label `devops::secure`.

doc/user/application_security/container_scanning/index.md

@@ -189,11 +189,6 @@ container_scanning:
     GIT_STRATEGY: fetch
 ```
 
-WARNING:
-GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/index.md#only--except).
-When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules)
-instead.
-
 ### Change scanners
 
 The container-scanning analyzer can use different scanners, depending on the value of the

doc/user/application_security/index.md

@@ -33,16 +33,17 @@ GitLab uses the following tools to scan and report known vulnerabilities found i
 
 | Secure scanning tool                                                         | Description                                                            |
 |:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------|
-| [Container Scanning](container_scanning/index.md) **(ULTIMATE)**             | Scan Docker containers for known vulnerabilities.                      |
-| [Dependency List](dependency_list/index.md) **(ULTIMATE)**                   | View your project's dependencies and their known vulnerabilities.      |
-| [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)**           | Analyze your dependencies for known vulnerabilities.                   |
-| [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)**  | Analyze running web applications for known vulnerabilities.            |
-| [DAST API](dast_api/index.md) **(ULTIMATE)**  | Analyze running web APIs for known vulnerabilities.            |
-| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)**                           | Find unknown bugs and vulnerabilities in web APIs with fuzzing.        |
-| [Secret Detection](secret_detection/index.md)                                | Analyze Git history for leaked secrets.                                |
-| [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)**             | View vulnerabilities in all your projects and groups.                  |
-| [Static Application Security Testing (SAST)](sast/index.md)                  | Analyze source code for known vulnerabilities.                         |
-| [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)**                 | Find unknown bugs and vulnerabilities with coverage-guided fuzzing.    |
+| [Container Scanning](container_scanning/index.md) **(ULTIMATE)**                 | Scan Docker containers for known vulnerabilities.                      |
+| [Dependency List](dependency_list/index.md) **(ULTIMATE)**                       | View your project's dependencies and their known vulnerabilities.      |
+| [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)**               | Analyze your dependencies for known vulnerabilities.                   |
+| [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)**      | Analyze running web applications for known vulnerabilities.            |
+| [DAST API](dast_api/index.md) **(ULTIMATE)**                                     | Analyze running web APIs for known vulnerabilities.            |
+| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)**                               | Find unknown bugs and vulnerabilities in web APIs with fuzzing.        |
+| [Secret Detection](secret_detection/index.md)                                    | Analyze Git history for leaked secrets.                                |
+| [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)**                 | View vulnerabilities in all your projects and groups.                  |
+| [Static Application Security Testing (SAST)](sast/index.md)                      | Analyze source code for known vulnerabilities.                         |
+| [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)**                     | Find unknown bugs and vulnerabilities with coverage-guided fuzzing.    |
+| [Cluster Image Scanning](cluster_image_scanning/index.md) **(ULTIMATE)**         | Scan Kubernetes clusters for known vulnerabilities.                      |
 
 ## Security scanning with Auto DevOps
 

doc/user/application_security/security_dashboard/index.md

@@ -33,6 +33,7 @@ The security dashboard and vulnerability report displays information about vulne
 - [Dynamic Application Security Testing](../dast/index.md)
 - [Dependency Scanning](../dependency_scanning/index.md)
 - [Static Application Security Testing](../sast/index.md)
+- [Cluster Image Scanning](../cluster_image_scanning/index.md)
 - And [others](../index.md#security-scanning-tools)!
 
 ## Prerequisites

doc/user/application_security/terminology/index.md

@@ -118,6 +118,7 @@ The type of scan. This must be one of the following:
 - `dependency_scanning`
 - `dast`
 - `sast`
+- `cluster_image_scanning`
 
 ### Scanner
 

ee/spec/lib/ee/gitlab/template/gitlab_ci_yml_template_spec.rb

@@ -8,6 +8,7 @@ RSpec.describe Gitlab::Template::GitlabCiYmlTemplate do
 
     it 'finds the Security Products templates' do
       expect(templates).to include('Container-Scanning')
+      expect(templates).to include('Cluster-Image-Scanning')
       expect(templates).to include('DAST')
       expect(templates).to include('Dependency-Scanning')
       expect(templates).to include('License-Scanning')

ee/spec/lib/gitlab/ci/templates/cluster_image_scanning_gitlab_ci_yaml_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'Cluster-Image-Scanning.gitlab-ci.yml' do
+  subject(:template) { Gitlab::Template::GitlabCiYmlTemplate.find('Cluster-Image-Scanning') }
+
+  describe 'the created pipeline' do
+    let_it_be(:project) { create(:project, :custom_repo, files: { 'README.txt' => '' }) }
+
+    let(:default_branch) { 'master' }
+    let(:user) { project.owner }
+    let(:service) { Ci::CreatePipelineService.new(project, user, ref: 'master' ) }
+    let(:pipeline) { service.execute!(:push) }
+    let(:build_names) { pipeline.builds.pluck(:name) }
+
+    before do
+      stub_ci_pipeline_yaml_file(template.content)
+      allow_next_instance_of(Ci::BuildScheduleWorker) do |worker|
+        allow(worker).to receive(:perform).and_return(true)
+      end
+      allow(project).to receive(:default_branch).and_return(default_branch)
+      create(:ci_variable, project: project, key: 'CIS_KUBECONFIG', value: '*')
+    end
+
+    context 'when project has no license' do
+      it 'includes no jobs' do
+        expect { pipeline }.to raise_error(Ci::CreatePipelineService::CreateError)
+      end
+    end
+
+    context 'when project has Ultimate license' do
+      let(:license) { build(:license, plan: License::ULTIMATE_PLAN) }
+
+      before do
+        allow(License).to receive(:current).and_return(license)
+      end
+
+      context 'by default' do
+        it 'includes job' do
+          expect(build_names).to match_array(%w[cluster_image_scanning])
+        end
+      end
+
+      context 'with CIS_MAJOR_VERSION greater than 3' do
+        before do
+          create(:ci_variable, project: project, key: 'CIS_MAJOR_VERSION', value: '4')
+        end
+
+        it 'includes job' do
+          expect(build_names).to match_array(%w[cluster_image_scanning])
+        end
+      end
+
+      context 'when CLUSTER_IMAGE_SCANNING_DISABLED=1' do
+        before do
+          create(:ci_variable, project: project, key: 'CLUSTER_IMAGE_SCANNING_DISABLED', value: '1')
+        end
+
+        it 'includes no jobs' do
+          expect { pipeline }.to raise_error(Ci::CreatePipelineService::CreateError)
+        end
+      end
+    end
+  end
+end

lib/gitlab/ci/templates/Security/Cluster-Image-Scanning.gitlab-ci.yml

+# Use this template to enable cluster image scanning in your project.
+# You should add this template to an existing `.gitlab-ci.yml` file by using the `include:`
+# keyword.
+# The template should work without modifications but you can customize the template settings if
+# needed: https://docs.gitlab.com/ee/user/application_security/cluster_image_scanning/#customize-the-container-scanning-settings
+#
+# Requirements:
+# - A `test` stage to be present in the pipeline.
+# - You must define the `CIS_KUBECONFIG` variable to allow analyzer to connect to your Kubernetes cluster and fetch found vulnerabilities.
+#
+# Configure container scanning with CI/CD variables (https://docs.gitlab.com/ee/ci/variables/README.html).
+# List of available variables: https://docs.gitlab.com/ee/user/application_security/cluster_image_scanning/#available-variables
+
+variables:
+  CIS_ANALYZER_IMAGE: registry.gitlab.com/gitlab-org/security-products/analyzers/cluster-image-scanning:0
+
+cluster_image_scanning:
+  image: "$CIS_ANALYZER_IMAGE"
+  stage: test
+  allow_failure: true
+  artifacts:
+    reports:
+      cluster_image_scanning: gl-cluster-image-scanning-report.json
+    paths: [gl-cluster-image-scanning-report.json]
+  dependencies: []
+  script:
+    - /analyzer run
+  rules:
+    - if: $CLUSTER_IMAGE_SCANNING_DISABLED
+      when: never
+    - if: '($KUBECONFIG == null || $KUBECONFIG == "") && ($CIS_KUBECONFIG == null || $CIS_KUBECONFIG == "")'
+      when: never
+    - if: $CI_COMMIT_BRANCH &&
+          $GITLAB_FEATURES =~ /\bcluster_image_scanning\b/