diff options
Diffstat (limited to 'doc/user/application_security/dast/index.md')
| -rw-r--r-- | doc/user/application_security/dast/index.md | 111 |
1 files changed, 73 insertions, 38 deletions
diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index cfc679f13a7..256daae46d7 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,10 +1,13 @@ --- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- # Dynamic Application Security Testing (DAST) **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. NOTE: **4 of the top 6 attacks were application based.** Download our whitepaper, @@ -142,7 +145,14 @@ the site during a scan could lead to inaccurate results. ### Authentication -It's also possible to authenticate the user before performing the DAST checks: +It's also possible to authenticate the user before performing the DAST checks. + +Create masked variables to pass the credentials that DAST will use. +To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). +Note that the key of the username variable must be `DAST_USERNAME` +and the key of the password variable must be `DAST_PASSWORD`. + +Other variables that are related to authenticated scans are: ```yaml include: @@ -151,8 +161,6 @@ include: variables: DAST_WEBSITE: https://example.com DAST_AUTH_URL: https://example.com/sign-in - DAST_USERNAME: john.doe@example.com - DAST_PASSWORD: john-doe-password DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between @@ -439,7 +447,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | Environment variable | Required | Description | |-----------------------------| -----------|--------------------------------------------------------------------------------| -| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address from which to download the analyzer. | +| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address from which to download the analyzer. | | `DAST_WEBSITE` | no| The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | | `DAST_API_SPECIFICATION` | no | The API specification to import. `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_AUTH_URL` | no | The authentication URL of the website to scan. Not supported for API scans. | @@ -455,7 +463,15 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `DAST_API_HOST_OVERRIDE` | no | Used to override domains defined in API specification files. | | `DAST_EXCLUDE_RULES` | no | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from the scan report. Currently, excluded rules will get executed but the alerts from them will be suppressed. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. | | `DAST_REQUEST_HEADERS` | no | Set to a comma-separated list of request header names and values. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_ZAP_USE_AJAX_SPIDER` | no | Use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | +| `DAST_DEBUG` | no | Enable debug message output. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | +| `DAST_SPIDER_MINS` | no | The maximum duration of the spider scan in minutes. Set to zero for unlimited. Defaults to one minute, or unlimited when the scan is a full scan. | +| `DAST_HTML_REPORT` | no | The file name of the HTML report written at the end of a scan. | +| `DAST_MARKDOWN_REPORT` | no | The file name of the Markdown report written at the end of a scan. | +| `DAST_XML_REPORT` | no | The file name of the XML report written at the end of a scan. | +| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | no | Include alpha passive and active scan rules. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | +| `DAST_USE_AJAX_SPIDER` | no | Use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | +| `DAST_ZAP_CLI_OPTIONS` | no | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | +| `DAST_ZAP_LOG_CONFIGURATION` | no | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG` | ### DAST command-line options @@ -472,8 +488,9 @@ dast: - /analyze --help ``` -You must then overwrite the `script` command to pass in the appropriate argument. -For example, debug messages can be enabled by using `-d`, as shown in the following configuration: +You must then overwrite the `script` command to pass in the appropriate +argument. For example, passive scanning can be delayed using option `-D`. The following +configuration delays passive scanning by five minutes: ```yaml include: @@ -482,14 +499,14 @@ include: dast: script: - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -d -t $DAST_WEBSITE + - /analyze -D 300 -t $DAST_WEBSITE ``` ### Custom ZAProxy configuration -The ZAProxy server contains many [useful configurable values](https://gitlab.com/gitlab-org/gitlab/issues/36437#note_245801885). +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). +[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: @@ -497,10 +514,8 @@ when used. An example of how to rewrite the Authorization header value with `TOK 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 +variables: + DAST_ZAP_CLI_OPTIONS: "-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" ``` ### Cloning the project's repository @@ -508,6 +523,29 @@ dast: The DAST job does not require the project's repository to be present when running, so by default [`GIT_STRATEGY`](../../../ci/yaml/README.md#git-strategy) is set to `none`. +### Debugging DAST jobs + +A DAST job has two executing processes: + +- The ZAP server. +- A series of scripts that start, control and stop the ZAP server. + +Debug mode of the scripts can be enabled by using the `DAST_DEBUG` environment variable. This can help when troubleshooting the job, +and will output statements indicating what percentage of the scan is complete. +For details on using variables, see [Overriding the DAST template](#overriding-the-dast-template). + +Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` environment variable. +The following table outlines examples of values that can be set and the effect that they have on the output that is logged. +Multiple values can be specified, separated by semicolons. + +| Log configuration value | Effect | +|-------------------------------------------------- | ----------------------------------------------------------------- | +| `log4j.rootLogger=DEBUG` | Enable all debug logging statements. | +| `log4j.logger.org.apache.commons.httpclient=DEBUG` | Log every HTTP request and response made by the ZAP server. | +| `log4j.logger.com.crawljax=DEBUG` | Enable Ajax Crawler debug logging statements. | +| `log4j.logger.org.parosproxy.paros=DEBUG` | Enable ZAP server proxy debug logging statements. | +| `log4j.logger.org.zaproxy.zap=DEBUG` | Enable debug logging statements of the general ZAP server code. | + ## Running DAST in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access @@ -568,7 +606,8 @@ Alternatively, you can use the variable `SECURE_ANALYZERS_PREFIX` to override th ## Reports -The DAST job can emit various reports. +The DAST tool outputs a report file in JSON format by default. However, this tool can also generate reports in +Markdown, HTML, and XML. For more information, see the [schema for DAST reports](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dast-report-format.json). ### List of URLs scanned @@ -593,24 +632,22 @@ There are two formats of data in the JSON report that are used side by side: ### Other formats -Reports can also be generated in Markdown, HTML, and XML. - -Reports can be published as artifacts using the following configuration: +Reports can also be generated in Markdown, HTML, and XML. These 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" + variables: + DAST_HTML_REPORT: report.html + DAST_MARKDOWN_REPORT: report.md + DAST_XML_REPORT: report.xml artifacts: paths: - - report.html - - report.md - - report.xml + - $DAST_HTML_REPORT + - $DAST_MARKDOWN_REPORT + - $DAST_XML_REPORT - gl-dast-report.json ``` @@ -622,18 +659,18 @@ 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: +ZAP 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 the +`DAST_INCLUDE_ALPHA_VULNERABILITIES` environment variable 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 +variables: + DAST_INCLUDE_ALPHA_VULNERABILITIES: true ``` ## Interacting with the vulnerabilities @@ -685,16 +722,14 @@ This results in the following error: ``` Fortunately, it's straightforward to increase the amount of memory available -for DAST by overwriting the `script` key in the DAST template: +for DAST by using the `DAST_ZAP_CLI_OPTIONS` environment variable: ```yaml include: - template: DAST.gitlab-ci.yml -dast: - script: - - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -t $DAST_WEBSITE -z"-Xmx3072m" +variables: + DAST_ZAP_CLI_OPTIONS: "-Xmx3072m" ``` Here, DAST is being allocated 3072 MB. |