index.md 26.8 KB
Newer Older
1 2
---
type: reference, howto
3
stage: Protect
4
group: Container Security
5
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
6 7
---

8
# Container Scanning **(ULTIMATE)**
9

Evan Read's avatar
Evan Read committed
10
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4.
11

Nick Gaskill's avatar
Nick Gaskill committed
12 13 14 15
WARNING:
GitLab 14.0 will replace its container scanning engine with Trivy. Currently, GitLab uses the open
source Clair engine for container scanning. GitLab 13.9 deprecates Clair. This is not a hard
breaking change, as customers who wish to continue to use Clair can do so by setting the
16
`CS_MAJOR_VERSION` CI/CD variable to version 3 (or earlier) in their `gitlab-ci.yaml` file. Since Clair is
Nick Gaskill's avatar
Nick Gaskill committed
17 18 19 20
deprecated, however, note that GitLab will no longer update or maintain that scanning engine
beginning in the 14.0 release. We advise customers to use the new default of Trivy beginning in
GitLab 14.0 for regular updates and the latest features.

21 22 23 24 25
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
Amy Qualls's avatar
Amy Qualls committed
26
containers. The GitLab [Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/)
27
scans the containers and serves as a wrapper for Clair.
28

29 30
To integrate security scanners other than Clair and Klar into GitLab, see
[Security scanner integration](../../../development/integrations/secure.md).
31

32
You can enable container scanning by doing one of the following:
33

34
- [Include the CI job](#configuration) in your existing `.gitlab-ci.yml` file.
Craig Norris's avatar
Craig Norris committed
35
- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning),
36
  provided by [Auto DevOps](../../../topics/autodevops/index.md).
37

38 39
GitLab compares the found vulnerabilities between the source and target branches, and shows the
information directly in the merge request.
40

41
![Container Scanning Widget](img/container_scanning_v13_2.png)
42

43 44 45
<!-- 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) -->
46

47 48
## Requirements

49
To enable container scanning in your pipeline, you need the following:
50

