Merge branch 'add_dast_paths_file_to_dast_docs_258825' into 'master'

Add instruction for URL Scan using DAST_PATHS_FILE

See merge request gitlab-org/gitlab!45114

doc/user/application_security/dast/index.md

@@ -423,7 +423,51 @@ A URL scan allows you to specify which parts of a website are scanned by DAST.
 
 #### Define the URLs to scan
 
-To specify the paths to scan, add a comma-separated list of the paths to the `DAST_PATHS`
+URLs to scan can be specified by either of the following methods:
+
+- Use `DAST_PATHS_FILE` environment variable to specify the name of a file containing the paths.
+- Use `DAST_PATHS` environment variable to list the paths.
+
+##### Use DAST_PATHS_FILE environment variable
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6.
+
+To define the URLs to scan in a file, create a plain text file with one path per line.
+
+```txt
+page1.html
+/page2.html
+category/shoes/page1.html
+```
+
+To scan the URLs in that file, set the environment variable `DAST_PATHS_FILE` to the path of that file.
+
+```yaml
+include:
+  - template: DAST.gitlab-ci.yml
+
+variables:
+  DAST_PATHS_FILE: url_file.txt
+```
+
+By default, DAST scans do not clone the project repository. If the file is checked in to the project, instruct the DAST job to clone the project by setting GIT_STRATEGY to fetch. The file is expected to be in the `/zap/wrk` directory.
+
+```yaml
+dast:
+  script:
+    - mkdir -p /zap/wrk
+    - cp url_file.txt /zap/wrk/url_file.txt
+    - /analyze -t $DAST_WEBSITE
+  variables:
+    GIT_STRATEGY: fetch
+    DAST_PATHS_FILE: url_file.txt
+```
+
+##### Use DAST_PATHS environment variable
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4.
+
+To specify the paths to scan in an environment variable, add a comma-separated list of the paths to the `DAST_PATHS`
 environment variable. Note that you can only scan paths of a single host.
 
 ```yaml
@@ -434,10 +478,13 @@ variables:
   DAST_PATHS=/page1.html,/category1/page1.html,/page3.html
 ```
 
-When using `DAST_PATHS`, note the following:
+When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following:
 
+- `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either will use `DAST_WEBSITE` to build the URLs to scan
+- Spidering is disabed when `DAST_PATHS` or `DAST_PATHS_FILE` are defined
+- `DAST_PATHS_FILE` and `DAST_PATHS` can not be used together
 - The `DAST_PATHS` environment variable has a limit of about 130kb. If you have a list or paths
-  greater than this, you should create multiple DAST jobs and split the paths over each job.
+  greater than this, use `DAST_PATHS_FILE`.
 
 #### Full Scan
 
@@ -498,6 +545,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia
 | `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
 | `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
 | `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. |
+| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be within `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. |
 | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
 | `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` |