diff options
Diffstat (limited to 'doc/user/application_security/container_scanning/index.md')
| -rw-r--r-- | doc/user/application_security/container_scanning/index.md | 146 |
1 files changed, 67 insertions, 79 deletions
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 093780f36db..21a4155df40 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -8,35 +8,28 @@ type: reference, howto ## Overview -If you are using [GitLab CI/CD](../../../ci/README.md), you can check your Docker -images (or more precisely the containers) for known vulnerabilities by using -[Clair](https://github.com/quay/clair) and [klar](https://github.com/optiopay/klar), -two open source tools for Vulnerability Static Analysis for containers. +Your application's Docker image may itself be based on Docker images that contain known +vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and +displays them in a merge request, you can use GitLab to audit your Docker-based apps. +By default, container scanning in GitLab is based on [Clair](https://github.com/quay/clair) and +[Klar](https://github.com/optiopay/klar), which are open-source tools for vulnerability static analysis in +containers. [GitLab's Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) +scans the containers and serves as a wrapper for Clair. -You can take advantage of Container Scanning by either [including the CI job](#configuration) in -your existing `.gitlab-ci.yml` file or by implicitly using -[Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning-ultimate) -that is provided by [Auto DevOps](../../../topics/autodevops/index.md). - -GitLab checks the Container Scanning report, compares the found vulnerabilities -between the source and target branches, and shows the information right on the -merge request. - - - -## Contribute your scanner +NOTE: **Note:** +To integrate security scanners other than Clair and Klar into GitLab, see +[Security scanner integration](../../../development/integrations/secure.md). -The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab. +You can enable container scanning by doing one of the following: -## Use cases +- [Include the CI job](#configuration) in your existing `.gitlab-ci.yml` file. +- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning-ultimate) + provided by [Auto DevOps](../../../topics/autodevops/index.md). -If you distribute your application with Docker, then there's a great chance -that your image is based on other Docker images that may in turn contain some -known vulnerabilities that could be exploited. +GitLab compares the found vulnerabilities between the source and target branches, and shows the +information directly in the merge request. -Having an extra job in your pipeline that checks for those vulnerabilities, -and the fact that they are displayed inside a merge request, makes it very easy -to perform audits for your Docker-based apps. + <!-- NOTE: The container scanning tool references the following heading in the code, so if you make a change to this heading, make sure to update the documentation URLs used in the @@ -44,26 +37,21 @@ to perform audits for your Docker-based apps. ## Requirements -To enable Container Scanning in your pipeline, you need: - -- A GitLab Runner with the - [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or - [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) - executor. -- Docker `18.09.03` or higher installed on the machine where the Runners are - running. If you're using the shared Runners on GitLab.com, this is already - the case. -- To [build and push](../../packages/container_registry/index.md#container-registry-examples-with-gitlab-cicd) - your Docker image to your project's Container Registry. - The name of the Docker image should use the following - [predefined environment variables](../../../ci/variables/predefined_variables.md) - as defined below: +To enable Container Scanning in your pipeline, you need the following: + +- [GitLab Runner](https://docs.gitlab.com/runner/) with the [Docker](https://docs.gitlab.com/runner/executors/docker.html) + or [Kubernetes](https://docs.gitlab.com/runner/install/kubernetes.html) executor. +- Docker `18.09.03` or higher installed on the same computer as the Runner. If you're using the + shared Runners on GitLab.com, then this is already the case. +- [Build and push](../../packages/container_registry/index.md#container-registry-examples-with-gitlab-cicd) + your Docker image to your project's container registry. The name of the Docker image should use + the following [predefined environment variables](../../../ci/variables/predefined_variables.md): ```plaintext $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA ``` - These can be used directly in your `.gitlab-ci.yml` file: + You can use these directly in your `.gitlab-ci.yml` file: ```yaml build: @@ -81,37 +69,35 @@ To enable Container Scanning in your pipeline, you need: ## Configuration -For GitLab 11.9 and later, to enable Container Scanning, you must -[include](../../../ci/yaml/README.md#includetemplate) the -[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) -that's provided as a part of your GitLab installation. -For GitLab versions earlier than 11.9, you can copy and use the job as defined -in that template. +How you enable Container Scanning depends on your GitLab version: + +- GitLab 11.9 and later: [Include](../../../ci/yaml/README.md#includetemplate) the + [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) + that comes with your GitLab installation. +- GitLab versions earlier than 11.9: Copy and use the job from the + [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). -Add the following to your `.gitlab-ci.yml` file: +To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the +following to your `.gitlab-ci.yml` file: ```yaml include: - template: Container-Scanning.gitlab-ci.yml ``` -The included template will: +The included template: -1. Create a `container_scanning` job in your CI/CD pipeline. -1. Pull the already built Docker image from your project's - [Container Registry](../../packages/container_registry/index.md) (see [requirements](#requirements)) - and scan it for possible vulnerabilities. +- Creates a `container_scanning` job in your CI/CD pipeline. +- Pulls the built Docker image from your project's [Container Registry](../../packages/container_registry/index.md) + (see [requirements](#requirements)) and scans it for possible vulnerabilities. -The results will be saved as a +GitLab saves the results as a [Container Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscontainer_scanning-ultimate) -that you can later download and analyze. -Due to implementation limitations, we always take the latest Container Scanning -artifact available. Behind the scenes, the -[GitLab Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) -is used and runs the scans. +that you can download and analyze later. When downloading, you always receive the most-recent +artifact. -The following is a sample `.gitlab-ci.yml` that will build your Docker image, -push it to the Container Registry, and run Container Scanning: +The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the Container +Registry, and scans the containers: ```yaml variables: @@ -141,11 +127,15 @@ include: ### Customizing the Container Scanning settings -You can change container scanning settings by using the [`variables`](../../../ci/yaml/README.md#variables) -parameter in your `.gitlab-ci.yml` to change [environment variables](#available-variables). +There may be cases where you want to customize how GitLab scans your containers. For example, you +may want to enable more verbose output from Clair or Klar, access a Docker registry that requires +authentication, and more. To change such settings, use the [`variables`](../../../ci/yaml/README.md#variables) +parameter in your `.gitlab-ci.yml` to set [environment variables](#available-variables). +The environment variables you set in your `.gitlab-ci.yml` overwrite those in +`Container-Scanning.gitlab-ci.yml`. -In the following example, we [include](../../../ci/yaml/README.md#include) the template and also -set the `CLAIR_OUTPUT` variable to `High`: +This example [includes](../../../ci/yaml/README.md#include) the Container Scanning template and +enables verbose output from Clair by setting the `CLAIR_OUTPUT` environment variable to `High`: ```yaml include: @@ -155,9 +145,6 @@ variables: CLAIR_OUTPUT: High ``` -The `CLAIR_OUTPUT` variable defined in the main `gitlab-ci.yml` will overwrite what's -defined in `Container-Scanning.gitlab-ci.yml`, changing the Container Scanning behavior. - <!-- NOTE: The container scanning tool references the following heading in the code, so if you" make a change to this heading, make sure to update the documentation URLs used in the" container scanning tool (https://gitlab.com/gitlab-org/security-products/analyzers/klar)" --> @@ -188,13 +175,9 @@ using environment variables. ### Overriding the Container Scanning template -CAUTION: **Deprecation:** -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. - -If you want to override the job definition (for example, change properties like -`variables`), you need to declare a `container_scanning` job after the -template inclusion and specify any additional keys under it. For example: +If you want to override the job definition (for example, to change properties like `variables`), you +must declare a `container_scanning` job after the template inclusion, and then +specify any additional keys. For example: ```yaml include: @@ -205,15 +188,20 @@ container_scanning: GIT_STRATEGY: fetch ``` +CAUTION: **Deprecated:** +GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic). +When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) +instead. + ### Vulnerability whitelisting -If you want to whitelist specific vulnerabilities, you'll need to: +To whitelist specific vulnerabilities, follow these steps: -1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions described in the - [overriding the Container Scanning template](#overriding-the-container-scanning-template) section of this document. -1. Define the whitelisted vulnerabilities in a YAML file named `clair-whitelist.yml` which must use the format described - in the [whitelist example file](https://github.com/arminc/clair-scanner/blob/v12/example-whitelist.yaml). -1. Add the `clair-whitelist.yml` file to the Git repository of your project. +1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions in + [overriding the Container Scanning template](#overriding-the-container-scanning-template). +1. Define the whitelisted vulnerabilities in a YAML file named `clair-whitelist.yml`. This must use + the format described in the [whitelist example file](https://github.com/arminc/clair-scanner/blob/v12/example-whitelist.yaml). +1. Add the `clair-whitelist.yml` file to your project's Git repository. ### Running Container Scanning in an offline environment |