Skip to content

G
gitlab-ce
Commit 67f26445 authored by Nick Gaskill's avatar Nick Gaskill Committed by Craig Norris
Browse files
Options

Revisions to container scanning doc

parent 32a9c16b
Show whitespace changes
Inline Side-by-side
Showing with 67 additions and 79 deletions
doc/user/application_security/container_scanning/index.md
View file @ 67f26445
......@@ -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.
![Container Scanning Widget](img/container_scanning_v13_0.png)
## 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.
![Container Scanning Widget](img/container_scanning_v13_0.png)
<!-- 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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7