Refactor Docker SAST docs

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

@@ -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 of your docker image with GitLab CI/CD
+# Static Application Security Testing for Docker containers with GitLab CI/CD
 
-NOTE: **Note:**
-In order to use this tool, a [GitLab Enterprise Edition Ultimate][ee] license
-is needed.
+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:image`:
+called `sast:container`:
 
 ```yaml
-sast:image:
+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:
-    - setup_docker
     - 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
@@ -26,22 +30,26 @@ sast:image:
     - mv clair-scanner_linux_386 clair-scanner
     - chmod +x clair-scanner
     - touch clair-whitelist.yml
-    - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-sast-image-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true
+    - ./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-image-report.json]
+    paths: [gl-sast-container-report.json]
 ```
 
-The above example will create a `sast:image` job in your CI pipeline and will allow
-you to download and analyze the report artifact in JSON format.
+The above example will create a `sast:container` job in your CI 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.
 
-
-TODO: TELL ABOUT WHITELISTING HERE. 
+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 10.3, 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 `sast:image` and the artifact path must be
-`gl-sast-image-report.json`.
+so, the CI 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

@@ -212,15 +212,16 @@ Any security warnings are also [shown in the merge request widget](../../user/pr
 
 ### Auto SAST for Docker images
 
-> Introduced in [GitLab Enterprise Edition Ultimate][ee] 10.4.
+> Introduced in GitLab 10.4.
 
-Vulnerability Static Analysis for Containers. It uses the
-[clair](https://github.com/coreos/clair) to run static
-analysis on the current 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
+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](../../user/project/merge_requests/sast.md).
+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
 

doc/user/project/merge_requests/index.md

@@ -210,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.
@@ -220,17 +231,6 @@ GitLab runs the [Sitespeed.io container][sitespeed-container] and displays the d
 
 [Read more about Browser Performance Testing.](browser_performance_testing.md)
 
-## Static Application Security Testing for Docker images
-
-> 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 image reports.](sast_docker.md)
-
 ## Live preview with Review Apps
 
 If you configured [Review Apps](https://about.gitlab.com/features/review-apps/) for your project,

doc/user/project/merge_requests/sast_docker.md

-# Static Application Security Testing (SAST)
+# Static Application Security Testing for Docker containers
 
-> [Introduced][ee-3781] in [GitLab Enterprise Edition Ultimate][ee] 10.4.
+> [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 for known
+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 for Containers.
+a Vulnerability Static Analysis tool for containers.
 
 Going a step further, GitLab can show the vulnerability list right in the merge
-request widget area:
+request widget area.
 
 ![SAST Widget](img/sast-image.png)
 
 ## Use cases
 
-TODO: write
+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:image` job (exact name) that will analyze the code and upload the resulting
-`gl-sast-image-report.json` file as an artifact. GitLab will then check this file and
-show the information inside the merge request.
+`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:image` job should look like, check the
-example on [analyzing a project's code for vulnerabilities][cc-docs].
+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-3781]: https://gitlab.com/gitlab-org/gitlab-ee/issues/3781
+[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.md
+[cc-docs]: ../../../ci/examples/sast_docker.md