diff options
Diffstat (limited to 'doc/user/application_security')
18 files changed, 481 insertions, 251 deletions
diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md index 7940e072420..db0b2a32bcf 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -68,8 +68,12 @@ Install GitLab HAR Recorder: 1. Make sure proxy is used! 1. Stop the recorder. -To verify the HAR contains all requests, use the [HAR Viewer (online)](http://www.softwareishard.com/har/viewer/). -[Google Admin Toolbox HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/) +To verify the HAR contains all requests, use an online HAR viewer, for example: + +- [HAR Viewer](http://www.softwareishard.com/har/viewer/) +<!-- vale gitlab.Admin = NO --> +- [Google Admin Toolbox HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/) +<!-- vale gitlab.Admin = YES --> ### Insomnia API Client @@ -190,7 +194,9 @@ a text editor. Tools recommended for viewing HAR files include: - [HAR Viewer](http://www.softwareishard.com/har/viewer/) - (online) +<!-- vale gitlab.Admin = NO --> - [Google Admin Toolbox HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/) - (online) +<!-- vale gitlab.Admin = YES --> - [Fiddler](https://www.telerik.com/fiddler) - local - [Insomnia API Client](https://insomnia.rest/) - local diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 98e241ba3bd..674eee5e80a 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -38,7 +38,7 @@ Select **Configuration history** to see the `.gitlab-ci.yml` file's history. You can configure the following security controls: -- Static Application Security Testing (SAST) +- Static Application Security Testing (SAST) **(FREE)** - Select **Enable SAST** to configure SAST for the current project. For more details, read [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). - Dynamic Application Security Testing (DAST) **(ULTIMATE)** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 2b3d4dbfc0a..22b54bf019c 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -42,10 +42,20 @@ To enable container scanning in your pipeline, you need the following: shared runners on GitLab.com, then this is already the case. - An image matching the [supported distributions](#supported-distributions). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) - the Docker image to your project's container registry. If using a third-party container - registry, you might need to provide authentication credentials using the `DOCKER_USER` and - `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). + the Docker image to your project's container registry. - The name of the Docker image to scan, in the `DOCKER_IMAGE` [configuration variable](#available-cicd-variables). +- If you're using a third-party container registry, you might need to provide authentication + credentials through the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). + For example, if you are connecting to AWS ECR, you might use the following: + +```yaml +export AWS_ECR_PASSWORD=$(aws ecr get-login-password --region region) + +include: + - template: Security/Container-Scanning.gitlab-ci.yml + DOCKER_USER: AWS + DOCKER_PASSWORD: "$AWS_ECR_PASSWORD" +``` ## Configuration @@ -397,7 +407,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc We recommend that you set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) to fetch the latest vulnerabilities database on a preset schedule. Automating this with a pipeline means you do not have to do it manually each time. You can use the -following `.gitlab-yml.ci` example as a template. +following `.gitlab-ci.yml` example as a template. ```yaml variables: @@ -420,6 +430,39 @@ The above template works for a GitLab Docker registry running on a local install you're using a non-GitLab Docker registry, you must change the `$CI_REGISTRY` value and the `docker login` credentials to match your local registry's details. +#### Scan images in external private registries + +To scan an image in an external private registry, you must configure access credentials so the +container scanning analyzer can authenticate itself before attempting to access the image to scan. + +If you use the GitLab [Container Registry](../../packages/container_registry/), +the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables) +are set automatically and you can skip this configuration. + +This example shows the configuration needed to scan images in a private [Google Container Registry](https://cloud.google.com/container-registry/): + +```yaml +include: + - template: Security/Container-Scanning.gitlab-ci.yml + +container_scanning: + variables: + DOCKER_USER: _json_key + DOCKER_PASSWORD: "$GCP_CREDENTIALS" + DOCKER_IMAGE: "gcr.io/path-to-you-registry/image:tag" +``` + +Before you commit this configuration, [add a CI/CD variable](../../../ci/variables/#add-a-cicd-variable-to-a-project) +for `GCP_CREDENTIALS` containing the JSON key, as described in the +[Google Cloud Platform Container Registry documentation](https://cloud.google.com/container-registry/docs/advanced-authentication#json-key). +Also: + +- The value of the variable may not fit the masking requirements for the **Mask variable** option, + so the value could be exposed in the job logs. +- Scans may not run in unprotected feature branches if you select the **Protect variable** option. +- Consider creating credentials with read-only permissions and rotating them regularly if the + options aren't selected. + ## Running the standalone container scanning tool It's possible to run the [GitLab container scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 0d5eb2b6d50..cdb2e7109bf 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -7,15 +7,26 @@ type: reference, howto # Coverage-guided fuzz testing **(ULTIMATE)** +Coverage-guided fuzzing sends random inputs to an instrumented version of your application in an +effort to cause unexpected behavior. Such behavior indicates a bug that you should address. GitLab allows you to add coverage-guided fuzz testing to your pipelines. This helps you discover -bugs and potential security issues that other QA processes may miss. Coverage-guided fuzzing sends -random inputs to an instrumented version of your application in an effort to cause unexpected -behavior, such as a crash. Such behavior indicates a bug that you should address. +bugs and potential security issues that other QA processes may miss. We recommend that you use fuzz testing in addition to the other security scanners in [GitLab Secure](../index.md) and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), -you can run your coverage-guided fuzz tests as part your CI/CD workflow. You can take advantage of -coverage-guided fuzzing by including the CI job in your existing `.gitlab-ci.yml` file. +you can run your coverage-guided fuzz tests as part your CI/CD workflow. + +## Coverage-guided fuzz testing process + +The fuzz testing process: + +1. Compiles the target application. +1. Runs the instrumented application, using the `gitlab-cov-fuzz` tool. +1. Parses and analyzes the exception information output by the fuzzer. +1. Downloads the [corpus](../terminology/index.md#corpus) and crash events from previous pipelines. +1. Outputs the parsed crash events and data to the `gl-coverage-fuzzing-report.json` file. + +The results of the coverage-guided fuzz testing are available in the CI/CD pipeline. ## Supported fuzzing engines and languages @@ -249,6 +260,8 @@ which shows an overview of all the security vulnerabilities in your groups, proj Clicking the vulnerability opens a modal that provides additional information about the vulnerability: +<!-- vale gitlab.Acronyms = NO --> + - Status: The vulnerability's status. As with any type of vulnerability, a coverage fuzzing vulnerability can be Detected, Confirmed, Dismissed, or Resolved. - Project: The project in which the vulnerability exists. @@ -262,3 +275,5 @@ vulnerability: - Scanner: The scanner that detected the vulnerability (for example, Coverage Fuzzing). - Scanner Provider: The engine that did the scan. For Coverage Fuzzing, this can be any of the engines listed in [Supported fuzzing engines and languages](#supported-fuzzing-engines-and-languages). + +<!-- vale gitlab.Acronyms = YES --> diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index 1489b250e4b..5ffd47527c5 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -5,65 +5,64 @@ group: Threat Insights 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/#assignments --- -# CVE ID Requests **(FREE SAAS)** +# CVE ID request **(FREE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. -As part of [our role as a CVE Numbering Authority](https://about.gitlab.com/security/cve/) -([CNA](https://cve.mitre.org/cve/cna.html)), you may request -[CVE](https://cve.mitre.org/index.html) identifiers from GitLab to track -vulnerabilities found within your project. +A [CVE](https://cve.mitre.org/index.html) identifier is assigned to a publicly-disclosed software +vulnerability. GitLab is a [CVE Numbering Authority](https://about.gitlab.com/security/cve/) +([CNA](https://cve.mitre.org/cve/cna.html)). For any public project you can request +a CVE identifier (ID). -## Overview +Assigning a CVE ID to a vulnerability in your project helps your users stay secure and informed. For +example, [dependency scanning tools](../application_security/dependency_scanning/index.md) can +detect when vulnerable versions of your project are used as a dependency. -CVE identifiers track specific vulnerabilities within projects. Having a CVE assigned to a -vulnerability in your project helps your users stay secure and informed. For example, -[dependency scanning tools](../application_security/dependency_scanning/index.md) -can detect when vulnerable versions of your project are used as a dependency. +A common vulnerability workflow is: -## Conditions +1. Request a CVE for a vulnerability. +1. Reference the assigned CVE identifier in release notes. +1. Publish the vulnerability's details after the fix is released. -If the following conditions are met, a **Request CVE ID** button appears in your issue sidebar: +## Prerequisites -- The project is hosted in GitLab.com. +To [submit a CVE ID Request](#submit-a-cve-id-request) the following prerequisites must be met: + +- The project is hosted on GitLab.com. - The project is public. - You are a maintainer of the project. -- The issue is [confidential](../project/issues/confidential_issues.md). - -## Submitting a CVE ID Request - -Clicking the **Request CVE ID** button in the issue sidebar takes you to the new issue page for -the [GitLab CVE project](https://gitlab.com/gitlab-org/cves). +- The vulnerability's issue is [confidential](../project/issues/confidential_issues.md). - +## Submit a CVE ID request -Creating the [confidential issue](../project/issues/confidential_issues.md) starts the CVE request process. +To submit a CVE ID request: - +1. Go to the vulnerability's issue and select **Create CVE ID Request**. The new issue page of + the [GitLab CVE project](https://gitlab.com/gitlab-org/cves) opens. -You are required to fill in the issue description, which includes: +  -- A description of the vulnerability -- The project's vendor and name -- Impacted versions -- Fixed versions -- The vulnerability type (a [CWE](https://cwe.mitre.org/data/index.html) identifier) -- A [CVSS v3 vector](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator) +1. In the **Title** box, enter a brief description of the vulnerability. -## CVE Assignment +1. In the **Description** box, enter the following details: -GitLab triages your submitted CVE ID request and communicates with you throughout the CVE validation -and assignment process. + - A detailed description of the vulnerability + - The project's vendor and name + - Impacted versions + - Fixed versions + - The vulnerability class (a [CWE](https://cwe.mitre.org/data/index.html) identifier) + - A [CVSS v3 vector](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator) - +  -Once a CVE identifier is assigned, you may use and reference it as you see fit. +GitLab updates your CVE ID request issue when: -Details of the vulnerability submitted in the CVE ID request are published according to your -schedule. It's common to request a CVE for an unpatched vulnerability, reference the assigned CVE -identifier in release notes, and later publish the vulnerability's details after the fix is -released. +- Your submission is assigned a CVE. +- Your CVE is published. +- MITRE is notified that your CVE is published. +- MITRE has added your CVE in the NVD feed. -Separate communications notify you when different stages of the publication process are complete. +## CVE assignment - +After a CVE identifier is assigned, you can reference it as required. Details of the vulnerability +submitted in the CVE ID request are published according to your schedule. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 5094ccd2196..9c5b84f4f36 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -10,13 +10,13 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323423) in GitLab 13.12. WARNING: -This product is an early access and is considered a [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) feature. +This product is in an early-access stage and is considered a [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) feature. GitLab DAST's new browser-based crawler is a crawl engine built by GitLab to test Single Page Applications (SPAs) and traditional web applications. Due to the reliance of modern web applications on JavaScript, handling SPAs or applications that are dependent on JavaScript is paramount to ensuring proper coverage of an application for Dynamic Application Security Testing (DAST). -The browser-based crawler works by loading the target application into a specially-instrumented Chromium browser. A snapshot of the page is taken prior to a search to find any actions that a user might perform, -such as clicking on a link or filling in a form. For each action found, the crawler will execute it, take a new snapshot and determine what in the page changed from the previous snapshot. +The browser-based crawler works by loading the target application into a specially-instrumented Chromium browser. A snapshot of the page is taken before a search to find any actions that a user might perform, +such as clicking on a link or filling in a form. For each action found, the crawler executes it, takes a new snapshot, and determines what in the page changed from the previous snapshot. Crawling continues by taking more snapshots and finding subsequent actions. The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don't understand. This results in better coverage of the website. @@ -57,17 +57,17 @@ The browser-based crawler can be configured using CI/CD variables. | `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | | `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | | `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | -| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but will likely produce little benefit after five to seven instances. | +| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com, we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but are likely to produce little benefit after five to seven instances. | | `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | | `DAST_BROWSER_LOG` | List of strings | `brows:debug,auth:debug` | A list of modules and their intended log level. | -| `DAST_BROWSER_NAVIGATION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `15s` | The maximum amount of time to wait for a browser to navigate from one page to another | -| `DAST_BROWSER_ACTION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to complete an action | -| `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis | -| `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after a navigation completes | -| `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `800ms` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after completing an action | -| `DAST_BROWSER_SEARCH_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `3s` | The maximum amount of time to allow the browser to search for new elements or navigations | -| `DAST_BROWSER_EXTRACT_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `5s` | The maximum amount of time to allow the browser to extract newly found elements or navigations | -| `DAST_BROWSER_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `600ms` | The maximum amount of time to wait for an element before determining it is ready for analysis | +| `DAST_BROWSER_NAVIGATION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `15s` | The maximum amount of time to wait for a browser to navigate from one page to another. | +| `DAST_BROWSER_ACTION_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to complete an action. | +| `DAST_BROWSER_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis. | +| `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after a navigation completes. | +| `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `800ms` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after completing an action. | +| `DAST_BROWSER_SEARCH_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `3s` | The maximum amount of time to allow the browser to search for new elements or navigations. | +| `DAST_BROWSER_EXTRACT_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `5s` | The maximum amount of time to allow the browser to extract newly found elements or navigations. | +| `DAST_BROWSER_ELEMENT_TIMEOUT` | [Duration string](https://golang.org/pkg/time/#ParseDuration) | `600ms` | The maximum amount of time to wait for an element before determining it is ready for analysis. | The [DAST variables](index.md#available-cicd-variables) `SECURE_ANALYZERS_PREFIX`, `DAST_FULL_SCAN_ENABLED`, `DAST_AUTO_UPDATE_ADDONS`, `DAST_EXCLUDE_RULES`, `DAST_REQUEST_HEADERS`, `DAST_HTML_REPORT`, `DAST_MARKDOWN_REPORT`, `DAST_XML_REPORT`, `DAST_AUTH_URL`, `DAST_USERNAME`, `DAST_PASSWORD`, `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, `DAST_SUBMIT_FIELD`, `DAST_EXCLUDE_URLS`, `DAST_AUTH_VERIFICATION_URL`, `DAST_BROWSER_AUTH_VERIFICATION_SELECTOR`, `DAST_BROWSER_AUTH_VERIFICATION_LOGIN_FORM`, `DAST_BROWSER_AUTH_REPORT`, @@ -80,27 +80,27 @@ While the browser-based crawler crawls modern web applications efficiently, vuln The crawler runs the target website in a browser with DAST/ZAP configured as the proxy server. This ensures that all requests and responses made by the browser are passively scanned by DAST/ZAP. When running a full scan, active vulnerability checks executed by DAST/ZAP do not use a browser. This difference in how vulnerabilities are checked can cause issues that require certain features of the target website to be disabled to ensure the scan works as intended. -For example, for a target website that contains forms with Anti-CSRF tokens, a passive scan will scan as intended because the browser displays pages/forms as if a user is viewing the page. -However, active vulnerability checks run in a full scan will not be able to submit forms containing Anti-CSRF tokens. In such cases we recommend you disable Anti-CSRF tokens when running a full scan. +For example, for a target website that contains forms with Anti-CSRF tokens, a passive scan works as intended because the browser displays pages and forms as if a user is viewing the page. +However, active vulnerability checks that run in a full scan cannot submit forms containing Anti-CSRF tokens. In such cases, we recommend you disable Anti-CSRF tokens when running a full scan. ## Managing scan time -It is expected that running the browser-based crawler will result in better coverage for many web applications, when compared to the normal GitLab DAST solution. +It is expected that running the browser-based crawler results in better coverage for many web applications, when compared to the normal GitLab DAST solution. This can come at a cost of increased scan time. You can manage the trade-off between coverage and scan time with the following measures: - Limit the number of actions executed by the browser with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_ACTIONS`. The default is `10,000`. - Limit the page depth that the browser-based crawler will check coverage on with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. -- Vertically scaling the runner and using a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. +- Vertically scale the runner and use a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. ## Timeouts Due to poor network conditions or heavy application load, the default timeouts may not be applicable to your application. -Browser-based scans offer the ability to adjust various timeouts to ensure it continues smoothly as it transitions from one page to the next. These values are configured using a [Duration string](https://golang.org/pkg/time/#ParseDuration) which allow you to configure durations with a prefix: `m` for minutes, `s` for seconds, and `ms` for milliseconds. +Browser-based scans offer the ability to adjust various timeouts to ensure it continues smoothly as it transitions from one page to the next. These values are configured using a [Duration string](https://golang.org/pkg/time/#ParseDuration), which allow you to configure durations with a prefix: `m` for minutes, `s` for seconds, and `ms` for milliseconds. -Navigations, or the act of loading a new page, usually require the most amount of time as they are +Navigations, or the act of loading a new page, usually require the most amount of time because they are loading multiple new resources such as JavaScript or CSS files. Depending on the size of these resources, or the speed at which they are returned, the default `DAST_BROWSER_NAVIGATION_TIMEOUT` may not be sufficient. Stability timeouts, such as those configurable with `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT`, `DAST_BROWSER_STABILITY_TIMEOUT`, and `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` can also be configured. Stability timeouts determine when browser-based scans consider @@ -110,11 +110,11 @@ a page fully loaded. Browser-based scans consider a page loaded when: 1. There are no open or outstanding requests that are deemed important, such as JavaScript and CSS. Media files are usually deemed unimportant. 1. Depending on whether the browser executed a navigation, was forcibly transitioned, or action: - - There are no new Document Object Model (DOM) modification events after the `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT`, `DAST_BROWSER_STABILITY_TIMEOUT` or `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` durations + - There are no new Document Object Model (DOM) modification events after the `DAST_BROWSER_NAVIGATION_STABILITY_TIMEOUT`, `DAST_BROWSER_STABILITY_TIMEOUT`, or `DAST_BROWSER_ACTION_STABILITY_TIMEOUT` durations. -After these events have occurred, browser-based scans consider the page loaded and ready and attempt the next action. +After these events have occurred, browser-based scans consider the page loaded and ready, and attempt the next action. -If your application experiences latency or returns many navigation failures, consider adjusting the timeout values such in this example: +If your application experiences latency or returns many navigation failures, consider adjusting the timeout values such as in this example: ```yaml include: @@ -132,7 +132,7 @@ dast: ``` NOTE: -Adjusting these values may impact scan time as they adjust how long each browser waits for various activities to complete. +Adjusting these values may impact scan time because they adjust how long each browser waits for various activities to complete. ## Debugging scans using logging @@ -168,7 +168,7 @@ The modules that can be configured for logging are as follows: | Log module | Component overview | | ---------- | ----------- | | `AUTH` | Used for creating an authenticated scan. | -| `BROWS` | Used for querying the state/page of the browser. | +| `BROWS` | Used for querying the state or page of the browser. | | `BPOOL` | The set of browsers that are leased out for crawling. | | `CRAWL` | Used for the core crawler algorithm. | | `DATAB` | Used for persisting data to the internal database. | diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index f771bc82d58..9969526c906 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -20,7 +20,7 @@ A DAST job has two executing processes: Enable the `DAST_DEBUG` CI/CD variable to debug scripts. This can help when troubleshooting the job, and outputs statements indicating what percentage of the scan is complete. -For details on using variables, see [Overriding the DAST template](index.md#customizing-the-dast-settings). +For details on using variables, see [Overriding the DAST template](index.md#customize-dast-settings). Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` variable. The following table outlines examples of values that can be set and the effect that they have on the output that is logged. diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 0d60701b030..09b55e7b395 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -269,7 +269,7 @@ image. Using the `DAST_VERSION` variable, you can choose how DAST updates: - 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/security-products/dast/-/releases) +Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page. #### Configure DAST using the UI @@ -483,6 +483,13 @@ 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. +### List URLs scanned + +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. + + + ### 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. @@ -515,15 +522,20 @@ To view details of vulnerabilities detected by DAST: | Links | Links to further details of the detected vulnerability. | | Solution | Details of a recommended solution to the vulnerability (optional). | -### Customizing the DAST settings +## Customize DAST settings + +You can customize the behavior of DAST using both CI/CD variables and command-line options. Use of CI/CD +variables overrides the values contained in the DAST template. + +### Customize DAST using CI/CD variables WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. +is no longer supported. You must use [`rules`](../../../ci/yaml/index.md#rules) instead. The DAST settings can be changed through CI/CD variables by using the -[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. -These variables are documented in [available variables](#available-cicd-variables). +[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`. For details of +all DAST CI/CD variables, read [Available CI/CD variables](#available-cicd-variables). For example: @@ -539,10 +551,10 @@ variables: Because the template is [evaluated before](../../../ci/yaml/index.md#include) the pipeline configuration, the last mention of the variable takes precedence. -#### Enabling and disabling rules +#### Enable or disable rules A complete list of the rules that DAST uses to scan for vulnerabilities can be -found in the [ZAP docs](https://www.zaproxy.org/docs/alerts/). +found in the [ZAP documentation](https://www.zaproxy.org/docs/alerts/). `DAST_EXCLUDE_RULES` disables the rules with the given IDs. @@ -559,7 +571,7 @@ can be found in [exclude_rules.yml](https://gitlab.com/gitlab-org/security-produ The lists for `DAST_EXCLUDE_RULES` and `DAST_ONLY_INCLUDE_RULES` **must** be enclosed in double quotes (`"`), otherwise they are interpreted as numeric values. -### Hide sensitive information +#### Hide sensitive information > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. @@ -573,7 +585,105 @@ authorization credentials. By default, the following headers are masked: Using the [`DAST_MASK_HTTP_HEADERS` CI/CD variable](#available-cicd-variables), you can list the headers whose values you want masked. For details on how to mask headers, see -[Customizing the DAST settings](#customizing-the-dast-settings). +[Customizing the DAST settings](#customize-dast-settings). + +#### Available CI/CD variables + +These CI/CD variables are specific to DAST. They can be used to customize the behavior of DAST to your requirements. + +| CI/CD variable | Type | Description | +|:-------------------------------------------------|:--------------|:------------------------------| +| `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | +| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | +| `DAST_API_HOST_OVERRIDE` <sup>1</sup> | 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_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. The variable `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` <sup>1</sup> | 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. The variable `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_AUTH_REPORT` <sup>2</sup> | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. | +| `DAST_AUTH_EXCLUDE_URLS` <sup>2</sup> | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_URLS`. The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | +| `DAST_AUTH_URL` <sup>1,2</sup> | 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. Example: `https://login.example.com`. | +| `DAST_AUTH_VERIFICATION_LOGIN_FORM` <sup>2</sup> | boolean | Verifies successful authentication by checking for the lack of a login form once the login form has been submitted. | +| `DAST_AUTH_VERIFICATION_SELECTOR` <sup>2</sup> | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo`. | +| `DAST_AUTH_VERIFICATION_URL` <sup>1,2</sup> | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. Example: `"http://example.com/loggedin_page"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | +| `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_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that will be clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | +| `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `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://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_EXCLUDE_URLS` <sup>1,2</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. Example, `http://example.com/sign-out`. | +| `DAST_FIRST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. For example, `css:button[type='user-submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` | +| `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `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_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | +| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | +| `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://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | +| `DAST_PASSWORD` <sup>1,2</sup> | string | The password to authenticate to in the website. Example: `P@55w0rd!` | +| `DAST_PASSWORD_FIELD` <sup>1,2</sup> | string | The selector of password field at the sign-in HTML form. Example: `id:password` | +| `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. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_REQUEST_HEADERS` <sup>1</sup> | 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_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | +| `DAST_SPIDER_MINS` <sup>1</sup> | 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. | +| `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_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. For example, `css:button[type='submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_TARGET_AVAILABILITY_TIMEOUT` <sup>1</sup> | number | Time limit in seconds to wait for target availability. | +| `DAST_USE_AJAX_SPIDER` <sup>1</sup> | 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_USERNAME` <sup>1,2</sup> | string | The username to authenticate to in the website. Example: `admin` | +| `DAST_USERNAME_FIELD` <sup>1,2</sup> | string | The selector of username field at the sign-in HTML form. Example: `name:username` | +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. The variable `DAST_API_OPENAPI` must be specified if this is omitted. | +| `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. Example: `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | +| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | + +1. Available to an on-demand DAST scan. +1. Used for authentication. + +### Customize DAST using command-line options + +Not all DAST configuration is available via CI/CD variables. To find out all +possible options, run the following configuration. +Available command-line options are 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, vulnerability definitions in alpha can be included with +`-a`. The following configuration includes those definitions: + +```yaml +include: + template: DAST.gitlab-ci.yml + +dast: + script: + - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} + - /analyze -a -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 + +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" +``` ## Authentication @@ -747,59 +857,6 @@ dast: when: always ``` -## Available CI/CD variables - -These CI/CD variables are specific to DAST. They can be used to customize the behavior of DAST to your requirements. - -| CI/CD variable | Type | Description | -|:-------------------------------------------------|:--------------|:------------------------------| -| `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | -| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | -| `DAST_API_HOST_OVERRIDE` <sup>1</sup> | 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_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. The variable `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` <sup>1</sup> | 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. The variable `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_AUTH_REPORT` <sup>2</sup> | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. | -| `DAST_AUTH_EXCLUDE_URLS` <sup>2</sup> | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_URLS`. The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | -| `DAST_AUTH_URL` <sup>1,2</sup> | 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. Example: `https://login.example.com`. | -| `DAST_AUTH_VERIFICATION_LOGIN_FORM` <sup>2</sup> | boolean | Verifies successful authentication by checking for the lack of a login form once the login form has been submitted. | -| `DAST_AUTH_VERIFICATION_SELECTOR` <sup>2</sup> | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo`. | -| `DAST_AUTH_VERIFICATION_URL` <sup>1,2</sup> | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. Example: `"http://example.com/loggedin_page"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | -| `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_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that will be clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | -| `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. The whole list **must** be enclosed in double quotes (`"`). Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | -| `DAST_EXCLUDE_URLS` <sup>1,2</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. Example, `http://example.com/sign-out`. | -| `DAST_FIRST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. For example, `css:button[type='user-submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` | -| `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | -| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `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_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | -| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | -| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. The whole list **must** be enclosed in double quotes (`"`). Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | -| `DAST_PASSWORD` <sup>1,2</sup> | string | The password to authenticate to in the website. Example: `P@55w0rd!` | -| `DAST_PASSWORD_FIELD` <sup>1,2</sup> | string | The selector of password field at the sign-in HTML form. Example: `id:password` | -| `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. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | -| `DAST_REQUEST_HEADERS` <sup>1</sup> | 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_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | -| `DAST_SPIDER_MINS` <sup>1</sup> | 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. | -| `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_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. For example, `css:button[type='submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `DAST_TARGET_AVAILABILITY_TIMEOUT` <sup>1</sup> | number | Time limit in seconds to wait for target availability. | -| `DAST_USE_AJAX_SPIDER` <sup>1</sup> | 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_USERNAME` <sup>1,2</sup> | string | The username to authenticate to in the website. Example: `admin` | -| `DAST_USERNAME_FIELD` <sup>1,2</sup> | string | The selector of username field at the sign-in HTML form. Example: `name:username` | -| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. The variable `DAST_API_OPENAPI` must be specified if this is omitted. | -| `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. Example: `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | -| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | - -1. Available to an on-demand DAST scan. -1. Used for authentication. - ### Selectors Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. @@ -848,51 +905,6 @@ When using selectors to locate specific fields we recommend you avoid searching - XPath searches as they are less performant than other selector searches. - Unscoped searches, such as those beginning with `css:*` and `xpath://*`. -### DAST command-line options - -Not all DAST configuration is available via CI/CD variables. To find out all -possible options, run the following configuration. -Available command-line options are 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, vulnerability definitions in alpha can be included with -`-a`. The following configuration includes those definitions: - -```yaml -include: - template: DAST.gitlab-ci.yml - -dast: - script: - - export DAST_WEBSITE=${DAST_WEBSITE:-$(cat environment_url.txt)} - - /analyze -a -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 - -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" -``` - ### Bleeding-edge vulnerability definitions ZAP first creates rules in the `alpha` class. After a testing period with @@ -1002,12 +1014,15 @@ The on-demand DAST scan runs, and the project's dashboard shows the results. #### Schedule an on-demand scan -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.4. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per user, -ask an administrator to [disable the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md). -The feature is not ready for production use. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an +administrator to [disable the feature flag](../../../administration/feature_flags.md) named +`dast_on_demand_scans_scheduler`. +On GitLab.com, this feature is available. To schedule a scan: @@ -1185,11 +1200,9 @@ If a validated site profile's target URL is edited, the site's validation status #### Retry a failed validation -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322609) in GitLab 14.3. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an -administrator to [disable the `dast_failed_site_validations` flag](../../../administration/feature_flags.md). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322609) in GitLab 14.3. +> - [Deployed behind the `dast_failed_site_validations` flag](../../../administration/feature_flags.md), enabled by default. +> - [Feature flag `dast_failed_site_validations` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323961) in GitLab 14.4. If a site profile's validation fails, you can retry it by selecting the **Retry validation** button in the profiles list. @@ -1308,7 +1321,7 @@ If a scanner profile is linked to a security policy, a user cannot delete the pr page. See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. -### Auditing +## Auditing > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. @@ -1320,13 +1333,6 @@ and DAST site profiles are included in the [audit log](../../../administration/a 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 - -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. - - - ### JSON WARNING: diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 055a2ceb161..3b1c91b0be4 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -635,7 +635,7 @@ can be added, removed, and modified by creating a custom configuration. | `DAST_API_TARGET_URL` | Base URL of API testing target. | |[`DAST_API_CONFIG`](#configuration-files) | DAST API configuration file. Defaults to `.gitlab-dast-api.yml`. | |[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | -|[`FUZZAPI_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | +|[`DAST_API_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | @@ -899,7 +899,7 @@ variables: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. -When testing an API it can be useful to exclude certain paths. For example, you might exclude testing of an authentication service or an older version of the API. To exclude paths, use the `FUZZAPI_EXCLUDE_PATHS` CI/CD variable . This variable is specified in your `.gitlab-ci.yml` file. To exclude multiple paths, separate entries using the `;` character. In the provided paths you can use a single character wildcard `?` and `*` for a multiple character wildcard. +When testing an API it can be useful to exclude certain paths. For example, you might exclude testing of an authentication service or an older version of the API. To exclude paths, use the `DAST_API_EXCLUDE_PATHS` CI/CD variable . This variable is specified in your `.gitlab-ci.yml` file. To exclude multiple paths, separate entries using the `;` character. In the provided paths you can use a single character wildcard `?` and `*` for a multiple character wildcard. To verify the paths are excluded, review the `Tested Operations` and `Excluded Operations` portion of the job output. You should not see any excluded paths listed under `Tested Operations`. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index fae0f457a20..8559d5af02e 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -47,7 +47,7 @@ In `.gitlab-ci.yml` define: ```yaml include: - template: Dependency-Scanning.gitlab-ci.yml + template: Security/Dependency-Scanning.gitlab-ci.yml variables: SECURE_ANALYZERS_PREFIX: my-docker-registry/gl-images @@ -64,7 +64,7 @@ In `.gitlab-ci.yml` define: ```yaml include: - template: Dependency-Scanning.gitlab-ci.yml + template: Security/Dependency-Scanning.gitlab-ci.yml variables: DS_EXCLUDED_ANALYZERS: "bundler-audit, gemnasium" @@ -77,7 +77,7 @@ In `.gitlab-ci.yml` define: ```yaml include: - template: Dependency-Scanning.gitlab-ci.yml + template: Security/Dependency-Scanning.gitlab-ci.yml variables: DS_EXCLUDED_ANALYZERS: "gemnasium, gemnasium-maven, gemnasium-python, bundler-audit, retire.js" diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index d903ce58982..1f840c96663 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -82,6 +82,7 @@ table.supported-languages tr td:last-child { } table.supported-languages ul { + font-size: 1em; list-style-type: none; padding-left: 0px; margin-bottom: 0px; @@ -346,7 +347,7 @@ Add the following to your `.gitlab-ci.yml` file: ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml ``` The included template creates dependency scanning jobs in your CI/CD @@ -380,7 +381,7 @@ For example: ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml variables: SECURE_LOG_LEVEL: error @@ -402,7 +403,7 @@ the `gemnasium` analyzer: ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml gemnasium-dependency_scanning: variables: @@ -413,7 +414,7 @@ To override the `dependencies: []` attribute, add an override job as above, targ ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml gemnasium-dependency_scanning: dependencies: ["build"] @@ -712,7 +713,7 @@ value of `GEMNASIUM_DB_REMOTE_URL` to the location of your offline Git copy of t ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml variables: SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers" @@ -867,7 +868,7 @@ to the supported `requirements.txt` as follows. ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml stages: - test @@ -926,3 +927,37 @@ gemnasium-maven-dependency_scanning: - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions) - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import ``` + +### Dependency Scanning job fails with message `strconv.ParseUint: parsing "0.0": invalid syntax` + +Invoking Docker-in-Docker is the likely cause of this error. Docker-in-Docker is: + +- Disabled by default in GitLab 13.0 and later. +- Unsupported from GitLab 13.4 and later. + +To fix this error, disable Docker-in-Docker for dependency scanning. Individual +`<analyzer-name>-dependency_scanning` jobs are created for each analyzer that runs in your CI/CD +pipeline. + +```yaml +include: + - template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DISABLE_DIND: "true" +``` + +### Message `<file> does not exist in <commit SHA>` + +When the `Location` of a dependency in a file is shown, the path in the link goes to a specific Git +SHA. + +If the lock file that our dependency scanning tools reviewed was cached, however, selecting that +link redirects you to the repository root, with the message: +`<file> does not exist in <commit SHA>`. + +The lock file is cached during the build phase and passed to the dependency scanning job before the +scan occurs. Because the cache is downloaded before the analyzer run occurs, the existence of a lock +file in the `CI_BUILDS_DIR` directory triggers the dependency scanning job. + +We recommend committing the lock files, which prevents this warning. diff --git a/doc/user/application_security/img/cve_request_communication.png b/doc/user/application_security/img/cve_request_communication.png Binary files differdeleted file mode 100644 index 5c58df463ef..00000000000 --- a/doc/user/application_security/img/cve_request_communication.png +++ /dev/null diff --git a/doc/user/application_security/img/cve_request_communication_publication.png b/doc/user/application_security/img/cve_request_communication_publication.png Binary files differdeleted file mode 100644 index 9eb6f2f8d9f..00000000000 --- a/doc/user/application_security/img/cve_request_communication_publication.png +++ /dev/null diff --git a/doc/user/application_security/img/new_cve_request_issue.png b/doc/user/application_security/img/new_cve_request_issue.png Binary files differindex 6ea7ca4a2ab..5f9deeb7bd9 100644 --- a/doc/user/application_security/img/new_cve_request_issue.png +++ b/doc/user/application_security/img/new_cve_request_issue.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index bd143d8608a..e1ddb3167ff 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -1,18 +1,14 @@ --- stage: Protect group: Container Security -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 +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/#assignments --- # Policies **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. Deployed behind a feature flag, disabled by default. -> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 14.3. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, -ask an administrator to [disable the `security_orchestration_policies_configuration` flag](../../../administration/feature_flags.md). -On GitLab.com, this feature is available. +> - Introduced in GitLab Ultimate 13.10 [with a flag](https://gitlab.com/groups/gitlab-org/-/epics/5329) named `security_orchestration_policies_configuration`. Disabled by default. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab Ultimate 14.3. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in GitLab 14.4. Policies in GitLab provide security teams a way to require scans of their choice to be run whenever a project pipeline runs according to the configuration specified. Security teams can @@ -28,8 +24,8 @@ GitLab supports the following security policies: The Policies page displays deployed policies for all available environments. You can check a -policy's information (for example description, enforcement -status, etc.), and create and edit deployed policies: +policy's information (for example, description or enforcement +status), and create and edit deployed policies: 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Security & Compliance > Policies**. @@ -53,7 +49,7 @@ users must make changes by following the ## Policy editor -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in GitLab Ultimate 13.4. You can use the policy editor to create, edit, and delete policies: @@ -83,7 +79,7 @@ mode to fix your policy before Rule mode is available again. ## Container Network Policy -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in GitLab Ultimate 12.9. The **Container Network Policy** section provides packet flow metrics for your application's Kubernetes namespace. This section has the following @@ -158,7 +154,7 @@ at the bottom of the editor. ### Configure a Network Policy Alert -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab Ultimate 13.9. > - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. You can use policy alerts to track your policy's impact. Alerts are only available if you've @@ -255,6 +251,10 @@ The policy editor currently only supports the YAML mode. The Rule mode is tracke The YAML file with Scan Execution Policies consists of an array of objects matching Scan Execution Policy Schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 policies under the `scan_execution_policy` key. +When you save a new policy, GitLab validates its contents against [this JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/validators/json_schemas/security_orchestration_policy.json). +If you're not familiar with how to read [JSON schemas](https://json-schema.org/), +the following sections and tables provide an alternative. + | Field | Type | Possible values | Description | |-------|------|-----------------|-------------| | `scan_execution_policy` | `array` of Scan Execution Policy | | List of scan execution policies (maximum 5) | @@ -291,6 +291,8 @@ This rule enforces the defined actions and schedules a scan on the provided date #### `cluster` schema +Use this schema to define `clusters` objects in the [`schedule` rule type](#schedule-rule-type). + | Field | Type | Possible values | Description | |--------------|---------------------|--------------------------|-------------| | `containers` | `array` of `string` | | The container name that will be scanned (only the first value is currently supported). | @@ -323,13 +325,16 @@ Note the following: - For a secret detection scan, only rules with the default ruleset are supported. [Custom rulesets](../secret_detection/index.md#custom-rulesets) are not supported. - A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in - [`historic`](../secret_detection/index.md#full-history-secret-scan) + [`historic`](../secret_detection/index.md#full-history-secret-detection) mode when executed as part of a scheduled scan. - A container scanning and cluster image scanning scans configured for the `pipeline` rule type will ignore the cluster defined in the `clusters` object. They will use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). -Here's an example: +### Example security policies project + +You can use this example in a `.gitlab/security-policies/policy.yml`, as described in +[Security policies project](#security-policies-project). ```yaml --- @@ -398,6 +403,24 @@ In this example: - Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. +### Example for scan execution policy editor + +You can use this example in the YAML mode of the [Scan Execution Policy editor](#scan-execution-policy-editor). +It corresponds to a single object from the previous example. + +```yaml +name: Enforce Secret Detection and Container Scanning in every default branch pipeline +description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch +enabled: true +rules: + - type: pipeline + branches: + - main +actions: + - scan: secret_detection + - scan: container_scanning +``` + ## Roadmap See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/) diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 3caa1771a5b..7ffefd34e40 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -27,6 +27,8 @@ analysis are available in the [security dashboards](../security_dashboard/index. The results are sorted by the priority of the vulnerability: +<!-- vale gitlab.SubstitutionWarning = NO --> + 1. Critical 1. High 1. Medium @@ -34,6 +36,8 @@ The results are sorted by the priority of the vulnerability: 1. Info 1. Unknown +<!-- vale gitlab.SubstitutionWarning = YES --> + A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard does not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard does not show SAST results. On failure, @@ -71,10 +75,11 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | | .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0 | | Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 | -| C | [Semgrep](https://semgrep.dev) | 14.2 | +| C | [Semgrep](https://semgrep.dev) | 14.2 | | C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | | Go | [Gosec](https://github.com/securego/gosec) | 10.7 | +| Go | [Semgrep](https://semgrep.dev) | 14.4 | | Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | | Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | | Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | @@ -184,26 +189,60 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. -### Configure SAST in the UI **(ULTIMATE)** +### Configure SAST in the UI + +You can enable and configure SAST in the UI, either with default settings, or with customizations. +Use the method that best meets your needs. + +- [Configure SAST in the UI with default settings](#configure-sast-in-the-ui-with-default-settings) +- [Configure SAST in the UI with customizations](#configure-sast-in-the-ui-with-customizations) + +### Configure SAST in the UI with default settings **(FREE)** + +> [Introduced](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#security-configuration-page-for-all-users) in GitLab 13.9 + +To enable and configure SAST with default settings: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance** > **Configuration**. +1. In the SAST section, select `Enable via MR`. +1. Review the draft MR that enables SAST with the default recommended settings in the + `.gitlab-ci.yml` file. +1. Merge the MR to enable SAST. You should see SAST jobs run in that MR's pipeline. + +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. + +### Configure SAST in the UI with customizations **(ULTIMATE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab Ultimate 13.4. > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/3635) in GitLab Ultimate 13.5. -You can enable and configure SAST with a basic configuration using the **SAST Configuration** -page: +To enable and configure SAST with customizations: -1. From the project's home page, go to **Security & Compliance** > **Configuration** in the - left sidebar. -1. If the project does not have a `.gitlab-ci.yml` file, click **Enable** in the Static Application Security Testing (SAST) row, otherwise click **Configure**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. If the project does not have a `.gitlab-ci.yml` file, select **Enable** in the Static Application + Security Testing (SAST) row, otherwise select **Configure**. 1. Enter the custom SAST values. - Custom values are stored in the `.gitlab-ci.yml` file. For CI/CD variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. + Custom values are stored in the `.gitlab-ci.yml` file. For CI/CD variables not in the SAST + Configuration page, their values are left unchanged. Default values are inherited from the GitLab + SAST template. -1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](analyzers.md) and enter custom analyzer values. -1. Click **Create Merge Request**. +1. Optionally, expand the **SAST analyzers** section, select individual + [SAST analyzers](analyzers.md) and enter custom analyzer values. +1. Select **Create Merge Request**. 1. Review and merge the merge request. +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. + ### Customizing the SAST settings The SAST settings can be changed through [CI/CD variables](#available-cicd-variables) @@ -250,12 +289,16 @@ versions are pulled, there are certain cases where it can be beneficial to pin an analyzer to a specific release. To do so, override the `SAST_ANALYZER_IMAGE_TAG` CI/CD variable in the job template directly. -In the example below, we are pinning to a specific patch version of the `spotbugs` analyzer: +In the example below, we pin to a specific patch version of the `spotbugs` analyzer and minor version of the `semgrep` analyzer: ```yaml include: - template: Security/SAST.gitlab-ci.yml +semgrep-sast: + variables: + SAST_ANALYZER_IMAGE_TAG: "2.12" + spotbugs-sast: variables: SAST_ANALYZER_IMAGE_TAG: "2.28.1" @@ -361,9 +404,6 @@ To create a custom ruleset: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292686) in GitLab 14.2. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the `vulnerability_flags` flag](../../../administration/feature_flags.md). On GitLab.com, this feature is available. - Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. ### Using CI/CD variables to pass credentials for private repositories @@ -536,9 +576,11 @@ all [custom variables](../../../ci/variables/index.md#custom-cicd-variables) are to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. -WARNING: -Variables having names starting with these prefixes are **not** propagated to the SAST Docker container and/or -analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. +NOTE: +In [GitLab 13.3 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/220540), +variables whose names started with the following prefixes are **not** propagated to either the +analyzer containers or SAST Docker container: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, +`OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. ### Experimental features @@ -807,3 +849,55 @@ This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, ### Semgrep slowness, unexpected results, or other errors If Semgrep is slow, reports too many false positives or false negatives, crashes, fails, or is otherwise broken, see the Semgrep docs for [troubleshooting GitLab SAST](https://semgrep.dev/docs/troubleshooting/gitlab-sast/). + +### SAST job fails with message `strconv.ParseUint: parsing "0.0": invalid syntax` + +Invoking Docker-in-Docker is the likely cause of this error. Docker-in-Docker is: + +- Disabled by default in GitLab 13.0 and later. +- Unsupported from GitLab 13.4 and later. + +Several workarounds are available. From GitLab version 13.0 and later, you must not use +Docker-in-Docker. + +#### Workaround 1: Pin analyzer versions (GitLab 12.1 and earlier) + +Set the following variables for the SAST job. This pins the analyzer versions to the last known +working version, allowing SAST with Docker-in-Docker to complete as it did previously: + +```yaml +sast: + variables: + SAST_DEFAULT_ANALYZERS: "" + SAST_ANALYZER_IMAGES: "registry.gitlab.com/gitlab-org/security-products/analyzers/bandit:2.9.6, registry.gitlab.com/gitlab-org/security-products/analyzers/brakeman:2.11.0, registry.gitlab.com/gitlab-org/security-products/analyzers/eslint:2.10.0, registry.gitlab.com/gitlab-org/security-products/analyzers/flawfinder:2.11.1, registry.gitlab.com/gitlab-org/security-products/analyzers/gosec:2.14.0, registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2.11.0, registry.gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit:2.9.1, registry.gitlab.com/gitlab-org/security-products/analyzers/pmd-apex:2.9.0, registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:3.12.0, registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2.13.0, registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2.8.0, registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2.13.6, registry.gitlab.com/gitlab-org/security-products/analyzers/tslint:2.4.0" +``` + +Remove any analyzers you don't need from the `SAST_ANALYZER_IMAGES` list. Keep +`SAST_DEFAULT_ANALYZERS` set to an empty string `""`. + +#### Workaround 2: Disable Docker-in-Docker for SAST and Dependency Scanning (GitLab 12.3 and later) + +Disable Docker-in-Docker for SAST. Individual `<analyzer-name>-sast` jobs are created for each +analyzer that runs in your CI/CD pipeline. + +```yaml +include: + - template: SAST.gitlab-ci.yml + +variables: + SAST_DISABLE_DIND: "true" +``` + +#### Workaround 3: Upgrade to GitLab 13.x and use the defaults + +From GitLab 13.0, SAST defaults to not using Docker-in-Docker. In GitLab 13.4 and later, SAST using +Docker-in-Docker is [no longer supported](https://gitlab.com/gitlab-org/gitlab/-/issues/220540). +If you have this problem on GitLab 13.x and later, you have customized your SAST job to +use Docker-in-Docker. To resolve this, comment out any customizations you've made to +your SAST CI job definition and [follow the documentation](index.md#configuration) +to reconfigure, using the new and improved job definition default values. + +```yaml +include: + - template: Security/SAST.gitlab-ci.yml +``` diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index cd1014d36a6..5933496ea00 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -138,7 +138,7 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. -### Enable Secret Detection via an automatic merge request **(ULTIMATE SELF)** +### Enable Secret Detection via an automatic merge request **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11, behind a feature flag, enabled by default. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/329886) in GitLab 14.1. @@ -151,7 +151,12 @@ from the Security Configuration page. 1. In the **Secret Detection** row, select **Configure via Merge Request**. This automatically creates a merge request with the changes necessary to enable Secret Detection -that you can review and merge to complete the configuration. +that you can review and merge to complete the configuration. + +NOTE: +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file it may not be parsed +successfully, and an error may occur. ### Customizing settings @@ -167,12 +172,12 @@ WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead. -#### GIT_DEPTH +#### `GIT_DEPTH` variable The [`GIT_DEPTH` CI/CD variable](../../../ci/runners/configure_runners.md#shallow-cloning) affects Secret Detection. The Secret Detection analyzer relies on generating patches between commits to scan content for secrets. If you override the default, ensure the value is greater than 1. If the number of commits -in an MR is greater than the GIT_DEPTH value, Secret Detection will [fail to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). +in an MR is greater than the `GIT_DEPTH` value, Secret Detection will [fail to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). #### Custom settings example @@ -285,20 +290,20 @@ sequenceDiagram Cloud Vendor-->>+RevocationAPI: ACCEPTED ``` -## Full History Secret Scan +## Full History Secret Detection GitLab 12.11 introduced support for scanning the full history of a repository. This new functionality is particularly useful when you are enabling Secret Detection in a repository for the first time and you -want to perform a full secret scan. Running a secret scan on the full history can take a long time, +want to perform a full secret detection scan. Running a secret detection scan on the full history can take a long time, especially for larger repositories with lengthy Git histories. We recommend not setting this CI/CD variable as part of your normal job definition. A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-cicd-variables)) can be set to change the behavior of the GitLab Secret Detection scan to run on the entire Git history of a repository. -We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a full history secret scan. +We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a full history secret detection scan. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=wDtc_K00Y0A">Walkthrough of historical secret scan</a>. + See the video: <a href="https://www.youtube.com/watch?v=wDtc_K00Y0A">Walkthrough of historical secret detection scan</a>. </div> <figure class="video-container"> <iframe src="https://www.youtube.com/embed/wDtc_K00Y0A" frameborder="0" allowfullscreen="true"> </iframe> diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 8b811c62ec3..f5b0194c320 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -45,6 +45,8 @@ From the Vulnerability Report you can: You can filter the vulnerabilities table by: +<!-- vale gitlab.SubstitutionWarning = NO --> + | Filter | Available options | |:---------|:------------------| | Status | Detected, Confirmed, Dismissed, Resolved. | @@ -53,6 +55,8 @@ You can filter the vulnerabilities table by: | Project | For more details, see [Project filter](#project-filter). | | Activity | For more details, see [Activity filter](#activity-filter). | +<!-- vale gitlab.SubstitutionWarning = YES --> + ### Filter the list of vulnerabilities To filter the list of vulnerabilities: |
