Merge branch 'docs/sast-image-ee' into 'master'

Documentation for Docker image security scanning feature

Closes #4358

See merge request gitlab-org/gitlab-ee!3781

doc/ci/examples/README.md

@@ -43,7 +43,8 @@ There's also a collection of repositories with [example projects](https://gitlab
 
 ### Static Application Security Testing (SAST)
 
-Scan your code for vulnerabilities with GitLab [Static Application Security Testing (SAST)](sast.md).
+- [Scan your code for vulnerabilities](sast.md)
+- [Scan your Docker images for vulnerabilities](sast_docker.md)
 
 ### Dynamic Application Security Testing (DAST)
 

doc/ci/examples/dast.md

-# Dynamic application security testing with GitLab CI/CD
-
-NOTE: **Note:**
-In order to use this tool, a [GitLab Enterprise Edition Ultimate][ee] license
-is needed.
+# Dynamic Application Security Testing with GitLab CI/CD
 
 This example shows how to run
 [Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_program_analysis)
 on your project's source code by using GitLab CI/CD.
 
+DAST is using the popular open source tool
+[OWASP ZAProxy](https://github.com/zaproxy/zaproxy) to perform an analysis.
+
 All you need is a GitLab Runner with the Docker executor (the shared Runners on
 GitLab.com will work fine). You can then add a new job to `.gitlab-ci.yml`,
 called `dast`:
@@ -17,23 +16,20 @@ dast:
   image: owasp/zap2docker-stable
   script:
     - mkdir /zap/wrk/
-    - /zap/zap-baseline.py -J gl-dast-report.json -t http://dzaporozhets.me/ || true
+    - /zap/zap-baseline.py -J gl-dast-report.json -t https://example.com || true
     - cp /zap/wrk/gl-dast-report.json .
   artifacts:
     paths: [gl-dast-report.json]
 ```
 
-DAST is using a popular open source tool 
-[OWASP ZAProxy](https://github.com/zaproxy/zaproxy) to perform an analysis.
-
 The above example will create a `dast` job in your CI pipeline and will allow
 you to download and analyze the report artifact in JSON format.
 
 TIP: **Tip:**
-Starting with GitLab Enterprise Edition Ultimate 10.4, this information will
+Starting with [GitLab Enterprise Edition Ultimate][ee] 10.4, this information will
 be automatically extracted and shown right in the merge request widget. To do
 so, the CI job must be named `dast` and the artifact path must be
 `gl-dast-report.json`.
-[Learn more on application security testing results shown in merge requests](../../user/project/merge_requests/sast.md).
+[Learn more on dynamic application security testing results shown in merge requests](../../user/project/merge_requests/dast.md).
 
 [ee]: https://about.gitlab.com/gitlab-ee/

doc/ci/examples/sast.md

-# Static application security testing with GitLab CI/CD
+# Static Application Security Testing with GitLab CI/CD
 
 NOTE: **Note:**
 In order to use this tool, a [GitLab Enterprise Edition Ultimate][ee] license
@@ -36,7 +36,7 @@ The results are sorted by the priority of the vulnerability:
 1. Everything else
 
 TIP: **Tip:**
-Starting with GitLab Enterprise Edition Ultimate 10.3, this information will
+Starting with [GitLab Enterprise Edition Ultimate][ee] 10.3, this information will
 be automatically extracted and shown right in the merge request widget. To do
 so, the CI job must be named `sast` and the artifact path must be
 `gl-sast-report.json`.

doc/ci/examples/sast_docker.md

+# Static Application Security Testing for Docker containers with GitLab CI/CD
+
+You can check your Docker 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.
+
+All you need is a GitLab Runner with the Docker executor (the shared Runners on
+GitLab.com will work fine). You can then add a new job to `.gitlab-ci.yml`,
+called `sast:container`:
+
+```yaml
+sast:container:
+  image: docker:latest
+  variables:
+    DOCKER_DRIVER: overlay2
+    ## Define two new variables based on GitLab's CI/CD predefined variables
+    ## https://docs.gitlab.com/ee/ci/variables/#predefined-variables-environment-variables
+    CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG
+    CI_APPLICATION_TAG: $CI_COMMIT_SHA
+  allow_failure: true
+  services:
+    - docker:dind
+  script:
+    - docker run -d --name db arminc/clair-db:latest
+    - docker run -p 6060:6060 --link db:postgres -d --name clair arminc/clair-local-scan:v2.0.1
+    - 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
+    - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-sast-container-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true
+  artifacts:
+    paths: [gl-sast-container-report.json]
+```
+
+The above example will create a `sast:container` job in your CI/CD pipeline, pull
+the image from the [Container Registry](../../user/project/container_registry.md)
+(whose name is defined from the two `CI_APPLICATION_` variables) and scan it
+for possible vulnerabilities. The report will be saved as an artifact that you
+can later download and analyze.
+
+If you want to whitelist some specific vulnerabilities, you can do so by defining
+them in a [YAML file](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file),
+in our case its named `clair-whitelist.yml`.
+
+TIP: **Tip:**
+Starting with [GitLab Enterprise Edition Ultimate][ee] 10.4, this information will
+be automatically extracted and shown right in the merge request widget. To do
+so, the CI/CD job must be named `sast:container` and the artifact path must be
+`gl-sast-container-report.json`.
+[Learn more on application security testing results shown in merge requests](../../user/project/merge_requests/sast_docker.md).
+
+[ee]: https://about.gitlab.com/gitlab-ee/

doc/topics/autodevops/index.md

@@ -20,6 +20,7 @@ project in an easy and automatic way:
 1. [Auto Test](#auto-test)
 1. [Auto Code Quality](#auto-code-quality)
 1. [Auto SAST (Static Application Security Testing)](#auto-sast)
+1. [Auto SAST for Docker images](#auto-sast-for-docker-images)
 1. [Auto Browser Performance Testing](#auto-browser-performance-testing)
 1. [Auto Review Apps](#auto-review-apps)
 1. [Auto Deploy](#auto-deploy)
@@ -209,17 +210,18 @@ check out.
 
 Any security warnings are also [shown in the merge request widget](../../user/project/merge_requests/sast.md).
 
-### Auto SAST
+### Auto SAST for Docker images
 
-> Introduced in [GitLab Enterprise Edition Ultimate][ee] 10.3.
+> Introduced in GitLab 10.4.
 
-Static Application Security Testing (SAST) uses the
-[gl-sast Docker image](https://gitlab.com/gitlab-org/gl-sast) to run static
-analysis on the current code and checks for potential security issues. Once the
-report is created, it's uploaded as an artifact which you can later download and
+Vulnerability Static Analysis for containers uses
+[Clair](https://github.com/coreos/clair) to run static analysis on a
+Docker image and checks for potential security issues. Once the report is
+created, it's uploaded as an artifact which you can later download and
 check out.
 
-Any security warnings are also [shown in the merge request widget](https://docs.gitlab.com/ee/user/project/merge_requests/sast.html).
+In GitLab Enterprise Edition Ultimate, any security warnings are also
+[shown in the merge request widget](../../user/project/merge_requests/sast_docker.md).
 
 ### Auto Browser Performance Testing
 
@@ -233,7 +235,8 @@ Auto Browser Performance Testing utilizes the [Sitespeed.io container](https://h
 /direction
 ```
 
-In GitLab Enterprise Edition Premium, performance differences between the source and target branches are [shown in the merge request widget](https://docs.gitlab.com/ee/user/project/merge_requests/browser_performance_testing.html).
+In GitLab Enterprise Edition Premium, performance differences between the source
+and target branches are [shown in the merge request widget](../../user/project/merge_requests/browser_performance_testing.md).
 
 ### Auto Review Apps
 

doc/user/project/merge_requests/index.md

@@ -189,7 +189,6 @@ list of approvers that will need to approve every merge request in a project.
 
 [Read more about merge request approvals.](merge_request_approvals.md)
 
-
 ## Code Quality reports
 
 > Introduced in [GitLab Enterprise Edition Starter][products] 9.3.
@@ -211,6 +210,17 @@ merge request widget area.
 
 [Read more about Static Application Security Testing reports.](sast.md)
 
+## Static Application Security Testing for Docker containers
+
+> Introduced in [GitLab Enterprise Edition Ultimate][products] 10.4.
+
+If you are using [GitLab CI/CD][ci], you can analyze your Docker images for known
+vulnerabilities.
+Going a step further, GitLab can show the vulnerability report right in the
+merge request widget area.
+
+[Read more about SAST Docker images reports.](sast_docker.md)
+
 ## Browser Performance Testing
 
 > Introduced in [GitLab Enterprise Edition Premium][products] 10.3.
@@ -346,9 +356,8 @@ And to check out a particular merge request:
 git checkout origin/merge-requests/1
 ```
 
-[protected branches]: ../protected_branches.md
-
 [products]: https://about.gitlab.com/products/ "GitLab products page"
+[protected branches]: ../protected_branches.md
 [ci]: ../../../ci/README.md
 [cc]: https://codeclimate.com/
 [cd]: https://hub.docker.com/r/codeclimate/codeclimate/

doc/user/project/merge_requests/sast_docker.md

+# Static Application Security Testing for Docker containers
+
+> [Introduced][ee-3672] in [GitLab Enterprise Edition Ultimate][ee] 10.4.
+
+## Overview
+
+If you are using [GitLab CI/CD][ci], you can analyze your Docker images for known
+vulnerabilities using [Clair](https://github.com/coreos/clair),
+a Vulnerability Static Analysis tool for containers.
+
+Going a step further, GitLab can show the vulnerability list right in the merge
+request widget area.
+
+![SAST Widget](img/sast-image.png)
+
+## Use cases
+
+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.
+
+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.
+
+## How it works
+
+In order for the report to show in the merge request, you need to specify a
+`sast:container` job (exact name) that will analyze the code and upload the
+resulting `gl-sast-container-report.json` file as an artifact (exact filename).
+GitLab will then check this file and show the information inside the merge request.
+
+This JSON file needs to be the only artifact file for the job. If you try
+to also include other files, it will break the vulnerability display in the
+merge request.
+
+For more information on how the `sast:container` job should look like, check the
+example on [analyzing a Docker image for vulnerabilities][cc-docs].
+
+[ee-3672]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672
+[ee]: https://about.gitlab.com/gitlab-ee/
+[ci]: ../../../ci/README.md
+[cc-docs]: ../../../ci/examples/sast_docker.md