Merge branch 'docs/dast-cleanup-ee' into 'master'

Add more info on how DAST works

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

doc/ci/examples/dast.md

 # 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.
+is using the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy)
+to perform an analysis on your running web application.
 
-DAST is using the popular open source tool
-[OWASP ZAProxy](https://github.com/zaproxy/zaproxy) to perform an analysis.
+It can be very useful combined with [Review Apps](../review_apps/index.md).
+
+## Example
 
 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`,
@@ -14,22 +15,26 @@ called `dast`:
 ```yaml
 dast:
   image: owasp/zap2docker-stable
+  variables:
+    website: "https://example.com"
   script:
     - mkdir /zap/wrk/
-    - /zap/zap-baseline.py -J gl-dast-report.json -t https://example.com || true
+    - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true
     - cp /zap/wrk/gl-dast-report.json .
   artifacts:
     paths: [gl-dast-report.json]
 ```
 
-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.
+The above example will create a `dast` job in your CI/CD pipeline which will run
+the tests on the URL defined in the `website` variable (change it to use your
+own) and finally write the results in the `gl-dast-report.json` file. You can
+then download and analyze the report artifact in JSON format.
 
 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 job must be named `dast` and the artifact path must be
 `gl-dast-report.json`.
-[Learn more on dynamic application security testing results shown in merge requests](../../user/project/merge_requests/dast.md).
+[Learn more about DAST results shown in merge requests](../../user/project/merge_requests/dast.md).
 
 [ee]: https://about.gitlab.com/gitlab-ee/

doc/user/project/merge_requests/dast.md

@@ -2,42 +2,54 @@
 
 > [Introduced][ee-4348] in [GitLab Enterprise Edition Ultimate][ee] 10.4.
 
+If you are using [GitLab CI/CD][ci], you can analyze your running web application(s)
+for known vulnerabilities using Dynamic Application Security Testing (DAST).
+
 ## Overview
 
-If you are using [GitLab CI/CD][ci], you can analyze your web application for known
-vulnerabilities using Dynamic Application Security Testing (DAST), either by
-including the CI job in your [existing `.gitlab-ci.yml` file][cc-docs] or
-by implicitly using [Auto DAST](../../../topics/autodevops/index.md#auto-dast)
+Running [static checks](sast.md) on your code is the first step to detect
+vulnerabilities that can put the security of your code at risk. Yet, once
+deployed, your application is exposed to a new category of possible attacks,
+such as cross-site scripting or broken authentication flaws. This is where
+Dynamic Application Security Testing (DAST) comes into place.
+
+You can take advantage of DAST by either [including the CI job][cc-docs] in
+your existing `.gitlab-ci.yml` file or by implicitly using
+[Auto DAST](../../../topics/autodevops/index.md#auto-dast)
 that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
 
 Going a step further, GitLab can show the vulnerability list right in the merge
 request widget area.
 
-![DAST Widget](img/dast-all.png)
+## Use cases
 
-By clicking on vulnerability you will be able to see the details and the URL(s)
-affected.
+It helps you automatically find security vulnerabilities in your running web
+applications while you are developing and testing your applications.
 
-![DAST Widget Clicked](img/dast-single.png)
+## How it works
 
-## Use cases
+First of all, you need to define a job named `dast` in your `.gitlab-ci.yml`
+file. [Check how the `dast` job should look like][cc-docs].
 
-It helps you automatically find security vulnerabilities in your web applications
-while you are developing and testing your applications.
+In order for the report to show in the merge request, there are two
+prerequisites:
 
-## How it works
+- the specified job **must** be named `dast`
+- the resulting report **must** be named `gl-dast-report.json` and uploaded as an
+  artifact. 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.
+
+The `sast` job will perform an analysis on the running web application, the
+resulting JSON file will be uploaded as an artifact, and GitLab will then check
+this file and show the information inside the merge request.
 
-In order for the report to show in the merge request, you need to specify a
-`dast` job (exact name) that will analyze the running application and upload the
-resulting `gl-dast-report.json` file (exact filename) as an artifact. GitLab
-will then check this file and show the information inside the merge request.
+![DAST Widget](img/dast_all.png)
 
-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.
+By clicking on one of the detected linked vulnerabilities, you will be able to
+see the details and the URL(s) affected.
 
-For more information on how the `dast` job should look like, check the
-[example on analyzing a project's code for vulnerabilities][cc-docs].
+![DAST Widget Clicked](img/dast_single.png)
 
 [ee-4348]: https://gitlab.com/gitlab-org/gitlab-ee/issues/4348
 [ee]: https://about.gitlab.com/gitlab-ee/