diff options
Diffstat (limited to 'doc/user/application_security/dast/index.md')
| -rw-r--r-- | doc/user/application_security/dast/index.md | 76 |
1 files changed, 62 insertions, 14 deletions
diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 65ddece1bde..1093e7cfabd 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -144,6 +144,14 @@ image. Using the `DAST_VERSION` variable, you can choose how DAST updates: Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page. +#### Crawling web applications dependent on JavaScript + +GitLab has released a new browser-based crawler, an add-on to DAST that uses a browser to crawl web applications for content. This crawler replaces the standard DAST Spider and Ajax Crawler. + +The browser-based crawler crawls websites by browsing web pages as a user would. This approach works well with web applications that make heavy use of JavaScript, such as Single Page Applications. + +For more details, including setup instructions, see [DAST browser-based crawler](browser_based.md). + ## Deployment options Depending on the complexity of the target application, there are a few options as to how to deploy and configure @@ -452,11 +460,14 @@ configured to act as a remote proxy and add the `Gitlab-DAST-Permission` header. ### API scan -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +> - A new DAST API scanning engine was introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. Using an API specification as a scan's target is a useful way to seed URLs for scanning an API. Vulnerability rules in an API scan are different than those in a normal website scan. +A new DAST API scanning engine is available in GitLab 13.12 and later. For more details, see [DAST API scanning engine](../dast_api). The new scanning engine supports REST, SOAP, GraphQL, and generic APIs using forms, XML, and JSON. Testing can be performed using OpenAPI, Postman Collections, and HTTP Archive (HAR) documents. + #### Specification format API scans support OpenAPI V2 and OpenAPI V3 specifications. You can define these specifications using `JSON` or `YAML`. @@ -471,7 +482,7 @@ include: - template: DAST.gitlab-ci.yml variables: - DAST_API_SPECIFICATION: http://my.api/api-specification.yml + DAST_API_OPENAPI: http://my.api/api-specification.yml ``` #### Import API specification from a file @@ -486,7 +497,7 @@ dast: - cp api-specification.yml /zap/wrk/api-specification.yml variables: GIT_STRATEGY: fetch - DAST_API_SPECIFICATION: api-specification.yml + DAST_API_OPENAPI: api-specification.yml ``` #### Full API scan @@ -522,7 +533,7 @@ include: - template: DAST.gitlab-ci.yml variables: - DAST_API_SPECIFICATION: http://api-test.host.com/api-specification.yml + DAST_API_OPENAPI: http://api-test.host.com/api-specification.yml DAST_API_HOST_OVERRIDE: api-test.host.com ``` @@ -537,7 +548,7 @@ include: - template: DAST.gitlab-ci.yml variables: - DAST_API_SPECIFICATION: http://api-test.api.com/api-specification.yml + DAST_API_OPENAPI: http://api-test.api.com/api-specification.yml DAST_REQUEST_HEADERS: "Authorization: Bearer my.token" ``` @@ -610,10 +621,42 @@ When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: To perform a [full scan](#full-scan) on the listed paths, use the `DAST_FULL_SCAN_ENABLED` CI/CD variable. +### View details of a vulnerability detected by DAST + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +Vulnerabilities detected by DAST occur in the live web application. Addressing these types of +vulnerabilities requires specific information. DAST provides the information required to +investigate and rectify the underlying cause. + +To view details of vulnerabilities detected by DAST: + +1. To see all vulnerabilities detected, either: + - Go to your project and select **Security & Compliance**. + - Go to the merge request and select the **Security** tab. + +1. Select a vulnerability's description. The following details are provided: + + | Field | Description | + |:-----------------|:------------------------------------------------------------------ | + | Description | Description of the vulnerability. | + | Project | Namespace and project in which the vulnerability was detected. | + | Method | HTTP method used to detect the vulnerability. | + | URL | URL at which the vulnerability was detected. | + | Request Headers | Headers of the request. | + | Response Status | Response status received from the application. | + | Response Headers | Headers of the response received from the application. | + | Evidence | Evidence of the data found that verified the vulnerability. Often a snippet of the request or response, this can be used to help verify that the finding is a vulnerability. | + | Identifiers | Identifiers of the vulnerability. | + | Severity | Severity of the vulnerability. | + | Scanner Type | Type of vulnerability report. | + | Links | Links to further details of the detected vulnerability. | + | Solution | Details of a recommended solution to the vulnerability (optional). | + ### Customizing the DAST settings WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. The DAST settings can be changed through CI/CD variables by using the @@ -641,8 +684,9 @@ DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. | CI/CD variable | Type | Description | |------------------------------| --------|-------------| | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | -| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_OPENAPI` must be specified if this is omitted. | +| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | | `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | | `DAST_AUTH_VERIFICATION_URL` | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST will exit if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. @@ -658,6 +702,7 @@ DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | | `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. 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`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. 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). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | | `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | | `DAST_DEBUG` | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | @@ -794,9 +839,9 @@ For DAST, import the following default DAST analyzer image from `registry.gitlab 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're able to make periodic updates yourself. +process by which external resources can be imported or temporarily accessed. +These scanners are [periodically updated](../vulnerabilities/index.md#vulnerability-scanner-maintenance) +with new definitions, and you may be able to make occasional updates on your own. 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/), @@ -944,15 +989,18 @@ required for an on-demand DAST scan. A site profile contains the following: - **Profile name**: A name you assign to the site to be scanned. +- **Site type**: The type of target to be scanned, either website or API scan. - **Target URL**: The URL that DAST runs against. - **Excluded URLs**: A comma-separated list of URLs to exclude from the scan. - **Request headers**: A comma-separated list of HTTP request headers, including names and values. These headers are added to every request made by DAST. - **Authentication**: - - **Authenticated URL**: The URL of the page containing the sign-in HTML form on the target website. The username and password are submitted with the login form to create an authenticated scan. + - **Authenticated URL**: The URL of the page containing the sign-in HTML form on the target website. The username and password are submitted with the login form to create an authenticated scan. - **Username**: The username used to authenticate to the website. - **Password**: The password used to authenticate to the website. - - **Username form field**: The name of username field at the sign-in HTML form. - - **Password form field**: The name of password field at the sign-in HTML form. + - **Username form field**: The name of username field at the sign-in HTML form. + - **Password form field**: The name of password field at the sign-in HTML form. + +When an API site type is selected, a [host override](#host-override) is used to ensure the API being scanned is on the same host as the target. This is done to reduce the risk of running an active scan against the wrong API. #### Site profile validation |