diff options
Diffstat (limited to 'doc/user/application_security/container_scanning/index.md')
| -rw-r--r-- | doc/user/application_security/container_scanning/index.md | 201 |
1 files changed, 170 insertions, 31 deletions
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index da2816ab6ed..bea9284873c 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,11 +9,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in GitLab 10.4. +INFO: +Try out Container Scanning in GitLab Ultimate. +[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-container-scanning-docs). + 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. +vulnerabilities. By including an extra Container Scanning 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. + +Container Scanning is often considered part of Software Composition Analysis (SCA). SCA can contain +aspects of inspecting the items your code uses. These items typically include application and system +dependencies that are almost always imported from external sources, rather than sourced from items +you wrote yourself. + +GitLab offers both Container Scanning and [Dependency Scanning](../dependency_scanning/) +to ensure coverage for all of these dependency types. To cover as much of your risk area as +possible, we encourage you to use all of our security scanners. -GitLab provides integration with open-source tools for vulnerability static analysis in containers: +## Overview + +GitLab integrates with open-source tools for vulnerability static analysis in containers: - [Trivy](https://github.com/aquasecurity/trivy) - [Grype](https://github.com/anchore/grype) @@ -43,19 +59,9 @@ To enable container scanning in your pipeline, you need the following: - An image matching the [supported distributions](#supported-distributions). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) the Docker image to your project's container registry. -- The name of the Docker image to scan, in the `DOCKER_IMAGE` [configuration variable](#available-cicd-variables). - If you're using a third-party container registry, you might need to provide authentication credentials through the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). - For example, if you are connecting to AWS ECR, you might use the following: - -```yaml -export AWS_ECR_PASSWORD=$(aws ecr get-login-password --region region) - -include: - - template: Security/Container-Scanning.gitlab-ci.yml - DOCKER_USER: AWS - DOCKER_PASSWORD: "$AWS_ECR_PASSWORD" -``` + For more details on how to use these variables, see [authenticate to a remote registry](#authenticate-to-a-remote-registry). ## Configuration @@ -75,31 +81,29 @@ The included template: (see [requirements](#requirements)) and scans it for possible vulnerabilities. GitLab saves the results as a -[Container Scanning report artifact](../../../ci/yaml/index.md#artifactsreportscontainer_scanning) +[Container Scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportscontainer_scanning) that you can download and analyze later. When downloading, you always receive the most-recent -artifact. +artifact. If [dependency scan is enabled](#dependency-list), +a [Dependency Scanning report artifact](../../../ci/yaml/artifacts_reports.md#artifactsreportsdependency_scanning) +is also created. The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the container registry, and scans the image: ```yaml -build: - image: docker:latest - stage: build - services: - - docker:dind - variables: - IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA - script: - - docker info - - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - - docker build -t $IMAGE . - - docker push $IMAGE - include: + - template: Jobs/Build.gitlab-ci.yml - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DEFAULT_BRANCH_IMAGE: $CI_REGISTRY_IMAGE/$CI_DEFAULT_BRANCH:$CI_COMMIT_SHA ``` +Setting `CS_DEFAULT_BRANCH_IMAGE` avoids duplicate vulnerability findings when an image name differs across branches. +The value of `CS_DEFAULT_BRANCH_IMAGE` indicates the name of the scanned image as it appears on the default branch. +For more details on how this deduplication is achieved, see [Setting the default branch image](#setting-the-default-branch-image). + ### Customizing the container scanning settings There may be cases where you want to customize how GitLab scans your containers. For example, you @@ -120,6 +124,92 @@ variables: SECURE_LOG_LEVEL: 'debug' ``` +#### Scan an image in a remote registry + +To scan images located in a registry other than the project's, use the following `.gitlab-ci.yml`: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + DOCKER_IMAGE: example.com/user/image:tag +``` + +##### Authenticate to a remote registry + +Scanning an image in a private registry requires authentication. Provide the username in the `DOCKER_USER` +variable, and the password in the `DOCKER_PASSWORD` configuration variable. + +For example, to scan an image from AWS Elastic Container Registry: + +```yaml +container_scanning: + before_script: + - curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" --output "awscliv2.zip" + - unzip awscliv2.zip + - ./aws/install + - aws --version + - export AWS_ECR_PASSWORD=$(aws ecr get-login-password --region region) + +include: + - template: Security/Container-Scanning.gitlab-ci.yml + DOCKER_IMAGE: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/<image>:<tag> + DOCKER_USER: AWS + DOCKER_PASSWORD: "$AWS_ECR_PASSWORD" +``` + +#### Dependency list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. + +The `CS_DISABLE_DEPENDENCY_LIST` CI/CD variable controls whether the scan creates a +[Dependency List](../dependency_list/) +report. The variable's default setting of `false` causes the scan to create the report. To disable +the report, set the variable to `true`: + +For example: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DISABLE_DEPENDENCY_LIST: "true" +``` + +#### Report language-specific findings + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7277) in GitLab 14.6. + +The `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` CI/CD variable controls whether the scan reports +findings related to programming languages. The languages supported depend on the +[scanner used](#change-scanners): + +- [Trivy](https://aquasecurity.github.io/trivy/latest/vulnerability/detection/language/). +- [Grype](https://github.com/anchore/grype#features). + +By default, the report only includes packages managed by the Operating System (OS) package manager +(for example, `yum`, `apt`, `apk`, `tdnf`). To report security findings in non-OS packages, set +`CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` to `"false"`: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN: "false" +``` + +When you enable this feature, you may see [duplicate findings](../terminology/#duplicate-finding) +in the [Vulnerability Report](../vulnerability_report/) +if [Dependency Scanning](../dependency_scanning/) +is enabled for your project. This happens because GitLab can't automatically deduplicate the +findings reported by the two different analyzers. + #### Available CI/CD variables You can [configure](#customizing-the-container-scanning-settings) analyzers by using the following CI/CD variables: @@ -130,6 +220,9 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u | `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | All | | `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | All | | `CS_ANALYZER_IMAGE` | `registry.gitlab.com/security-products/container-scanning:4` | Docker image of the analyzer. | All | +| `CS_DEFAULT_BRANCH_IMAGE` | `""` | The name of the `DOCKER_IMAGE` on the default branch. See [Setting the default branch image](#setting-the-default-branch-image) for more details. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338877) in GitLab 14.5. | All | +| `CS_DISABLE_DEPENDENCY_LIST` | `"false"` | Disable Dependency Scanning for packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | +| `CS_DISABLE_LANGUAGE_VULNERABILITY_SCAN` | `"true"` | Disable scanning for language-specific packages installed in the scanned image. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345434) in GitLab 14.6. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | | `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | @@ -225,6 +318,51 @@ Prior to the GitLab 14.0 release, any variable defined under the scope `containe considered for scanners other than Clair. In GitLab 14.0 and later, all variables can be defined either as a global variable or under `container_scanning`. +### Setting the default branch image + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338877) in GitLab 14.5. + +By default, container scanning assumes that the image naming convention stores any branch-specific +identifiers in the image tag rather than the image name. When the image name differs between the +default branch and the non-default branch, previously-detected vulnerabilities show up as newly +detected in merge requests. + +When the same image has different names on the default branch and a non-default branch, you can use +the `CS_DEFAULT_BRANCH_IMAGE` variable to indicate what that image's name is on the default branch. +GitLab then correctly determines if a vulnerability already exists when running scans on non-default +branches. + +As an example, suppose the following: + +- Non-default branches publish images with the naming convention + `$CI_REGISTRY_IMAGE/$CI_COMMIT_BRANCH:$CI_COMMIT_SHA`. +- The default branch publishes images with the naming convention + `$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA`. + +In this example, you can use the following CI/CD configuration to ensure that vulnerabilities aren't +duplicated: + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + CS_DEFAULT_BRANCH_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + before_script: + - export DOCKER_IMAGE="$CI_REGISTRY_IMAGE/$CI_COMMIT_BRANCH:$CI_COMMIT_SHA" + - | + if [ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then + export DOCKER_IMAGE="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" + fi +``` + +`CS_DEFAULT_BRANCH_IMAGE` should remain the same for a given `DOCKER_IMAGE`. If it changes, then a +duplicate set of vulnerabilities are created, which must be manually dismissed. + +When using [Auto DevOps](../../../topics/autodevops/index.md), `CS_DEFAULT_BRANCH_IMAGE` is +automatically set to `$CI_REGISTRY_IMAGE/$CI_DEFAULT_BRANCH:$CI_APPLICATION_TAG`. + ### Using a custom SSL CA certificate authority 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: @@ -496,7 +634,7 @@ Here's an example container scanning report: ```json-doc { - "version": "3.0.0", + "version": "14.0.0", "vulnerabilities": [ { "id": "df52bc8ce9a2ae56bbcb0c4ecda62123fbd6f69b", @@ -518,7 +656,8 @@ Here's an example container scanning report: "version": "1.4.8" }, "operating_system": "debian:9.4", - "image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256:bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e" + "image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256:bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e", + "default_branch_image": "registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0:latest" }, "identifiers": [ { |