diff options
Diffstat (limited to 'doc/user/application_security/container_scanning/index.md')
-rw-r--r-- | doc/user/application_security/container_scanning/index.md | 149 |
1 files changed, 39 insertions, 110 deletions
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 696446599c8..7b631a5a1cd 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Container Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672) @@ -10,7 +14,7 @@ images (or more precisely the containers) for known vulnerabilities by using [Clair](https://github.com/coreos/clair) and [clair-scanner](https://github.com/arminc/clair-scanner), two open source tools for Vulnerability Static Analysis for containers. -You can take advantage of Container Scanning by either [including the CI job](#including-the-provided-template) in +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/index.md#auto-container-scanning-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -47,7 +51,7 @@ To enable Container Scanning in your pipeline, you need: your Docker image to your project's [Container Registry](../../project/container_registry.md). The name of the Docker image should match the following scheme: - ``` + ```text $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA ``` @@ -55,32 +59,16 @@ To enable Container Scanning in your pipeline, you need: [predefined environment variables](../../../ci/variables/predefined_variables.md) document. -## Configuring Container Scanning - -To enable Container Scanning in your project, define a job in your -`.gitlab-ci.yml` file that generates the -[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate). - -This can be done in two ways: +## Configuration -- For GitLab 11.9 and later, including the provided - `Container-Scanning.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. +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-ee/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. -### Including the provided template - -NOTE: **Note:** -The CI/CD Container Scanning template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). - -A CI/CD [Container Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) -with the default Container Scanning job definition is provided as a part of your GitLab -installation that you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. - -To enable Container Scanning using the provided template, add the following to -your `.gitlab-ci.yml` file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -89,12 +77,12 @@ include: The included template will: -- Create a `container_scanning` job in your CI/CD pipeline. -- Pull the already built Docker image from your project's - [Container Registry](../../project/container_registry.md) (see [requirements](#requirements)) - and scan it for possible vulnerabilities. +1. Create a `container_scanning` job in your CI/CD pipeline. +1. Pull the already built Docker image from your project's + [Container Registry](../../project/container_registry.md) (see [requirements](#requirements)) + and scan it for possible vulnerabilities. -The report will be saved as a +The results will be saved as a [Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest Container Scanning @@ -106,95 +94,36 @@ If you want to whitelist some specific vulnerabilities, you can do so by definin them in a YAML file named `clair-whitelist.yml`. Read more in the [Clair documentation](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file). -### Manual job definition for GitLab 11.5 and later - -CAUTION: **Caution:** -The job definition shown below is supported on GitLab 11.5 and later versions. -However, if you're using GitLab 11.9+, it's recommended to use -[the provided Container Scanning template](#including-the-provided-template). +## Example -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `container_scanning` -job can be added: +The following is a sample `.gitlab-ci.yml` that will build your Docker Image, push it to the container registry and run Container Scanning. ```yaml -container_scanning: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - ## Define two new variables based on GitLab's CI/CD predefined variables - ## https://docs.gitlab.com/ee/ci/variables/README.html#predefined-environment-variables - CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG - CI_APPLICATION_TAG: $CI_COMMIT_SHA - CLAIR_LOCAL_SCAN_VERSION: v2.0.8_fe9b059d930314b54c78f75afe265955faf4fdc1 - allow_failure: true - services: - - docker:stable-dind - script: - - docker run -d --name db arminc/clair-db:latest - - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:${CLAIR_LOCAL_SCAN_VERSION} - - apk add -U wget ca-certificates - - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} - - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64 - - mv clair-scanner_linux_amd64 clair-scanner - - chmod +x clair-scanner - - touch clair-whitelist.yml - - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done - - retries=0 - - echo "Waiting for clair daemon to start" - - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done - - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true - artifacts: - reports: - container_scanning: gl-container-scanning-report.json -``` +variables: + DOCKER_DRIVER: overlay2 -### Manual job definition for GitLab 11.4 and earlier (deprecated) +services: + - docker:stable-dind -CAUTION: **Deprecated:** -Before GitLab 11.5, the Container Scanning job and artifact had to be named specifically -to automatically extract report data and show it in the merge request widget. -While these old job definitions are still maintained, they have been deprecated -and may be removed in the next major release, GitLab 12.0. You are strongly -advised to update your current `.gitlab-ci.yml` configuration to reflect that change. +stages: + - build + - test -For GitLab 11.4 and earlier, the Container Scanning job should look like: +include: + - template: Container-Scanning.gitlab-ci.yml -```yaml -container_scanning: +build: image: docker:stable + stage: build variables: - DOCKER_DRIVER: overlay2 - ## Define two new variables based on GitLab's CI/CD predefined variables - ## https://docs.gitlab.com/ee/ci/variables/README.html#predefined-environment-variables - CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG - CI_APPLICATION_TAG: $CI_COMMIT_SHA - CLAIR_LOCAL_SCAN_VERSION: v2.0.8_fe9b059d930314b54c78f75afe265955faf4fdc1 - allow_failure: true - services: - - docker:stable-dind + IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA script: - - docker run -d --name db arminc/clair-db:latest - - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:${CLAIR_LOCAL_SCAN_VERSION} - - apk add -U wget ca-certificates - - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} - - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64 - - mv clair-scanner_linux_amd64 clair-scanner - - chmod +x clair-scanner - - touch clair-whitelist.yml - - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done - - retries=0 - - echo "Waiting for clair daemon to start" - - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done - - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true - artifacts: - paths: [gl-container-scanning-report.json] + - docker info + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker build -t $IMAGE . + - docker push $IMAGE ``` -Alternatively, the job name could be `sast:container` -and the artifact name could be `gl-sast-container-report.json`. -These names have been deprecated with GitLab 11.0 -and may be removed in the next major release, GitLab 12.0. - ## Security Dashboard The Security Dashboard is a good place to get an overview of all the security @@ -219,11 +148,11 @@ When the GitLab Runner uses the Docker executor and NFS is used (e.g., `/var/lib/docker` is on an NFS mount), Container Scanning might fail with an error like the following: -``` +```text 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"). To prevent the error, ensure the Docker version that the Runner is using is `18.09.03` or higher. For more information, see -[issue #10241](https://gitlab.com/gitlab-org/gitlab-ee/issues/10241 "Investigate why Container Scanning is not working with NFS mounts"). +[issue #10241](https://gitlab.com/gitlab-org/gitlab-ee/issues/10241 "Investigate why Container Scanning is not working with NFS mounts").
\ No newline at end of file |