Merge branch 'docs-aqualls-dast' into 'master'

Docs: style cleanup of DAST page

See merge request gitlab-org/gitlab!31037

doc/.vale/gitlab/spelling-exceptions.txt

@@ -306,6 +306,7 @@ Slack
 Slony
 SMTP
 Sourcegraph
+spidering
 Splunk
 SSH
 storable

doc/user/application_security/dast/index.md

@@ -19,16 +19,15 @@ Dynamic Application Security Testing (DAST) comes into place.
 
 ## Overview
 
-If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web application(s)
+If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web applications
 for known vulnerabilities using Dynamic Application Security Testing (DAST).
-
 You can take advantage of DAST by either [including the CI job](#configuration) in
 your existing `.gitlab-ci.yml` file or by implicitly using
-[Auto DAST](../../../topics/autodevops/stages.md#auto-dast-ultimate)
-that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
+[Auto DAST](../../../topics/autodevops/stages.md#auto-dast-ultimate),
+provided by [Auto DevOps](../../../topics/autodevops/index.md).
 
 GitLab checks the DAST report, compares the found vulnerabilities between the source and target
-branches, and shows the information right on the merge request.
+branches, and shows the information on the merge request.
 
 NOTE: **Note:**
 This comparison logic uses only the latest pipeline executed for the target branch's base commit.
@@ -36,28 +35,32 @@ Running the pipeline on any other commit has no effect on the merge request.
 
 ![DAST Widget](img/dast_all_v12_9.png)
 
-By clicking on one of the detected linked vulnerabilities, you will be able to
+By clicking on one of the detected linked vulnerabilities, you can
 see the details and the URL(s) affected.
 
 ![DAST Widget Clicked](img/dast_single_v12_9.png)
 
 [Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_Application_Security_Testing)
-is using the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy)
+uses the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy)
 to perform an analysis on your running web application.
 
-By default, DAST executes [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan) and will perform passive scanning only. It will not actively attack your application.
-
+By default, DAST executes [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan)
+and performs passive scanning only. It won't actively attack your application.
 However, DAST can be [configured](#full-scan)
-to also perform a so-called "active scan". That is, attack your application and produce a more extensive security report.
+to also perform an *active scan*: attack your application and produce a more extensive security report.
 It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md).
 
 NOTE: **Note:**
-A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show DAST scanner output. For example, if the DAST job finishes but the SAST job fails, the security dashboard will not show DAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure.
+A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any
+job fails to finish for any reason, the security dashboard won't show DAST scanner
+output. For example, if the DAST job finishes but the SAST job fails, the security
+dashboard won't show DAST results. The analyzer will output an
+[exit code](../../../development/integrations/secure.md#exit-code) on failure.
 
 ## Use cases
 
 It helps you automatically find security vulnerabilities in your running web
-applications while you are developing and testing your applications.
+applications while you're developing and testing your applications.
 
 ## Requirements
 
@@ -69,9 +72,8 @@ To run a DAST job, you need GitLab Runner with the
 For GitLab 11.9 and later, to enable DAST, you must
 [include](../../../ci/yaml/README.md#includetemplate) the
 [`DAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.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.
+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.
 
 Add the following to your `.gitlab-ci.yml` file:
 
@@ -88,32 +90,39 @@ There are two ways to define the URL to be scanned by DAST:
 1. Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables).
 
 1. Add it in an `environment_url.txt` file at the root of your project.
-    This is great for testing in dynamic environments. In order to run DAST against
-    an app that is dynamically created during a GitLab CI/CD pipeline, have the app
-    persist its domain in an `environment_url.txt` file, and DAST will
-    automatically parse that file to find its scan target.
-    You can see an [example](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml)
-    of this in our Auto DevOps CI YML.
+   This is great for testing in dynamic environments. In order to run DAST against
+   an app dynamically created during a GitLab CI/CD pipeline, have the app
+   persist its domain in an `environment_url.txt` file, and DAST
+   automatically parses that file to find its scan target.
+   You can see an [example](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml)
+   of this in our Auto DevOps CI YML.
 
-If both values are set, the `DAST_WEBSITE` value will take precedence.
+If both values are set, the `DAST_WEBSITE` value takes precedence.
 
-The included template will create a `dast` job in your CI/CD pipeline and scan
+The included template creates a `dast` job in your CI/CD pipeline and scan
 your project's source code for possible vulnerabilities.
 
-The results will be saved as a
+The results are saved as a
 [DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast-ultimate)
 that you can later download and analyze. Due to implementation limitations we
 always take the latest DAST artifact available. Behind the scenes, the
 [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast)
 is used to run the tests on the specified URL and scan it for possible vulnerabilities.
 
-By default, the DAST template will use the latest major version of the DAST Docker image. Using the `DAST_VERSION` variable,
-you can choose to automatically update DAST with new features and fixes by pinning to a major version (e.g. 1), only update fixes by pinning to a minor version (e.g. 1.6) or prevent all updates by pinning to a specific version (e.g. 1.6.4).
+By default, the DAST template will use the latest major version of the DAST Docker
+image. Using the `DAST_VERSION` variable, you can choose how DAST updates:
+
+- Automatically update DAST with new features and fixes by pinning to a major version (such as `1`).
+- Only update fixes by pinning to a minor version (such as `1.6`).
+- Prevent all updates by pinning to a specific version (such as `1.6.4`).
+
 Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page.
 
 ### When DAST scans run
 
-When using `DAST.gitlab-ci.yml` template, the `dast` job is run last as shown in the example below. To ensure DAST is scanning the latest code, your CI pipeline should deploy changes to the web server in one of the jobs preceeding the `dast` job.
+When using `DAST.gitlab-ci.yml` template, the `dast` job is run last as shown in
+the example below. To ensure DAST is scanning the latest code, your CI pipeline
+should deploy changes to the web server in one of the jobs preceding the `dast` job.
 
 ```yaml
 stages:
@@ -123,9 +132,12 @@ stages:
   - dast
 ```
 
-Be aware that if your pipeline is configured to deploy to the same webserver in each run, running a pipeline while another is still running, could cause a race condition
-where one pipeline overwrites the code from another pipeline. The site to be scanned should be excluded from changes for the duration of a DAST scan.
-The only changes to the site should be from the DAST scanner. Be aware that any changes that users, scheduled tasks, database or code changes, other pipelines, or other scanners make to
+Be aware that if your pipeline is configured to deploy to the same webserver in
+each run, running a pipeline while another is still running, could cause a race condition
+where one pipeline overwrites the code from another pipeline. The site to be scanned
+should be excluded from changes for the duration of a DAST scan.
+The only changes to the site should be from the DAST scanner. Be aware that any
+changes that users, scheduled tasks, database changes, code changes, other pipelines, or other scanners make to
 the site during a scan could lead to inaccurate results.
 
 ### Authenticated scan
@@ -152,7 +164,10 @@ that you can later download and analyze.
 Due to implementation limitations, we always take the latest DAST artifact available.
 
 DANGER: **Danger:**
-**DO NOT** run an authenticated scan against a production server. When an authenticated scan is run, it may perform *any* function that the authenticated user can. This includes modifying and deleting data, submitting forms, following links, and so on. Only run an authenticated scan against a test server.
+**NEVER** run an authenticated scan against a production server. When an authenticated
+scan is run, it may perform *any* function that the authenticated user can. This
+includes actions like modifying and deleting data, submitting forms, and following links.
+Only run an authenticated scan against a test server.
 
 ### Full scan
 
@@ -173,7 +188,8 @@ The DAST job can be run anywhere, which means you can accidentally hit live web
 and potentially damage them. You could even take down your production environment.
 For that reason, you should use domain validation.
 
-Domain validation is not required by default. It can be required by setting the [environment variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to true.
+Domain validation is not required by default. It can be required by setting the
+[environment variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to `"true"`.
 
 ```yaml
 include:
@@ -184,19 +200,23 @@ variables:
   DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED: "true"
 ```
 
-Since ZAP full scan actively attacks the target application, DAST sends a ping to the target (normally defined in `DAST_WEBSITE` or `environment_url.txt`) beforehand.
-
-If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is false or unset, the scan will _proceed_ unless the response to the ping
-includes a `Gitlab-DAST-Permission` header with a value of `deny`.
+Since ZAP full scan actively attacks the target application, DAST sends a ping
+to the target (normally defined in `DAST_WEBSITE` or `environment_url.txt`) beforehand.
 
-If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is true, the scan will _exit_ unless the response to the ping
-includes a `Gitlab-DAST-Permission` header with a value of `allow`.
+- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `false` or unset, the scan will
+  proceed unless the response to the ping includes a `Gitlab-DAST-Permission`
+  header with a value of `deny`.
+- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `true`, the scan will exit
+  unless the response to the ping includes a `Gitlab-DAST-Permission` header with
+  a value of `allow`.
 
-Here are some examples of adding the `Gitlab-DAST-Permission` header to a response in Rails, Django, and Node (with Express).
+Here are some examples of adding the `Gitlab-DAST-Permission` header to a response
+in Rails, Django, and Node (with Express).
 
 ##### Ruby on Rails
 
-Here's how you would add a [custom header in Ruby on Rails](https://guides.rubyonrails.org/action_controller_overview.html#setting-custom-headers):
+Here's how you would add a
+[custom header in Ruby on Rails](https://guides.rubyonrails.org/action_controller_overview.html#setting-custom-headers):
 
 ```ruby
 class DastWebsiteTargetController < ActionController::Base
@@ -210,7 +230,8 @@ end
 
 ##### Django
 
-Here's how you would add a [custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields):
+Here's how you would add a
+[custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields):
 
 ```python
 class DastWebsiteTargetView(View):
@@ -223,7 +244,8 @@ class DastWebsiteTargetView(View):
 
 ##### Node (with Express)
 
-Here's how you would add a [custom header in Node (with Express)](http://expressjs.com/en/5x/api.html#res.append):
+Here's how you would add a
+[custom header in Node (with Express)](http://expressjs.com/en/5x/api.html#res.append):
 
 ```javascript
 app.get('/dast-website-target', function(req, res) {
@@ -238,7 +260,8 @@ It's also possible to add the `Gitlab-DAST-Permission` header via a proxy.
 
 ###### NGINX
 
-The following config allows NGINX to act as a reverse proxy and add the `Gitlab-DAST-Permission` [header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header):
+The following configuration allows NGINX to act as a reverse proxy and add the
+`Gitlab-DAST-Permission` [header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header):
 
 ```nginx
 # default.conf
@@ -290,7 +313,7 @@ API scans support OpenAPI V2 and OpenAPI V3 specifications. You can define these
 #### Import API specification from a URL
 
 If your API specification is accessible at a URL, you can pass that URL in directly as the target.
-The specification doesn't have to be hosted on the same host as the API being tested.
+The specification does not have to be hosted on the same host as the API being tested.
 
 ```yml
 include:
@@ -302,9 +325,11 @@ variables:
 
 #### Import API specification from a file
 
-If your API specification is in your repository, you can provide the specification's filename directly as the target. The specification file is expected to be in the `/zap/wrk` directory.
+If your API specification is in your repository, you can provide the specification's
+filename directly as the target. The specification file is expected to be in the
+`/zap/wrk` directory.
 
-```yml
+```yaml
 dast:
   script:
     - mkdir -p /zap/wrk
@@ -317,23 +342,27 @@ dast:
 
 #### Full scan
 
-API scans support full scanning, which can be enabled by using the `DAST_FULL_SCAN_ENABLED` environment variable. Domain validation isn't supported for full API scans.
+API scans support full scanning, which can be enabled by using the `DAST_FULL_SCAN_ENABLED`
+environment variable. Domain validation is not supported for full API scans.
 
 #### Host override
 
-Specifications often define a host, which contains a domain name and a port. The host referenced may be different than the host of the API's review instance.
-This can cause incorrect URLs to be imported, or a scan on an incorrect host. Use the `DAST_API_HOST_OVERRIDE` environment variable to override these values.
+Specifications often define a host, which contains a domain name and a port. The
+host referenced may be different than the host of the API's review instance.
+This can cause incorrect URLs to be imported, or a scan on an incorrect host.
+Use the `DAST_API_HOST_OVERRIDE` environment variable to override these values.
 
 For example, with a OpenAPI V3 specification containing:
 
-```yml
+```yaml
 servers:
   - url: https://api.host.com
 ```
 
-If the test version of the API is running at `https://api-test.host.com`, then the following DAST configuration can be used:
+If the test version of the API is running at `https://api-test.host.com`, then
+the following DAST configuration can be used:
 
-```yml
+```yaml
 include:
   - template: DAST.gitlab-ci.yml
 
@@ -346,9 +375,11 @@ Note that `DAST_API_HOST_OVERRIDE` is only applied to specifications imported by
 
 #### Authentication using headers
 
-Tokens in request headers are often used as a way to authenticate API requests. You can achieve this by using the `DAST_REQUEST_HEADERS` environment variable. Headers are applied to every request DAST makes.
+Tokens in request headers are often used as a way to authenticate API requests.
+You can achieve this by using the `DAST_REQUEST_HEADERS` environment variable.
+Headers are applied to every request DAST makes.
 
-```yml
+```yaml
 include:
   - template: DAST.gitlab-ci.yml
 
@@ -426,7 +457,8 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia
 
 ### DAST command-line options
 
-Not all DAST configuration is available via environment variables. To find out all possible options, run the following configuration.
+Not all DAST configuration is available via environment variables. To find out all
+possible options, run the following configuration.
 Available command-line options will be printed to the job log:
 
 ```yaml
@@ -438,7 +470,8 @@ dast:
     - /analyze --help
 ```
 
-You must then overwrite the `script` command to pass in the appropriate argument. For example, AJAX spidering can be enabled by using `-j`, as shown in the following configuration:
+You must then overwrite the `script` command to pass in the appropriate argument.
+For example, AJAX spidering can be enabled by using `-j`, as shown in the following configuration:
 
 ```yaml
 include:
@@ -453,8 +486,10 @@ dast:
 ### Custom ZAProxy configuration
 
 The ZAProxy server contains many [useful configurable values](https://gitlab.com/gitlab-org/gitlab/issues/36437#note_245801885).
-Many key/values for `-config` remain undocumented, but there is an untested list of [possible keys](https://gitlab.com/gitlab-org/gitlab/issues/36437#note_244981023).
-Note that these options are not supported by DAST, and may break the DAST scan when used. An example of how to rewrite the Authorization header value with `TOKEN` follows:
+Many key/values for `-config` remain undocumented, but there is an untested list of
+[possible keys](https://gitlab.com/gitlab-org/gitlab/issues/36437#note_244981023).
+Note that these options are not supported by DAST, and may break the DAST scan
+when used. An example of how to rewrite the Authorization header value with `TOKEN` follows:
 
 ```yaml
 include:
@@ -482,7 +517,9 @@ successfully run. For more information, see [Offline environments](../offline_de
 To use DAST in an offline environment, you need:
 
 - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements).
-- Docker Container Registry with a locally available copy of the DAST [container image](https://gitlab.com/gitlab-org/security-products/dast), found in the [DAST container registry](https://gitlab.com/gitlab-org/security-products/dast/container_registry).
+- Docker Container Registry with a locally available copy of the DAST
+  [container image](https://gitlab.com/gitlab-org/security-products/dast), found in the
+  [DAST container registry](https://gitlab.com/gitlab-org/security-products/dast/container_registry).
 
 NOTE: **Note:**
 GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
@@ -499,12 +536,15 @@ registry:
 
 The process for importing Docker images into a local offline Docker registry depends on
 **your network security policy**. Please consult your IT staff to find an accepted and approved
-process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
-with new definitions, so consider if you are able to make periodic updates yourself.
+process by which external resources can be imported or temporarily accessed. Note
+that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
+with new definitions, so consider if you're able to make periodic updates yourself.
 
 For details on saving and transporting Docker images as a file, see Docker's documentation on
-[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/),
-[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/).
+[`docker save`](https://docs.docker.com/engine/reference/commandline/save/),
+[`docker load`](https://docs.docker.com/engine/reference/commandline/load/),
+[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and
+[`docker import`](https://docs.docker.com/engine/reference/commandline/import/).
 
 ### Set DAST CI job variables to use local DAST analyzers
 
@@ -530,7 +570,8 @@ The DAST job can emit various reports.
 
 ### List of URLs scanned
 
-When DAST completes scanning, the merge request page states the number of URLs that were scanned. Click **View details** to view the web console output which includes the list of scanned URLs.
+When DAST completes scanning, the merge request page states the number of URLs scanned.
+Click **View details** to view the web console output which includes the list of scanned URLs.
 
 ![DAST Widget](img/dast_urls_scanned_v12_10.png)
 
@@ -539,9 +580,13 @@ When DAST completes scanning, the merge request page states the number of URLs t
 CAUTION: **Caution:**
 The JSON report artifacts are not a public API of DAST and their format is expected to change in the future.
 
-The DAST tool always emits a JSON report file called `gl-dast-report.json` and sample reports can be found in the [DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/master/test/end-to-end/expect).
+The DAST tool always emits a JSON report file called `gl-dast-report.json` and
+sample reports can be found in the
+[DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/master/test/end-to-end/expect).
 
-There are two formats of data in the JSON report that are used side by side: the proprietary ZAP format which will be eventually deprecated, and a "common" format which will be the default in the future.
+There are two formats of data in the JSON report that are used side by side: the
+proprietary ZAP format which will be eventually deprecated, and a "common" format
+which will be the default in the future.
 
 ### Other formats
 
@@ -574,7 +619,9 @@ vulnerabilities in your groups, projects and pipelines. Read more about the
 
 ## Bleeding-edge vulnerability definitions
 
-ZAProxy first creates rules in the `alpha` class. After a testing period with the community, they are promoted to `beta`. DAST uses `beta` definitions by default. To request `alpha` definitions, use `-a` as shown in the following configuration:
+ZAProxy first creates rules in the `alpha` class. After a testing period with the
+community, they are promoted to `beta`. DAST uses `beta` definitions by default.
+To request `alpha` definitions, use `-a` as shown in the following configuration:
 
 ```yaml
 include:
@@ -612,7 +659,8 @@ but commented out to help encourage others to add to it in the future. -->
 
 By default, DAST will download all artifacts defined by previous jobs in the pipeline. If
 your DAST job does not rely on `environment_url.txt` to define the URL under test or any other files created
-in previous jobs, we recommend you don't download artifacts. To avoid downloading artifacts, add the following to your `gitlab-ci.yml` file:
+in previous jobs, we recommend you don't download artifacts. To avoid downloading
+artifacts, add the following to your `gitlab-ci.yml` file:
 
 ```json
 dast:
@@ -626,14 +674,14 @@ dast:
 By default, ZAProxy, which DAST relies on, is allocated memory that sums to 25%
 of the total memory on the host.
 Since it keeps most of its information in memory during a scan,
-it is possible for DAST to run out of memory while scanning large applications.
+it's possible for DAST to run out of memory while scanning large applications.
 This results in the following error:
 
 ```plaintext
 [zap.out] java.lang.OutOfMemoryError: Java heap space
 ```
 
-Fortunately, it is straightforward to increase the amount of memory available
+Fortunately, it's straightforward to increase the amount of memory available
 for DAST by overwriting the `script` key in the DAST template:
 
 ```yaml