51 52 53 54
- [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.
55
- An image matching [Clair's list of supported distributions](https://quay.github.io/claircore/).
56
- [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd)
57
  your Docker image to your project's container registry. The name of the Docker image should use
58
  the following [predefined CI/CD variables](../../../ci/variables/predefined_variables.md):
59

60
  ```plaintext
61 62 63
  $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA
  ```

64
  You can use these directly in your `.gitlab-ci.yml` file:
65 66 67

  ```yaml
  build:
68
    image: docker:19.03.12
69 70
    stage: build
    services:
71
      - docker:19.03.12-dind
72
    variables:
73
      IMAGE_TAG: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA
74
    script:
75
      - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
76 77 78
      - docker build -t $IMAGE_TAG .
      - docker push $IMAGE_TAG
  ```
79

80
## Configuration
81

82
How you enable container scanning depends on your GitLab version:
83 84 85 86 87 88

- 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).
mo's avatar
mo committed
89
- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the `CS_MAJOR_VERSION` from `2` to `3`.
90

91 92
To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the
following to your `.gitlab-ci.yml` file:
93 94 95

```yaml
include:
96
  - template: Container-Scanning.gitlab-ci.yml
97 98
```

99
The included template:
100

101
- Creates a `container_scanning` job in your CI/CD pipeline.
102
- Pulls the built Docker image from your project's [container registry](../../packages/container_registry/index.md)
103
  (see [requirements](#requirements)) and scans it for possible vulnerabilities.
104

105
GitLab saves the results as a
106
[Container Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscontainer_scanning)
107 108
that you can download and analyze later. When downloading, you always receive the most-recent
artifact.
109

110 111
The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the container
registry, and scans the containers:
Seth Berger's avatar
Seth Berger committed
112 113 114 115 116 117 118 119 120 121 122 123

```yaml
variables:
  DOCKER_DRIVER: overlay2

stages:
  - build
  - test

build:
  image: docker:stable
  stage: build
Adam Cohen's avatar
Adam Cohen committed
124
  services:
125
    - docker:19.03.12-dind
Seth Berger's avatar
Seth Berger committed
126 127 128 129
  variables:
    IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA
  script:
    - docker info
130
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
Seth Berger's avatar
Seth Berger committed
131 132
    - docker build -t $IMAGE .
    - docker push $IMAGE
133 134 135

include:
  - template: Container-Scanning.gitlab-ci.yml
Seth Berger's avatar
Seth Berger committed
136 137
```

138
### Customizing the container scanning settings
139

140 141 142
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)
143 144
parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#available-variables).
The variables you set in your `.gitlab-ci.yml` overwrite those in
145
`Container-Scanning.gitlab-ci.yml`.
146

147
This example [includes](../../../ci/yaml/README.md#include) the container scanning template and
148
enables verbose output from Clair by setting the `CLAIR_OUTPUT` variable to `High`:
149 150 151

```yaml
include:
Dominic Couture's avatar
Dominic Couture committed
152
  - template: Container-Scanning.gitlab-ci.yml
153

154 155
variables:
  CLAIR_OUTPUT: High
156 157
```

mo's avatar
mo committed
158 159 160
Version `3` of the `container_scanning` Docker image uses [`centos:centos8`](https://hub.docker.com/_/centos)
as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77)
script and instead executes the analyzer by default. Any customizations made to the
161 162
`container_scanning` job's [`before_script`](../../../ci/yaml/README.md#before_script)
and [`after_script`](../../../ci/yaml/README.md#after_script)
mo's avatar
mo committed
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177
blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based
Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-variables)
variable.

This example [includes](../../../ci/yaml/README.md#include) the container scanning template and
enables version `2` of the analyzer:

```yaml
include:
  - template: Container-Scanning.gitlab-ci.yml

variables:
  CS_MAJOR_VERSION: '2'
```

Amy Qualls's avatar
Amy Qualls committed
178 179 180
<!-- 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)" -->
181

182
#### Available variables
183

184
You can [configure](#customizing-the-container-scanning-settings) container
185
scanning by using the following CI/CD variables:
186

187
| CI/CD Variable                 | Default       | Description |
188
| ------------------------------ | ------------- | ----------- |
189
| `ADDITIONAL_CA_CERT_BUNDLE`    | `""`          | Bundle of CA certs that you want to trust. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. |
190 191 192 193
| `CLAIR_DB_CONNECTION_STRING`   | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. |
| `CLAIR_DB_IMAGE`               | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. |
| `CLAIR_DB_IMAGE_TAG`           | `latest`      | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. |
| `CLAIR_OUTPUT`                 | `Unknown`     | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. |
194
| `CLAIR_TRACE`                  | `"false"`     | Set to true to enable more verbose output from the Clair server process. |
195 196 197
| `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool) section. |
| `CI_APPLICATION_REPOSITORY`    | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. |
| `CI_APPLICATION_TAG`           | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. |
198
| `CS_MAJOR_VERSION`             | `3`           | The major version of the Docker image tag. |
199
| `DOCKER_IMAGE`                 | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. |
200 201 202 203
| `DOCKER_INSECURE`              | `"false"`     | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. |
| `DOCKER_PASSWORD`              | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. |
| `DOCKER_USER`                  | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. |
| `DOCKERFILE_PATH`              | `Dockerfile`  | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. |
204
| `KLAR_TRACE`                   | `"false"`     | Set to true to enable more verbose output from Klar. |
205 206 207 208 209
| `REGISTRY_INSECURE`            | `"false"`     | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. |
| `SECURE_ANALYZERS_PREFIX`      | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. |
| `SECURE_LOG_LEVEL`             | `info`        | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. |

### Overriding the container scanning template
210

211 212 213
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:
214

215 216
```yaml
include:
Dominic Couture's avatar
Dominic Couture committed
217
  - template: Container-Scanning.gitlab-ci.yml
218

219 220 221 222
container_scanning:
  variables:
    GIT_STRATEGY: fetch
```
223

224
WARNING:
225 226 227 228
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.

229
### Using a custom SSL CA certificate authority
230

231
You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when fetching Docker images from a registry which uses HTTPS. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following:
232 233 234 235 236 237 238 239 240 241 242 243 244 245

```yaml
container_scanning:
  variables:
    ADDITIONAL_CA_CERT_BUNDLE: |
        -----BEGIN CERTIFICATE-----
        MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
        ...
        jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
        -----END CERTIFICATE-----
```

The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate.

Can Eldem's avatar
Can Eldem committed
246
### Vulnerability allowlisting
247

Can Eldem's avatar
Can Eldem committed
248
To allowlist specific vulnerabilities, follow these steps:
249

250
1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions in
251
   [overriding the container scanning template](#overriding-the-container-scanning-template).
Can Eldem's avatar
Can Eldem committed
252 253 254
1. Define the allowlisted vulnerabilities in a YAML file named `vulnerability-allowlist.yml`. This must use
   the format described in the [allowlist example file](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/raw/master/testdata/vulnerability-allowlist.yml).
1. Add the `vulnerability-allowlist.yml` file to your project's Git repository.
255

256
### Running container scanning in an offline environment
257

258
For self-managed GitLab instances in an environment with limited, restricted, or intermittent access
259
to external resources through the internet, some adjustments are required for the container scanning job to
260
successfully run. For more information, see [Offline environments](../offline_deployments/index.md).
261

262
#### Requirements for offline container Scanning
263

264
To use container scanning in an offline environment, you need:
265 266

- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements).
267
- To configure a local Docker container registry with copies of the container scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar) images, found in the [container scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry).
268

269
Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
270 271
meaning the runner tries to pull Docker images from the GitLab container registry even if a local
copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
272 273 274
in an offline environment if you prefer using only locally available Docker images. However, we
recommend keeping the pull policy setting to `always` if not in an offline environment, as this
enables the use of updated scanners in your CI/CD pipelines.
275

276 277 278 279 280 281 282 283
##### Support for Custom Certificate Authorities

Support for custom certificate authorities was introduced in the following versions:

| Analyzer | Version |
| -------- | ------- |
| `klar` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/releases/v2.3.0) |

284
#### Make GitLab container scanning analyzer images available inside your Docker registry
285

286
For container scanning, import the following default images from `registry.gitlab.com` into your
287
[local Docker container registry](../../packages/container_registry/index.md):
288

289 290 291 292
```plaintext
registry.gitlab.com/gitlab-org/security-products/analyzers/klar
https://hub.docker.com/r/arminc/clair-db
```
293 294 295

The process for importing Docker images into a local offline Docker registry depends on
**your network security policy**. Please consult your IT staff to find an accepted and approved
296 297
process by which you can import or temporarily access external resources. Note that these scanners
are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
298
with new definitions, so consider if you are able to make periodic updates yourself.
299 300

For more information, see [the specific steps on how to update an image with a pipeline](#automating-container-scanning-vulnerability-database-updates-with-a-pipeline).
301 302 303 304 305

For details on saving and transporting Docker images as a file, see Docker's documentation on
[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/),
[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/).

306
#### Set container scanning CI/CD variables to use local container scanner analyzers
307

308
1. [Override the container scanning template](#overriding-the-container-scanning-template) in your `.gitlab-ci.yml` file to refer to the Docker images hosted on your local Docker container registry:
309 310 311 312 313 314

   ```yaml
   include:
     - template: Container-Scanning.gitlab-ci.yml

   container_scanning:
315
     image: $CI_REGISTRY/namespace/gitlab-klar-analyzer
316
     variables:
317
       CLAIR_DB_IMAGE: $CI_REGISTRY/namespace/clair-vulnerabilities-db
318 319
   ```

320
1. If your local Docker container registry is running securely over `HTTPS`, but you're using a
321
   self-signed certificate, then you must set `DOCKER_INSECURE: "true"` in the above
322 323
   `container_scanning` section of your `.gitlab-ci.yml`.

324
#### Automating container scanning vulnerability database updates with a pipeline
325 326

It can be worthwhile to set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) to
327
build a new version of the vulnerabilities database on a preset schedule. Automating
Lindsay Kerr's avatar
Lindsay Kerr committed
328
this with a pipeline means you do not have to do it manually each time. You can use the following
329
`.gitlab-yml.ci` as a template:
330 331 332 333 334 335 336 337 338

```yaml
image: docker:stable

stages:
  - build

build_latest_vulnerabilities:
  stage: build
Adam Cohen's avatar
Adam Cohen committed
339
  services:
340
    - docker:19.03.12-dind
341 342 343
  script:
    - docker pull arminc/clair-db:latest
    - docker tag arminc/clair-db:latest $CI_REGISTRY/namespace/clair-vulnerabilities-db
344
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
345 346 347
    - docker push $CI_REGISTRY/namespace/clair-vulnerabilities-db
```

Lindsay Kerr's avatar
Lindsay Kerr committed
348
The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry.
349

350
## Running the standalone container scanning tool
Adam Cohen's avatar
Adam Cohen committed
351

352
It's possible to run the [GitLab container scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/klar)
Adam Cohen's avatar
Adam Cohen committed
353 354 355 356
against a Docker container without needing to run it within the context of a CI job. To scan an
image directly, follow these steps:

1. Run [Docker Desktop](https://www.docker.com/products/docker-desktop) or [Docker Machine](https://github.com/docker/machine).
357
1. Run the latest [prefilled vulnerabilities database](https://hub.docker.com/repository/docker/arminc/clair-db) Docker image:
Adam Cohen's avatar
Adam Cohen committed
358

359 360 361
   ```shell
   docker run -p 5432:5432 -d --name clair-db arminc/clair-db:latest
   ```
Adam Cohen's avatar
Adam Cohen committed
362

363
1. Configure a CI/CD variable to point to your local machine's IP address (or insert your IP address instead of the `LOCAL_MACHINE_IP_ADDRESS` variable in the `CLAIR_DB_CONNECTION_STRING` in the next step):
Adam Cohen's avatar
Adam Cohen committed
364 365 366 367 368

   ```shell
   export LOCAL_MACHINE_IP_ADDRESS=your.local.ip.address
   ```

369
1. Run the analyzer's Docker image, passing the image and tag you want to analyze in the `CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG` variables:
Adam Cohen's avatar
Adam Cohen committed
370

371 372 373 374 375 376 377 378 379 380
   ```shell
   docker run \
     --interactive --rm \
     --volume "$PWD":/tmp/app \
     -e CI_PROJECT_DIR=/tmp/app \
     -e CLAIR_DB_CONNECTION_STRING="postgresql://postgres:password@${LOCAL_MACHINE_IP_ADDRESS}:5432/postgres?sslmode=disable&statement_timeout=60000" \
     -e CI_APPLICATION_REPOSITORY=registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256 \
     -e CI_APPLICATION_TAG=bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e \
     registry.gitlab.com/gitlab-org/security-products/analyzers/klar
   ```
Adam Cohen's avatar
Adam Cohen committed
381 382 383

The results are stored in `gl-container-scanning-report.json`.

384 385
## Reports JSON format

386
The container scanning tool emits a JSON report file. For more information, see the
387
[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json).
388

389
Here's an example container scanning report:
390 391 392 393 394 395

```json-doc
{
  "version": "2.3",
  "vulnerabilities": [
    {
396
      "id": "ac0997ad-1006-4c81-81fb-ee2bbe6e78e3",
397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432
      "category": "container_scanning",
      "message": "CVE-2019-3462 in apt",
      "description": "Incorrect sanitation of the 302 redirect field in HTTP transport method of apt versions 1.4.8 and earlier can lead to content injection by a MITM attacker, potentially leading to remote code execution on the target machine.",
      "severity": "High",
      "confidence": "Unknown",
      "solution": "Upgrade apt from 1.4.8 to 1.4.9",
      "scanner": {
        "id": "klar",
        "name": "klar"
      },
      "location": {
        "dependency": {
          "package": {
            "name": "apt"
          },
          "version": "1.4.8"
        },
        "operating_system": "debian:9",
        "image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256:bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e"
      },
      "identifiers": [
        {
          "type": "cve",
          "name": "CVE-2019-3462",
          "value": "CVE-2019-3462",
          "url": "https://security-tracker.debian.org/tracker/CVE-2019-3462"
        }
      ],
      "links": [
        {
          "url": "https://security-tracker.debian.org/tracker/CVE-2019-3462"
        }
      ]
    }
  ],
  "remediations": [
433 434 435
    {
      "fixes": [
        {
436
          "id": "c0997ad-1006-4c81-81fb-ee2bbe6e78e3"
437 438 439 440 441
        }
      ],
      "summary": "Upgrade apt from 1.4.8 to 1.4.9",
      "diff": "YXB0LWdldCB1cGRhdGUgJiYgYXB0LWdldCB1cGdyYWRlIC15IGFwdA=="
    }
442 443 444 445
  ]
}
```

446 447 448 449 450 451 452 453 454 455 456 457
## Security Dashboard

The [Security Dashboard](../security_dashboard/index.md) shows you an overview of all
the security vulnerabilities in your groups, projects and pipelines.

## Vulnerabilities database update

For more information about the vulnerabilities database update, check the
[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database).

## Interacting with the vulnerabilities

458
After a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities).
459 460 461 462 463 464 465

## Solutions for vulnerabilities (auto-remediation)

Some vulnerabilities can be fixed by applying the solution that GitLab
automatically generates.

To enable remediation support, the scanning tool _must_ have access to the `Dockerfile` specified by
466
the [`DOCKERFILE_PATH`](#available-variables) CI/CD variable. To ensure that the scanning tool
467
has access to this
468
file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.md#git-strategy) in
469
your `.gitlab-ci.yml` file by following the instructions described in this document's
470
[overriding the container scanning template](#overriding-the-container-scanning-template) section.
471

Nicole Schwartz's avatar
Nicole Schwartz committed
472
Read more about the [solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities).
473

474 475
## Troubleshooting

Evan Read's avatar
Evan Read committed
476
### `docker: Error response from daemon: failed to copy xattrs`
477

478
When the runner uses the `docker` executor and NFS is used
479
(for example, `/var/lib/docker` is on an NFS mount), container scanning might fail with
480 481
an error like the following:

482
```plaintext
483 484 485 486
docker: Error response from daemon: failed to copy xattrs: failed to set xattr "security.selinux" on /path/to/file: operation not supported.
```

This is a result of a bug in Docker which is now [fixed](https://github.com/containerd/continuity/pull/138 "fs: add WithAllowXAttrErrors CopyOpt").
487
To prevent the error, ensure the Docker version that the runner is using is
488
`18.09.03` or higher. For more information, see
489
[issue #10241](https://gitlab.com/gitlab-org/gitlab/-/issues/10241 "Investigate why Container Scanning is not working with NFS mounts").
490 491 492 493

### Getting warning message `gl-container-scanning-report.json: no matching files`

For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload).