Merge branch 'doc-add-dast-usage-examples' into 'master'

Documentation for advanced configuration of DAST

See merge request gitlab-org/gitlab!23940

doc/user/application_security/dast/index.md

@@ -291,15 +291,9 @@ As the DAST job belongs to a separate `dast` stage that runs after all
 [default stages](../../../ci/yaml/README.md#stages),
 don't forget to add `stage: dast` when you override the template job definition.
 
-## Available variables
+### Available variables
 
 DAST can be [configured](#customizing-the-dast-settings) using environment variables.
-Since it's a wrapper around the ZAP scanning scripts
-([baseline](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan)
-or [full](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) scan), it
-accepts all arguments those scripts recognize (the arguments are the same).
-The choice of the scan type depends on the `DAST_FULL_SCAN_ENABLED` environment
-variable value.
 
 | Environment variable        | Required   | Description                                                                    |
 |-----------------------------| ----------|--------------------------------------------------------------------------------|
@@ -314,14 +308,83 @@ variable value.
 | `DAST_FULL_SCAN_ENABLED` | no | Switches the tool to execute [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. |
 | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | no | Requires [domain validation](#domain-validation) when running DAST full scans. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. |
 
-## Reports JSON format
+### DAST command-line options
+
+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
+include:
+  template: DAST.gitlab-ci.yml
+
+dast:
+  script:
+    - /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:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+dast:
+  script:
+    - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)}
+    - /analyze -j -t $DAST_WEBSITE
+```
+
+### 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:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+dast:
+  script:
+    - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)}
+    - /analyze -z"-config replacer.full_list\(0\).description=auth -config replacer.full_list\(0\).enabled=true -config replacer.full_list\(0\).matchtype=REQ_HEADER -config replacer.full_list\(0\).matchstr=Authorization -config replacer.full_list\(0\).regex=false -config replacer.full_list\(0\).replacement=TOKEN" -t $DAST_WEBSITE
+```
+
+## Reports
+
+The DAST job can emit various reports.
+
+### JSON
 
 CAUTION: **Caution:**
-The JSON report artifacts are not a public API of DAST and their format may change in the future.
+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 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.
 
-The DAST tool emits a JSON report report file. Sample report files can be found in the [DAST repository](https://gitlab.com/gitlab-org/security-products/dast/tree/master/test/end-to-end/expect).
+### Other formats
 
-There are two formats of data in the JSON document 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.
+Reports can also be generated in Markdown, HTML, and XML.
+
+Reports can be published as artifacts using the following configuration:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+dast:
+  script:
+    - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)}
+    - /analyze -r report.html -w report.md -x report.xml -t $DAST_WEBSITE
+    - cp /zap/wrk/report.{html,md,xml} "$PWD"
+  artifacts:
+    paths:
+      - report.html
+      - report.md
+      - report.xml
+      - gl-dast-report.json
+```
 
 ## Security Dashboard
 
@@ -329,6 +392,20 @@ The Security Dashboard is a good place to get an overview of all the security
 vulnerabilities in your groups, projects and pipelines. Read more about the
 [Security Dashboard](../security_dashboard/index.md).
 
+## 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:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+dast:
+  script:
+    - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)}
+    - /analyze -a -t $DAST_WEBSITE
+```
+
 ## Interacting with the vulnerabilities
 
 Once a vulnerability is found, you can interact with it. Read more on how to