diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-03-16 21:18:33 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-03-16 21:18:33 +0300 |
| commit | f64a639bcfa1fc2bc89ca7db268f594306edfd7c (patch) | |
| tree | a2c3c2ebcc3b45e596949db485d6ed18ffaacfa1 /doc/user/application_security | |
| parent | bfbc3e0d6583ea1a91f627528bedc3d65ba4b10f (diff) | |
Add latest changes from gitlab-org/gitlab@13-10-stable-eev13.10.0-rc40
Diffstat (limited to 'doc/user/application_security')
30 files changed, 708 insertions, 373 deletions
diff --git a/doc/user/application_security/api_fuzzing/img/api_fuzzing_configuration_snippet_v13.10.png b/doc/user/application_security/api_fuzzing/img/api_fuzzing_configuration_snippet_v13.10.png Binary files differnew file mode 100644 index 00000000000..80c550a3ae7 --- /dev/null +++ b/doc/user/application_security/api_fuzzing/img/api_fuzzing_configuration_snippet_v13.10.png diff --git a/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_collection_edit_variable.png b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_collection_edit_variable.png Binary files differnew file mode 100644 index 00000000000..3a2799ecdc1 --- /dev/null +++ b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_collection_edit_variable.png diff --git a/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_environment_edit_variable.png b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_environment_edit_variable.png Binary files differnew file mode 100644 index 00000000000..656ba7652cd --- /dev/null +++ b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_environment_edit_variable.png diff --git a/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_request_edit.png b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_request_edit.png Binary files differnew file mode 100644 index 00000000000..3750af8f455 --- /dev/null +++ b/doc/user/application_security/api_fuzzing/img/api_fuzzing_postman_request_edit.png diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 49311ccc7cd..036da0068b5 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -25,7 +25,7 @@ you can run fuzz tests as part your CI/CD workflow. - GraphQL - Form bodies, JSON, or XML - One of the following assets to provide APIs to test: - - OpenAPI v2 API definition + - OpenAPI v2 or v3 API definition - HTTP Archive (HAR) of API requests to test - Postman Collection v2.0 or v2.1 @@ -54,7 +54,7 @@ changes, other pipelines, or other scanners) during a scan could cause inaccurat There are three ways to perform scans. See the configuration section for the one you wish to use: -- [OpenAPI v2 specification](#openapi-specification) +- [OpenAPI v2 or v3 specification](#openapi-specification) - [HTTP Archive (HAR)](#http-archive-har) - [Postman Collection v2.0 or v2.1](#postman-collection) @@ -64,13 +64,80 @@ Examples of both configurations can be found here: - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) - [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) +WARNING: +GitLab 14.0 will require that you place API fuzzing configuration files (for example, +`gitlab-api-fuzzing-config.yml`) in your repository's `.gitlab` directory instead of your +repository's root. You can continue using your existing configuration files as they are, but +starting in GitLab 14.0, GitLab will not check your repository's root for configuration files. + +### Configuration form + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. +> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-api-fuzzing-configuration-form). **(ULTIMATE)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +The API fuzzing configuration form helps you create or modify your project's API fuzzing +configuration. The form lets you choose values for the most common API fuzzing options and builds +a YAML snippet that you can paste in your GitLab CI/CD configuration. + +To generate an API Fuzzing configuration snippet: + +1. From your project's home page, go to **Security & Compliance > Configuration** in the left + sidebar. +1. Select **Configure** in the **API Fuzzing** row. +1. Complete the form as needed. Read below for more information on available configuration options. +1. Select **Generate code snippet**. + +A modal opens with the YAML snippet corresponding to the options you've selected in the form. + + + +Select **Copy code and open `.gitlab-ci.yml` file** to copy the snippet to your clipboard and be redirected +to your project's `.gitlab-ci.yml` file where you can paste the YAML configuration. + +Select **Copy code only** to copy the snippet to your clipboard and close the modal. + +#### Enable or disable API Fuzzing configuration form **(ULTIMATE)** + +The API Fuzzing configuration form is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:api_fuzzing_configuration_ui) +``` + +To disable it: + +```ruby +Feature.disable(:api_fuzzing_configuration_ui) +``` + ### OpenAPI Specification +> Support for OpenAPI Specification v3 was +> [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228652) in GitLab 13.9. + The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. This section shows you how to configure API fuzzing by using an OpenAPI specification to provide information about the target API to test. OpenAPI specifications are provided as a file system resource or URL. +API fuzzing uses an OpenAPI document to generate the request body. When a request body is required, +the body generation is limited to these body types: + +- `application/x-www-form-urlencoded` +- `multipart/form-data` +- `application/json` + Follow these steps to configure API fuzzing in GitLab with an OpenAPI specification: 1. To use API fuzzing, you must [include](../../../ci/yaml/README.md#includetemplate) @@ -100,7 +167,7 @@ Follow these steps to configure API fuzzing in GitLab with an OpenAPI specificat FUZZAPI_PROFILE: Quick-10 ``` -1. Provide the location of the OpenAPI v2 specification. You can provide the specification as a file +1. Provide the location of the OpenAPI specification. You can provide the specification as a file or URL. Specify the location by adding the `FUZZAPI_OPENAPI` variable: ```yaml @@ -193,7 +260,8 @@ target API to test: FUZZAPI_PROFILE: Quick-10 ``` -1. Add the `FUZZAPI_HAR` variable and set it to the HAR file's location: +1. Provide the location of the HAR specification. You can provide the specification as a file + or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `FUZZAPI_HAR` variable: ```yaml include: @@ -284,7 +352,8 @@ information about the target API to test: FUZZAPI_PROFILE: Quick-10 ``` -1. Add the `FUZZAPI_POSTMAN_COLLECTION` variable and set it to the Postman Collection's location: +1. Provide the location of the Postman Collection specification. You can provide the specification as a file + or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `FUZZAPI_POSTMAN_COLLECTION` variable: ```yaml include: @@ -327,6 +396,60 @@ WARNING: the API can, it may also trigger bugs in the API. This includes actions like modifying and deleting data. Only run fuzzing against a test server. +#### Postman variables + +Postman allows the developer to define placeholders that can be used in different parts of the +requests. These placeholders are called variables, as explained in [Using variables](https://learning.postman.com/docs/sending-requests/variables/). +You can use variables to store and reuse values in your requests and scripts. For example, you can +edit the collection to add variables to the document: + + + +You can then use the variables in sections such as URL, headers, and others: + + + +Variables can be defined at different [scopes](https://learning.postman.com/docs/sending-requests/variables/#variable-scopes) +(for example, Global, Collection, Environment, Local, and Data). In this example, they're defined at +the Environment scope: + + + +When you export a Postman collection, only Postman collection variables are exported into the +Postman file. For example, Postman does not export environment-scoped variables into the Postman +file. + +By default, the API fuzzer uses the Postman file to resolve Postman variable values. If a JSON file +is set in a GitLab CI environment variable `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`, then the JSON +file takes precedence to get Postman variable values. + +Although Postman can export environment variables into a JSON file, the format is not compatible +with the JSON expected by `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`. + +Here is an example of using `FUZZAPI_POSTMAN_COLLECTION_VARIABLES`: + +```yaml +include: + - template: API-Fuzzing.gitlab-ci.yml + +variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_POSTMAN_COLLECTION: postman-collection_serviceA.json + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_POSTMAN_COLLECTION_VARIABLES: variable-collection-dictionary.json +``` + +The file `variable-collection-dictionary.json` is a JSON document. This JSON is an object with +key-value pairs for properties. The keys are the variables' names, and the values are the variables' +values. For example: + + ```json + { + "base_url": "http://127.0.0.1/", + "token": "Token 84816165151" + } + ``` + ### Authentication Authentication is handled by providing the authentication token as a header or cookie. You can @@ -502,6 +625,7 @@ repository's root as `.gitlab-api-fuzzing.yml`. |[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | +|[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract postman variable values. | |[`FUZZAPI_OVERRIDES_FILE`](#overrides) | Path to a JSON file containing overrides. | |[`FUZZAPI_OVERRIDES_ENV`](#overrides) | JSON string containing headers to override. | |[`FUZZAPI_OVERRIDES_CMD`](#overrides) | Overrides command. | @@ -523,11 +647,19 @@ repository's root as `.gitlab-api-fuzzing.yml`. ### Overrides -API Fuzzing provides a method to add or override headers and cookies for all outbound HTTP requests. +API Fuzzing provides a method to add or override specific items in your request, for example: + +- Headers +- Cookies +- Query string +- Form data +- JSON nodes +- XML nodes + You can use this to inject semantic version headers, authentication, and so on. The [authentication section](#authentication) includes examples of using overrides for that purpose. -Overrides use a JSON document to define the headers and cookies: +Overrides use a JSON document, where each type of override is represented by a JSON object: ```json { @@ -538,6 +670,22 @@ Overrides use a JSON document to define the headers and cookies: "cookies": { "cookie1": "value", "cookie2": "value" + }, + "query": { + "query-string1": "value", + "query-string2": "value" + }, + "body-form": { + "form-param1": "value", + "form-param1": "value", + }, + "body-json": { + "json-path1": "value", + "json-path2": "value", + }, + "body-xml" : { + "xpath1": "value", + "xpath2": "value", } } ``` @@ -565,7 +713,94 @@ Example of setting both a header and cookie: } ``` -You can provide this JSON document as a file or CI/CD variable. You may also provide a command +Example usage for setting a `body-form` override: + +```json +{ + "body-form": { + "username": "john.doe" + } +} +``` + +The override engine uses `body-form` when the request body has only form-data content. + +Example usage for setting a `body-json` override: + +```json +{ + "body-json": { + "$.credentials.access-token": "iddqd!42.$" + } +} +``` + +Note that each JSON property name in the object `body-json` is set to a [JSON Path](https://goessner.net/articles/JsonPath/) +expression. The JSON Path expression `$.credentials.access-token` identifies the node to be +overridden with the value `iddqd!42.$`. The override engine uses `body-json` when the request body +has only [JSON](https://www.json.org/json-en.html) content. + +For example, if the body is set to the following JSON: + +```json +{ + "credentials" : { + "username" :"john.doe", + "access-token" : "non-valid-password" + } +} +``` + +It is changed to: + +```json +{ + "credentials" : { + "username" :"john.doe", + "access-token" : "iddqd!42.$" + } +} +``` + +Here's an example for setting a `body-xml` override. The first entry overrides an XML attribute and +the second entry overrides an XML element: + +```json +{ + "body-xml" : { + "/credentials/@isEnabled": "true", + "/credentials/access-token/text()" : "iddqd!42.$" + } +} +``` + +Note that each JSON property name in the object `body-xml` is set to an +[XPath v2](https://www.w3.org/TR/xpath20/) +expression. The XPath expression `/credentials/@isEnabled` identifies the attribute node to override +with the value `true`. The XPath expression `/credentials/access-token/text()` identifies the +element node to override with the value `iddqd!42.$`. The override engine uses `body-xml` when the +request body has only [XML](https://www.w3.org/XML/) +content. + +For example, if the body is set to the following XML: + +```xml +<credentials isEnabled="false"> + <username>john.doe</username> + <access-token>non-valid-password</access-token> +</credentials> +``` + +It is changed to: + +```xml +<credentials isEnabled="true"> + <username>john.doe</username> + <access-token>iddqd!42.$</access-token> +</credentials> +``` + +You can provide this JSON document as a file or environment variable. You may also provide a command to generate the JSON document. The command can run at intervals to support values that expire. #### Using a file @@ -762,7 +997,7 @@ pipelines. For more information, see the [Security Dashboard documentation](../s Fuzzing faults show up as vulnerabilities with a severity of Unknown. Once a fault is found, you can interact with it. Read more on how to -[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +[address the vulnerabilities](../index.md#addressing-vulnerabilities). ## Handling False Positives diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index fe21fdc1f15..4d5e3529762 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -5,14 +5,17 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Security Configuration **(ULTIMATE)** +# Security Configuration **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. -> - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. -> - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. **(ULTIMATE)** +> - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. **(ULTIMATE)** +> - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. **(ULTIMATE)** +> - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.9. + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. -The Security Configuration page displays the configuration state of each security control in the -current project. +The Security Configuration page displays what security scans are available, links to documentation and also simple enablement tools for the current project. To view a project's security configuration, go to the project's home page, then in the left sidebar go to **Security & Compliance > Configuration**. @@ -20,10 +23,11 @@ then in the left sidebar go to **Security & Compliance > Configuration**. For each security control the page displays: - **Security Control:** Name, description, and a documentation link. -- **Status:** The security control's status (enabled, not enabled, or available). - **Manage:** A management option or a documentation link. -## Status +## Status **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. The status of each security control is determined by the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md). @@ -35,7 +39,7 @@ all security features are configured by default. For SAST, click **View history** to see the `.gitlab-ci.yml` file's history. -## Manage +## Manage **(ULTIMATE)** You can configure the following security controls: diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 6eec1418ef0..909065d7907 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -32,7 +32,7 @@ To integrate security scanners other than Clair and Klar into GitLab, see You can enable container scanning by doing one of the following: - [Include the CI job](#configuration) in your existing `.gitlab-ci.yml` file. -- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning) +- Implicitly use [Auto Container Scanning](../../../topics/autodevops/stages.md#auto-container-scanning), provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab compares the found vulnerabilities between the source and target branches, and shows the @@ -455,7 +455,7 @@ For more information about the vulnerabilities database update, check the ## Interacting with the vulnerabilities -After a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). +After a vulnerability is found, you can [address it](../index.md#addressing-vulnerabilities). ## Solutions for vulnerabilities (auto-remediation) @@ -469,7 +469,7 @@ file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.m your `.gitlab-ci.yml` file by following the instructions described in this document's [overriding the container scanning template](#overriding-the-container-scanning-template) section. -Read more about the [solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities). +Read more about the [solutions for vulnerabilities](../index.md#apply-an-automatic-remediation-for-a-vulnerability). ## Troubleshooting diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 9e42b3e403a..94a7d5268b7 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -237,7 +237,7 @@ The `covfuzz-ci.yml` is the same as that in the [original synchronous example](h ## Interacting with the vulnerabilities -After a vulnerability is found, you can [interact with it](../index.md#interacting-with-the-vulnerabilities). +After a vulnerability is found, you can [address it](../index.md#addressing-vulnerabilities). The merge request widget lists the vulnerability and contains a button for downloading the fuzzing artifacts. By clicking one of the detected vulnerabilities, you can see its details. diff --git a/doc/user/application_security/dast/img/dast_single_v13_0.png b/doc/user/application_security/dast/img/dast_single_v13_0.png Binary files differdeleted file mode 100644 index 1d528fa0ace..00000000000 --- a/doc/user/application_security/dast/img/dast_single_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 3950c856b40..209dd7ad251 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -9,98 +9,82 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -Running [static checks](../sast/index.md) on your code is the first step to detect -vulnerabilities that can put the security of your code at risk. Yet, once -deployed, your application is exposed to a new category of possible attacks, -such as cross-site scripting or broken authentication flaws. This is where -Dynamic Application Security Testing (DAST) comes into place. +Your application may be exposed to a new category of attacks once deployed into a new environment. For +example, application server misconfigurations or incorrect assumptions about security controls may +not be visible from source code alone. Dynamic Application Security Testing (DAST) checks an +application for these types of vulnerabilities in a deployed environment. GitLab DAST uses the +popular open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) to analyze your running +web application. NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your organization. -## Overview - -If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web applications -for known vulnerabilities using Dynamic Application Security Testing (DAST). -You can take advantage of DAST by either [including the CI job](#configuration) in -your existing `.gitlab-ci.yml` file or by implicitly using -[Auto DAST](../../../topics/autodevops/stages.md#auto-dast), -provided by [Auto DevOps](../../../topics/autodevops/index.md). - -GitLab checks the DAST report, compares the found vulnerabilities between the source and target -branches, and shows the information on the merge request. +In GitLab, DAST is commonly initiated by a merge request and runs as a job in the CI/CD pipeline. +You can also run a DAST scan on demand, outside the CI/CD pipeline. Your running web application is +analyzed for known vulnerabilities. GitLab checks the DAST report, compares the vulnerabilities +found between the source and target branches, and shows any relevant findings on the merge request. Note that this comparison logic uses only the latest pipeline executed for the target branch's base commit. Running the pipeline on any other commit has no effect on the merge request. - + -By clicking on one of the detected linked vulnerabilities, you can -see the details and the URL(s) affected. +## Enable DAST - +### Prerequisites -[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_Application_Security_Testing) -uses the popular open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) -to perform an analysis on your running web application. +- GitLab Runner with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). -By default, DAST executes [ZAP Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) -and performs passive scanning only. It doesn't actively attack your application. -However, DAST can be [configured](#full-scan) -to also perform an *active scan*: attack your application and produce a more extensive security report. -It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md). +To enable DAST, either: -Note that a pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job -fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For -example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST -results. On failure, the analyzer outputs an -[exit code](../../../development/integrations/secure.md#exit-code). +- Enable [Auto DAST](../../../topics/autodevops/stages.md#auto-dast), provided by + [Auto DevOps](../../../topics/autodevops/index.md). +- [Include the DAST template](#dast-cicd-template) in your existing `.gitlab-ci.yml` file. -## Use cases +### DAST CI/CD template -It helps you automatically find security vulnerabilities in your running web -applications while you're developing and testing your applications. +The DAST job is defined in a CI/CD template file you reference in your CI/CD configuration file. The +template is included with GitLab. Updates to the template are provided with GitLab upgrades. You +benefit from any improvements and additions. -## Requirements +The following templates are available: -To run a DAST job, you need GitLab Runner with the -[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). +- [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml): + Stable version of the DAST CI/CD template. +- [`DAST.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.latest.gitlab-ci.yml): + Latest version of the DAST template. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) + in GitLab 13.8). Please note that the latest version may include breaking changes. Check the + [DAST troubleshooting guide](#troubleshooting) if you experience problems. -## Configuration +Use the stable template unless you need a feature provided only in the latest template. -For GitLab 11.9 and later, to enable DAST, you must -[include](../../../ci/yaml/README.md#includetemplate) the -[`DAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml) -that's provided as a part of your GitLab installation. For GitLab versions earlier -than 11.9, you can copy and use the job as defined in that template. +See the CI/CD [documentation](../../../development/cicd/templates.md#latest-version) +on template versioning for more information. -Add the following to your `.gitlab-ci.yml` file: +#### Include the DAST template -```yaml -include: - - template: DAST.gitlab-ci.yml +The method of including the DAST template depends on the GitLab version: -variables: - DAST_WEBSITE: https://example.com -``` +- In GitLab 11.9 and later, [include](../../../ci/yaml/README.md#includetemplate) the + `DAST.gitlab-ci.yml` template. -### Latest template + Add the following to your `.gitlab-ci.yml` file: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) in GitLab 13.8 + ```yaml + include: + - template: DAST.gitlab-ci.yml -To use the latest version of the DAST template, include -`DAST.latest.gitlab-ci.yml` instead of `DAST.gitlab-ci.yml`. -See the CI/CD [documentation](../../../development/cicd/templates.md#latest-version) -on template versioning for more information. + variables: + DAST_WEBSITE: https://example.com + ``` -Please note that the latest version may include breaking changes. Check the -[DAST troubleshooting guide](#troubleshooting) if you experience problems. +- In GitLab 11.8 and earlier, copy the template's content into your `.gitlab_ci.yml` file. -### Template options +#### Template options -There are two ways to define the URL to be scanned by DAST: +Running a DAST scan requires a URL. There are two ways to define the URL to be scanned by DAST: 1. Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/README.md#variables). @@ -125,7 +109,7 @@ There are two ways to define the URL to be scanned by DAST: If both values are set, the `DAST_WEBSITE` value takes precedence. The included template creates a `dast` job in your CI/CD pipeline and scans -your project's source code for possible vulnerabilities. +your project's running application for possible vulnerabilities. The results are saved as a [DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast) @@ -143,9 +127,93 @@ image. Using the `DAST_VERSION` variable, you can choose how DAST updates: Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page. -### When DAST scans run +## Deployment options + +Depending on the complexity of the target application, there are a few options as to how to deploy and configure +the DAST template. A set of example applications with their configurations have been made available in our +[DAST demonstrations](https://gitlab.com/gitlab-org/security-products/demos/dast/) project. + +### Review Apps + +Review Apps are the most involved method of deploying your DAST target application. To assist in the process, +we created a Review App deployment using Google Kubernetes Engine (GKE). This example can be found in our +[Review Apps - GKE](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke) project along with detailed +instructions in the [README.md](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke/-/blob/master/README.md) +on how to configure Review Apps for DAST. + +### Docker Services + +If your application utilizes Docker containers you have another option for deploying and scanning with DAST. +After your Docker build job completes and your image is added to your container registry, you can utilize the image as a +[service](../../../ci/docker/using_docker_images.md#what-is-a-service). + +By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. + +```yaml +stages: + - build + - dast + +include: + - template: DAST.gitlab-ci.yml + +# Deploys the container to the GitLab container registry +deploy: + services: + - name: docker:dind + alias: dind + image: docker:19.03.5 + stage: build + script: + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker pull $CI_REGISTRY_IMAGE:latest || true + - docker build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest . + - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + - docker push $CI_REGISTRY_IMAGE:latest + +services: # use services to link your app container to the dast job + - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + alias: yourapp + +variables: + DAST_FULL_SCAN_ENABLED: "true" # do a full scan + DAST_ZAP_USE_AJAX_SPIDER: "true" # use the ajax spider +``` + +Most applications depend on multiple services such as databases or caching services. By default, services defined in the services fields cannot communicate +with each another. To allow communication between services, enable the `FF_NETWORK_PER_BUILD` [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags). + +```yaml +variables: + FF_NETWORK_PER_BUILD: "true" # enable network per build so all services can communicate on the same network + +services: # use services to link the container to the dast job + - name: mongo:latest + alias: mongo + - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + alias: yourapp +``` + +### DAST application analysis + +DAST can analyze applications in two ways: + +- Passive scan only (DAST default). DAST executes + [ZAP's Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) and doesn't + actively attack your application. +- Passive and active scan. DAST can be [configured](#full-scan) to also perform an active scan + to attack your application and produce a more extensive security report. It can be very + useful when combined with [Review Apps](../../../ci/review_apps/index.md). + +Note that a pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job +fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For +example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST +results. On failure, the analyzer outputs an +[exit code](../../../development/integrations/secure.md#exit-code). + +#### DAST job order -When using `DAST.gitlab-ci.yml` template, the `dast` job is run last as shown in +When using the `DAST.gitlab-ci.yml` template, the `dast` job is run last as shown in the example below. To ensure DAST is scanning the latest code, your CI pipeline should deploy changes to the web server in one of the jobs preceding the `dast` job. @@ -247,6 +315,9 @@ tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/20 #### Domain validation +WARNING: +In GitLab 13.8, domain validation, outside of the new on-demand scan site profile validation, was deprecated. In GitLab 14.0, domain validation in CI/CD jobs will be permanently removed. + The DAST job can be run anywhere, which means you can accidentally hit live web servers and potentially damage them. You could even take down your production environment. For that reason, you should use domain validation. @@ -472,7 +543,7 @@ URLs to scan can be specified by either of the following methods: To define the URLs to scan in a file, create a plain text file with one path per line. -```txt +```plaintext page1.html /page2.html category/shoes/page1.html @@ -676,7 +747,7 @@ successfully run. For more information, see [Offline environments](../offline_de To use DAST in an offline environment, you need: -- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). +- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisites). - Docker Container Registry with a locally available copy of the DAST [container image](https://gitlab.com/gitlab-org/security-products/dast), found in the [DAST container registry](https://gitlab.com/gitlab-org/security-products/dast/container_registry). @@ -831,7 +902,7 @@ To delete an on-demand scan: 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. 1. Select **Delete** to confirm the deletion. -## Site profile +### Site profile A site profile describes the attributes of a web site to scan on demand with DAST. A site profile is required for an on-demand DAST scan. @@ -841,7 +912,7 @@ A site profile contains the following: - **Profile name**: A name you assign to the site to be scanned. - **Target URL**: The URL that DAST runs against. -### Site profile validation +#### Site profile validation > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. @@ -858,7 +929,7 @@ follows: Both methods are equivalent in functionality. Use whichever is feasible. -### Create a site profile +#### Create a site profile To create a site profile: @@ -869,7 +940,7 @@ To create a site profile: The site profile is created. -### Edit a site profile +#### Edit a site profile To edit an existing site profile: @@ -881,7 +952,7 @@ To edit an existing site profile: The site profile is updated with the edited details. -### Delete a site profile +#### Delete a site profile To delete an existing site profile: @@ -893,7 +964,7 @@ To delete an existing site profile: The site profile is deleted. -### Validate a site profile +#### Validate a site profile Prerequisites: @@ -921,7 +992,7 @@ The site is validated and an active scan can run against it. If a validated site profile's target URL is edited, the site's validation status is revoked. -### Revoke a site profile's validation status +#### Revoke a site profile's validation status Note that all site profiles with the same URL have their validation status revoked. @@ -977,7 +1048,7 @@ app.get('/dast-website-target', function(req, res) { }) ``` -## Scanner profile +### Scanner profile > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222767) in GitLab 13.4. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/225804) in GitLab 13.5: scan mode, AJAX spider, debug messages. @@ -992,7 +1063,7 @@ A scanner profile defines the scanner settings used to run an on-demand scan: - **AJAX spider:** Run the AJAX spider, in addition to the traditional spider, to crawl the target site. - **Debug messages:** Include debug messages in the DAST console output. -### Create a scanner profile +#### Create a scanner profile To create a scanner profile: @@ -1002,7 +1073,7 @@ To create a scanner profile: 1. Complete the form. For details of each field, see [Scanner profile](#scanner-profile). 1. Click **Save profile**. -### Edit a scanner profile +#### Edit a scanner profile To edit a scanner profile: @@ -1015,7 +1086,7 @@ To edit a scanner profile: The scanner profile is updated with the edited details. -### Delete a scanner profile +#### Delete a scanner profile To delete a scanner profile: @@ -1099,7 +1170,7 @@ variables: ## Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to -[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +[address the vulnerabilities](../index.md#addressing-vulnerabilities). ## Vulnerabilities database update diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index d5f4ce9cc6a..6ed3b15d829 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -5,54 +5,56 @@ group: Composition Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Dependency List **(ULTIMATE)** +# Dependency list **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab Ultimate 12.0. -The dependency list allows you to see your project's dependencies, and key -details about them, including their known vulnerabilities. To see it, -navigate to **Security & Compliance > Dependency List** in your project's -sidebar. This information is sometimes referred to as a Software Bill of Materials or SBoM / BOM. +Use the dependency list to review your project's dependencies and key +details about those dependencies, including their known vulnerabilities. To see the dependency list, +in your project, go to **Security & Compliance > Dependency List**. +This information is sometimes referred to as a Software Bill of Materials or SBoM / BOM. -## Requirements +## Prerequisites -1. The [Dependency Scanning](../dependency_scanning/index.md) CI job must be - configured for your project. -1. Your project uses at least one of the - [languages and package managers](../dependency_scanning/index.md#supported-languages-and-package-managers) - supported by Gemnasium. +To view your project's dependencies, ensure you meet the following requirements: -## Viewing dependencies +- The [Dependency Scanning](../dependency_scanning/index.md) CI job must be + configured for your project. +- Your project uses at least one of the + [languages and package managers](../dependency_scanning/index.md#supported-languages-and-package-managers) + supported by Gemnasium. - +## View a project's dependencies -Dependencies are displayed with the following information: + + +GitLab displays dependencies with the following information: | Field | Description | -| --------- | ----------- | -| Component | The dependency's name and version | -| Packager | The packager used to install the dependency | +|-----------|-------------| +| Component | The dependency's name and version. | +| Packager | The packager used to install the dependency. | | Location | A link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. | -| License | Links to dependency's software licenses | +| License | Links to dependency's software licenses. | -Dependencies shown are initially sorted by the severity of their known vulnerabilities, if any. They +Displayed dependencies are initially sorted by the severity of their known vulnerabilities, if any. They can also be sorted by name or by the packager that installed them. ### Vulnerabilities -If a dependency has known vulnerabilities, you can view them by clicking the arrow next to the +If a dependency has known vulnerabilities, view them by clicking the arrow next to the dependency's name or the badge that indicates how many known vulnerabilities exist. For each -vulnerability, its severity and description then appears below it. +vulnerability, its severity and description appears below it. -### Dependency Paths +### Dependency paths The dependency list shows the path between a dependency and a top-level dependency it's connected to, if any. There are many possible paths connecting a transient dependency to top-level -dependencies, but the UI only shows one of the shortest paths. +dependencies, but the user interface shows only one of the shortest paths. - + -Dependency Paths are supported for the following package managers: +Dependency paths are supported for the following package managers: - [NuGet](https://www.nuget.org/) - [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) @@ -62,9 +64,9 @@ Dependency Paths are supported for the following package managers: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab Ultimate 12.3. If the [License Compliance](../../compliance/license_compliance/index.md) CI job is configured, -the [discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) are displayed on this page. +[discovered licenses](../../compliance/license_compliance/index.md#supported-languages-and-package-managers) are displayed on this page. -## Downloading the Dependency List +## Downloading the dependency list -Your project's full list of dependencies and their details can be downloaded in -`JSON` format by clicking on the download button. +You can download your project's full list of dependencies and their details in +`JSON` format by selecting the download button. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 11d27140e42..f87ea8edc7b 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -19,10 +19,13 @@ vulnerable. You can then take action to protect your application. If you're using [GitLab CI/CD](../../../ci/README.md), you can use dependency scanning to analyze your dependencies for known vulnerabilities. GitLab scans all dependencies, including transitive dependencies (also known as nested dependencies). You can take advantage of dependency scanning by -either [including the dependency scanning template](#configuration) -in your existing `.gitlab-ci.yml` file, or by implicitly using -the [auto dependency scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) -provided by [Auto DevOps](../../../topics/autodevops/index.md). +either: + +- [Including the dependency scanning template](#configuration) + in your existing `.gitlab-ci.yml` file. +- Implicitly using + the [auto dependency scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) + provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab checks the dependency scanning report, compares the found vulnerabilities between the source and target branches, and shows the information on the @@ -59,16 +62,16 @@ The following languages and dependency managers are supported: | Package Managers | Languages | Supported files | Scan tools | | ------------------- | --------- | --------------- | ------------ | -| [Bundler](https://bundler.io/) | Ruby | `Gemfile.lock`, `gems.locked` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | -| [Composer](https://getcomposer.org/) | PHP | `composer.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [Conan](https://conan.io/) | C, C++ | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [Bundler](https://bundler.io/) | Ruby | `Gemfile.lock`, `gems.locked` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | +| [Composer](https://getcomposer.org/) | PHP | `composer.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [Conan](https://conan.io/) | C, C++ | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | | [npm](https://www.npmjs.com/) (7 and earlier), [yarn](https://classic.yarnpkg.com/en/) 1.x | JavaScript | `package.json` | [Retire.js](https://retirejs.github.io/retire.js/) | -| [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [`setuptools`](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) (*1*) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile`, `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| [sbt](https://www.scala-sbt.org/) (*2*) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [`setuptools`](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) (*1*) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile`, `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | +| [sbt](https://www.scala-sbt.org/) (*2*) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | 1. [Pipenv](https://pipenv.pypa.io/en/latest/) projects are scanned when a `Pipfile` is present. 1. Support for [sbt](https://www.scala-sbt.org/) 1.3 and above was added in GitLab 13.9. @@ -77,7 +80,7 @@ Plans are underway for supporting the following languages, dependency managers, | Package Managers | Languages | Supported files | Scan tools | Issue | | ------------------- | --------- | --------------- | ---------- | ----- | -| [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | +| [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | ## Contribute your scanner @@ -223,13 +226,13 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m ## Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to -[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +[address the vulnerabilities](../index.md#addressing-vulnerabilities). ## Solutions for vulnerabilities (auto-remediation) Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. Read more about the -[solutions for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities). +[solutions for vulnerabilities](../index.md#apply-an-automatic-remediation-for-a-vulnerability). ## Security Dashboard @@ -507,7 +510,7 @@ ensure that it can reach your private repository. Here is an example configurati ### Referencing local dependencies using a path in JavaScript projects The [Retire.js](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) analyzer -doesn't support dependency references made with [local paths](https://docs.npmjs.com/cli/v6/configuring-npm/package-json#local-paths) +doesn't support dependency references made with [local paths](https://docs.npmjs.com/cli/v6/configuring-npm/package-json/#local-paths) in the `package.json` of JavaScript projects. The dependency scan outputs the following error for such references: diff --git a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png Binary files differindex a914c2996f7..54ccfa24374 100644 --- a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png +++ b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png diff --git a/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png Binary files differdeleted file mode 100644 index a3034a7db04..00000000000 --- a/doc/user/application_security/img/vulnerability_page_merge_request_button_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png b/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png Binary files differdeleted file mode 100644 index 10d9effb811..00000000000 --- a/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif b/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif Binary files differdeleted file mode 100644 index 22acba5fe1e..00000000000 --- a/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 4a23cd874be..b0457ec0690 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -5,17 +5,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# GitLab Secure **(ULTIMATE)** +# Application security **(ULTIMATE)** GitLab can check your application for security vulnerabilities that may lead to unauthorized access, data leaks, denial of services, and more. GitLab reports vulnerabilities in the merge request so you -can fix them before merging. The [Security Dashboard](security_dashboard/index.md) provides a -high-level view of vulnerabilities detected in your projects, pipeline, and groups. The [Threat Monitoring](threat_monitoring/index.md) -page provides runtime security metrics for application environments. With the information provided, -you can immediately begin risk analysis and remediation. +can fix them before you merge. + +- The [Security Dashboard](security_dashboard/index.md) provides a + high-level view of vulnerabilities detected in your projects, pipeline, and groups. +- The [Threat Monitoring](threat_monitoring/index.md) page provides runtime security metrics + for application environments. With the information provided, + you can immediately begin risk analysis and remediation. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview of application security with GitLab, see +For an overview of GitLab application security, see [Security Deep Dive](https://www.youtube.com/watch?v=k4vEJnGYy84). ## Quick start @@ -123,7 +126,7 @@ latest versions of the scanning tools without having to do anything. There are s with this approach, however, and there is a [plan to resolve them](https://gitlab.com/gitlab-org/gitlab/-/issues/9725). -## Viewing security scan information in merge requests **(FREE)** +## View security scan information in merge requests **(FREE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Free 13.5. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. @@ -136,25 +139,7 @@ reports are available to download. To download a report, click on the  -## Interacting with the vulnerabilities - -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. - -Each security vulnerability in the merge request report or the -[Vulnerability Report](vulnerability_report/index.md) is actionable. Click an entry to view detailed -information with several options: - -- [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability styles it in - strikethrough. -- [Create issue](vulnerabilities/index.md#create-a-gitlab-issue-for-a-vulnerability): Create a new issue with the title and - description pre-populated with information from the vulnerability report. By default, such issues - are [confidential](../project/issues/confidential_issues.md). -- [Automatic Remediation](#automatic-remediation-for-vulnerabilities): For some vulnerabilities, - a solution is provided for how to fix the vulnerability. - - - -### View details of a DAST vulnerability +## View details of a DAST vulnerability > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. @@ -165,11 +150,10 @@ investigate and rectify the underlying cause. To view details of DAST vulnerabilities: 1. To see all vulnerabilities detected: - - In a project, go to the project's **{shield}** **Security & Compliance** page. - Only in a merge request, go the merge request's **Security** tab. -1. Click on the vulnerability's description. The following details are provided: +1. Select the vulnerability's description. The following details are provided: | Field | Description | |:-----------------|:------------------------------------------------------------------ | @@ -187,14 +171,14 @@ To view details of DAST vulnerabilities: | Links | Links to further details of the detected vulnerability. | | Solution | Details of a recommended solution to the vulnerability (optional). | -#### Hide sensitive information in headers +### Hide sensitive information in headers HTTP request and response headers may contain sensitive information, including cookies and authorization credentials. By default, content of specific headers are masked in DAST vulnerability reports. You can specify the list of all headers to be masked. For details, see [Hide sensitive information](dast/index.md#hide-sensitive-information). -### View details of an API Fuzzing vulnerability +## View details of an API Fuzzing vulnerability > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. @@ -231,65 +215,79 @@ Follow these steps to view details of a fuzzing fault: | Severity | Severity of the finding is always Unknown. | | Scanner Type | Scanner used to perform testing. | -### Dismissing a vulnerability +## Addressing vulnerabilities -To dismiss a vulnerability, you must set its status to Dismissed. This dismisses the vulnerability -for the entire project. Follow these steps to do so: +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. -1. Select the vulnerability in the Security Dashboard. -1. Select **Dismissed** from the **Status** selector menu at the top-right. +For each security vulnerability in a merge request or [Vulnerability Report](vulnerability_report/index.md), +you can: + +- [Dismiss the vulnerability](#dismiss-a-vulnerability). +- Create a [confidential](../project/issues/confidential_issues.md) + [issue](vulnerabilities/index.md#create-a-gitlab-issue-for-a-vulnerability). +- Apply an [automatically remediation](#apply-an-automatic-remediation-for-a-vulnerability). -You can undo this action by selecting a different status from the same menu. +### Dismiss a vulnerability -#### Adding a dismissal reason +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0, a dismissal reason. -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +You can dismiss a vulnerability for the entire project. -When dismissing a vulnerability, it's often helpful to provide a reason for doing so. Upon setting a -vulnerability's status to Dismissed, a text box appears for you to add a comment with your -dismissal. Once added, you can edit or delete it. This allows you to add and update context for a -vulnerability as you learn more over time. +1. Select the vulnerability in the Security Dashboard. +1. In the top-right, from the **Status** selector menu, select **Dismissed**. +1. Optional. Add a reason for the dismissal and select **Save comment**. - +To undo this action, select a different status from the same menu. -#### Dismissing multiple vulnerabilities +#### Dismiss multiple vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -You can dismiss multiple vulnerabilities at once, providing an optional reason. -Selecting the checkboxes on the side of each vulnerability in the list selects that individual vulnerability. -Alternatively, you can select all the vulnerabilities in the list by selecting the checkbox in the table header. -Deselecting the checkbox in the header deselects all the vulnerabilities in the list. -After you have selected some vulnerabilities, a menu appears at the top of the table that allows you to select a dismissal reason. -Pressing the "Dismiss Selected" button dismisses all the selected vulnerabilities at once, with the reason you chose. +You can dismiss multiple vulnerabilities at once. - +1. In the list of vulnerabilities, select the checkbox for each vulnerability you want to dismiss. + To select all, select the checkbox in the table header. +1. Above the table, select a dismissal reason. +1. Select **Dismiss Selected**. ### Create an issue for a vulnerability -You can create a GitLab issue, or a Jira issue (if it's enabled) for a vulnerability. For more -details, see [Vulnerability Pages](vulnerabilities/index.md). +You can create a GitLab or Jira issue for a vulnerability. For details, see [Vulnerability Pages](vulnerabilities/index.md). + +#### Link to an existing issue + +If you already have an open issue, you can link to it from the vulnerability. + +- The vulnerability page shows related issues, but the issue page doesn't show the vulnerability it's related to. +- An issue can only be related to one vulnerability at a time. +- Issues can be linked across groups and projects. + +To link to an existing issue: + +1. Open the vulnerability. +1. In the **Related Issues** section, select the plus (**{plus}**) icon. +1. In the text box that appears, type an issue number or paste an issue link. + - Type `#` followed by a number to show an autocomplete menu. + - You can enter multiple issues at once. Press the space bar after each issue number or link to converts them to tags. +1. Select **Add**. -### Automatic remediation for vulnerabilities +To remove an issue, to the right of the issue number, select **{close}**. + + + +### Apply an automatic remediation for a vulnerability > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. -Although the feature name is Automatic Remediation, this feature is also commonly called -Auto-Remediation, Auto Remediation, or Suggested Solutions. The following scanners are supported: +The following scanners are supported: -- [Dependency Scanning](dependency_scanning/index.md): +- [Dependency Scanning](dependency_scanning/index.md). Automatic Patch creation is only available for Node.js projects managed with `yarn`. -- [Container Scanning](container_scanning/index.md) - -When an automatic solution is available, the button in the header shows **Resolve with merge request**: +- [Container Scanning](container_scanning/index.md). - - -Selecting the button creates a merge request with the solution. - -#### Manually applying the suggested patch +#### Manually apply the suggested patch To manually apply the patch that GitLab generated for a vulnerability: @@ -301,49 +299,22 @@ To manually apply the patch that GitLab generated for a vulnerability: 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. -#### Creating a merge request from a vulnerability +#### Create a merge request with the suggested patch > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. -In certain cases, GitLab allows you to create a merge request that automatically remediates the +In some cases, you can create a merge request that automatically remediates the vulnerability. Any vulnerability that has a -[solution](#automatic-remediation-for-vulnerabilities) can have a merge +[solution](#apply-an-automatic-remediation-for-a-vulnerability) can have a merge request created to automatically solve the issue. -If this action is available, the vulnerability page or modal contains a **Create merge request** button. -Click this button to create a merge request to apply the solution onto the source branch. - - - -### Managing related issues for a vulnerability - -Issues can be linked to a vulnerability using the related issues block on the vulnerability page. -The relationship is uni-directional. The vulnerability page shows related issues, but the issue page -doesn't show the vulnerability it's related to. An issue can only be related to one vulnerability at -a time. Issues can be linked across groups and projects. - -#### Adding a related issue - -You can link an issue by clicking the **{plus}** button in the **Related Issues** block. - - - -A text box appears that lets you type an issue number or paste an issue link. You can enter multiple -issues at once. Pressing the space bar after each issue number or link converts them to tags that -you can remove by clicking the **{close}** icon to the tag's right. Typing `#` followed by a number -shows an autocomplete menu. Click an issue in the menu to add it as a tag. When you're finished -entering issues, click the **Add** button to link the issues to the vulnerability. Alternatively, -click **Cancel** to exit without linking any issues. - - - -### Removing a related issue +If this action is available: -Click the **{close}** icon to right of an issue to remove it as a related issue. Note that this only -removes it as a related issue of the vulnerability; it doesn't modify or remove the issue itself. -You can link it to the vulnerability again if desired. +1. Select the **Resolve with merge request** dropdown, then select **Resolve with merge request**. + +  - +A merge request is created. It that applies the solution to the source branch. ## Security approvals in merge requests diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 9d16fb75410..7c013a2a9de 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -59,14 +59,14 @@ mirroring the packages inside your own offline network. ### Interacting with the vulnerabilities Once a vulnerability is found, you can interact with it. Read more on how to -[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +[address the vulnerabilities](../index.md#addressing-vulnerabilities). Please note that in some cases the reported vulnerabilities provide metadata that can contain external links exposed in the UI. These links might not be accessible within an offline environment. ### Automatic remediation for vulnerabilities -The [automatic remediation for vulnerabilities](../index.md#automatic-remediation-for-vulnerabilities) feature is available for offline Dependency Scanning and Container Scanning, but may not work +The [automatic remediation for vulnerabilities](../index.md#apply-an-automatic-remediation-for-a-vulnerability) feature is available for offline Dependency Scanning and Container Scanning, but may not work depending on your instance's configuration. We can only suggest solutions, which are generally more current versions that have been patched, when we are able to access up-to-date registry services hosting the latest versions of that dependency or image. diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 880edebfeda..b71cefbc7fe 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Static Application Security Testing (SAST) +# Static Application Security Testing (SAST) **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. > - All open source (OSS) analyzers were moved to GitLab Free in GitLab 13.3. @@ -83,8 +83,9 @@ You can also [view our language roadmap](https://about.gitlab.com/direction/secu | Objective-C (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | | Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | -| Python | [semgrep](https://semgrep.dev) | 13.9 | +| Python | [Semgrep](https://semgrep.dev) | 13.9 | | React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | +| Ruby | [brakeman](https://brakemanscanner.org) | 13.9 | | Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | | Scala ([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.0 (SBT) & 11.9 (Ant, Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | @@ -130,16 +131,16 @@ All open source (OSS) analyzers have been moved to the GitLab Free tier as of Gi Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Ultimate | -|:-----------------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | -| [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](#security-dashboard) | **{dotted-circle}** | **{check-circle}** | -| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | -| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | +| Capability | In Free | In Ultimate | +|:-------------------------------------------------------------------------------------------------------------|:--------------------|:-------------------| +| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | +| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | +| [Address vulnerabilities](../../application_security/index.md#addressing-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | +| [Customize SAST Rulesets](#customize-rulesets) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -149,7 +150,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) To configure SAST for a project you can: -- Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast) provided by +- Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast), provided by [Auto DevOps](../../../topics/autodevops/index.md). - [Configure SAST manually](#configure-sast-manually). - [Configure SAST using the UI](#configure-sast-in-the-ui) (introduced in GitLab 13.3). @@ -374,8 +375,6 @@ If all dependencies are present, the `COMPILE=false` CI/CD variable can be provi analyzer and compilation is skipped: ```yaml -image: maven:3.6-jdk-8-alpine - stages: - build - test @@ -384,6 +383,7 @@ include: - template: Security/SAST.gitlab-ci.yml build: + image: maven:3.6-jdk-8-slim stage: build script: - mvn package -Dmaven.repo.local=./.m2/repository @@ -610,31 +610,6 @@ Here's an example SAST report: } ``` -## Secret detection - -Learn more about [Secret Detection](../secret_detection). - -## Security Dashboard **(ULTIMATE)** - -The Security Dashboard is a good place to get an overview of all the security -vulnerabilities in your groups, projects and pipelines. Read more about the -[Security Dashboard](../security_dashboard/index.md). - -## Interacting with the vulnerabilities **(ULTIMATE)** - -Once a vulnerability is found, you can interact with it. Read more on how to -[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). - -## Vulnerabilities database - -Vulnerabilities contained in the vulnerability database can be searched -and viewed at the [GitLab vulnerability advisory database](https://advisories.gitlab.com). - -### Vulnerabilities database update - -For more information about the vulnerabilities database update, check the -[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). - ## Running SAST in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 98177e804f3..d2a576e9e03 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -5,7 +5,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Secret Detection +# Secret Detection **(FREE)** > - [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in 13.3. @@ -102,8 +102,7 @@ as shown in the following table: Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml) during the `secret-detection` job. It runs regardless of your app's programming language. -The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) and -[TruffleHog](https://github.com/dxa4481/truffleHog) checks. +The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) checks. Note that the Secret Detection analyzer ignores Password-in-URL vulnerabilities if the password begins with a dollar sign (`$`), as this likely indicates the password is an environment variable. @@ -112,7 +111,7 @@ For example, `https://username:$password@example.com/path/to/repo` isn't detecte NOTE: You don't have to configure Secret Detection manually as shown in this section if you're using -[Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection) +[Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection), provided by [Auto DevOps](../../../topics/autodevops/index.md). To enable Secret Detection for GitLab 13.1 and later, you must include the @@ -200,7 +199,7 @@ Secret Detection can be customized by defining available CI/CD variables: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. You can customize the default secret detection rules provided with GitLab. -Customization allows you to exclude rules and add new rules. +Customization allows replace the default secret detection rules with rules that you define. To create a custom ruleset: @@ -258,7 +257,7 @@ want to perform a full secret scan. Running a secret scan on the full history ca 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`](../sast/#vulnerability-filters)) +A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-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. diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_10.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_10.png Binary files differnew file mode 100644 index 00000000000..72b24a3fd28 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_10.png diff --git a/doc/user/application_security/security_dashboard/img/security_center_dashboard_empty_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_dashboard_empty_v13_4.png Binary files differdeleted file mode 100644 index 5edceb32e5c..00000000000 --- a/doc/user/application_security/security_dashboard/img/security_center_dashboard_empty_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index b08c19bee47..8a2c40406e2 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -35,9 +35,7 @@ The security dashboard and vulnerability report displays information about vulne - [Static Application Security Testing](../sast/index.md) - And [others](../index.md#security-scanning-tools)! -## Requirements - -To use the security dashboards and vulnerability reports: +## Prerequisites 1. At least one project inside a group must be configured with at least one of the [supported reports](#supported-reports). @@ -52,7 +50,7 @@ To use the security dashboards and vulnerability reports: At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline ran against. - + Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view the pipeline's security findings, select the **Security** tab when viewing the pipeline. @@ -63,13 +61,21 @@ job finishes but the DAST job fails, the security dashboard doesn't show SAST re the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). +### Scan details + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. + +The **Scan details** section lists the scans run in the pipeline and the total number of +vulnerabilities per scan. For the DAST scan, select **Download scanned resources** to download a +CSV file containing details of the resources scanned. + ## Project Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. At the project level, the Security Dashboard displays a chart with the number of vulnerabilities over time. Access it by navigating to **Security & Compliance > Security Dashboard**. We display historical -data up to 365 days. +data up to 365 days. The chart's data is updated daily.  @@ -130,10 +136,6 @@ bar at the top of the page. Under **More**, select **Security**.  -The dashboard and vulnerability report are empty before you add projects. - - - ### Adding projects to the Security Center To add projects to the Security Center: @@ -175,7 +177,7 @@ lock files. Python projects can have lock files, but GitLab Secure tools don't s ## Security scans using Auto DevOps When using [Auto DevOps](../../../topics/autodevops/index.md), use -[special environment variables](../../../topics/autodevops/customize.md#environment-variables) +[special environment variables](../../../topics/autodevops/customize.md#cicd-variables) to configure daily security scans. <!-- ## Troubleshooting @@ -190,4 +192,4 @@ Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> -Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +Read more on how to [address the vulnerabilities](../index.md#addressing-vulnerabilities). diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 13bde2ed38b..747d31df356 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -186,7 +186,7 @@ There are two ways to create policy alerts: Once added, the UI updates and displays a warning about the dangers of too many alerts. -#### Enable or disable Policy Alerts **(FREE SELF)** +#### Enable or disable Policy Alerts **(ULTIMATE)** Policy Alerts is under development but ready for production use. It is deployed behind a feature flag that is **enabled by default**. @@ -223,4 +223,6 @@ checkbox **Hide dismissed alerts**.  +Clicking an alert's name takes the user to the [alert details page](../../../operations/incident_management/alerts.md#alert-details-page). + For information on work in progress for the alerts dashboard, see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/5041). diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 50f05b687f7..416db5b07fc 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -19,8 +19,7 @@ Each security vulnerability in a project's [Vulnerability Report](../vulnerabili On the vulnerability's page, you can: - [Change the vulnerability's status](#change-vulnerability-status). -- [Create a GitLab issue](#create-a-gitlab-issue-for-a-vulnerability). -- [Create a Jira issue](#create-a-jira-issue-for-a-vulnerability). +- [Create an issue](#create-an-issue-for-a-vulnerability). - [Link issues to the vulnerability](#link-gitlab-issues-to-the-vulnerability). - [Automatically remediate the vulnerability](#automatically-remediate-the-vulnerability), if an automatic solution is available. @@ -40,7 +39,21 @@ the following values: A timeline shows you when the vulnerability status has changed and allows you to comment on a change. -## Create a GitLab issue for a vulnerability +## Create an issue for a vulnerability + +From a vulnerability's page you can create an issue to track all action taken to resolve or +mitigate it. + +From a vulnerability you can create either: + +- [A GitLab issue](#create-a-gitlab-issue-for-a-vulnerability) (default). +- [A Jira issue](#create-a-jira-issue-for-a-vulnerability). + +Creating a Jira issue requires that +[Jira integration](../../project/integrations/jira_integrations.md) is enabled on the project. Note +that when Jira integration is enabled, the GitLab issue feature is not available. + +### Create a GitLab issue for a vulnerability To create a GitLab issue for a vulnerability: @@ -50,7 +63,7 @@ To create a GitLab issue for a vulnerability: An issue is created in the project, prepopulated with information from the vulnerability report. The issue is then opened so you can take further action. -## Create a Jira issue for a vulnerability +### Create a Jira issue for a vulnerability > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4677) in GitLab 13.9. > - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. @@ -64,16 +77,18 @@ This feature might not be available to you. Check the **version history** note a Prerequisites: -- [Enable Jira integration for vulnerabilities](../../project/integrations/jira.md). Select - **Enable Jira issues creation from vulnerabilities** when configuring the integration. +- [Enable Jira integration](../../project/integrations/jira.md). + The **Enable Jira issues creation from vulnerabilities** option must be selected as part of the configuration. +- Each user must have a personal Jira user account with permission to create issues in the target project. To create a Jira issue for a vulnerability: 1. Go to the vulnerability's page. 1. Select **Create Jira issue**. +1. If you're not already logged in to Jira, log in. -An issue is created in the linked Jira project, with the **Summary** and **Description** fields -pre-populated. The Jira issue is then opened in a new browser tab. +The Jira issue is created and opened in a new browser tab. The **Summary** and **Description** +fields are pre-populated from the vulnerability's details. ### Enable or disable Jira integration for vulnerabilities **(ULTIMATE SELF)** @@ -108,4 +123,4 @@ Linked issues are shown in the Vulnerability Report and the vulnerability's page ## Automatically remediate the vulnerability You can fix some vulnerabilities by applying the solution that GitLab automatically -generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#automatic-remediation-for-vulnerabilities). +generates for you. [Read more about the automatic remediation for vulnerabilities feature](../index.md#apply-an-automatic-remediation-for-a-vulnerability). diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png Binary files differdeleted file mode 100644 index ef96cf31fa4..00000000000 --- a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_dismissal_v13_9.png +++ /dev/null diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_9.png Binary files differnew file mode 100644 index 00000000000..f9f60810f20 --- /dev/null +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_9.png diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_9.png Binary files differdeleted file mode 100644 index 83e67a24b78..00000000000 --- a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_v13_9.png +++ /dev/null diff --git a/doc/user/application_security/vulnerability_report/img/vulnerability_details_create_issue_v13_7.png b/doc/user/application_security/vulnerability_report/img/vulnerability_details_create_issue_v13_7.png Binary files differdeleted file mode 100644 index 5184ad85fa9..00000000000 --- a/doc/user/application_security/vulnerability_report/img/vulnerability_details_create_issue_v13_7.png +++ /dev/null diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 28083e09f1c..583859e2541 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -5,91 +5,147 @@ 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 --- -# GitLab Vulnerability Reports **(ULTIMATE)** +# Vulnerability Report **(ULTIMATE)** -Each vulnerability report contains vulnerabilities from the scans of the most recent branch merged into the default branch. +The Vulnerability Report provides information about vulnerabilities from scans of the branch most +recently merged into the default branch. It is available at the instance, group, and project level. -The vulnerability reports display the total number of vulnerabilities by severity (for example, -Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's detected date, status, severity, description, identifier, the scanner where it was detected, and activity (including related issues or available solutions). By default, the vulnerability report is filtered to display all detected and confirmed vulnerabilities. +At all levels, the Vulnerability Report contains: + +- Totals of vulnerabilities per severity level. +- Filters for common vulnerability attributes. +- Details of each vulnerability, presented in tabular layout.  -You can filter which vulnerabilities display by: +## Project-level Vulnerability Report -| Filter | Available Options | -| --- | --- | -| Status | Detected, Confirmed, Dismissed, Resolved | -| Severity | Critical, High, Medium, Low, Info, Unknown | -| Scanner | [Available Scanners](../index.md#security-scanning-tools) | -| Project | Projects configured in the Security Center settings, or all projects in the group for the group level report. This filter is not displayed on the project level vulnerability report | -| Activity | Vulnerabilities with issues and vulnerabilities that are no longer detected in the default branch | +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in GitLab 11.1. -The Activity filter behaves differently from the other Vulnerability Report filters. The other filter options all OR together to show results from any vulnerability matching one of the filter criteria. With the Activity filter, the selected values form mutually exclusive sets to allow for precisely locating the desired vulnerability records. Additionally, not all options can be selected in combination. Selection behavior when using the Activity filter: +The project-level Vulnerability Report also contains: -| Activity Selection | Results Displayed | -| --- | --- | -| All | Vulnerabilities with any Activity status (same as ignoring this filter). Selecting this will deselect any other Activity filter options. | -| No activity | Only vulnerabilities without either an associated Issue or that are no longer detected. Selecting this will deselect any other Activity filter options. | -| With issues | Only vulnerabilities with one or more associated issues. Does not include vulnerabilities that also are no longer detected. | -| No longer detected | Only vulnerabilities that are no longer detected in the latest pipeline scan of the `default` branch. Does not include vulnerabilities with one or more associated issues. | -| With issues and No longer detected | Only vulnerabilities that have one or more associated issues and also are no longer detected in the latest pipeline scan of the `default` branch. | +- A time stamp showing when it was updated, including a link to the latest pipeline. +- The number of failures that occurred in the most recent pipeline. Select the failure + notification to view the **Failed jobs** tab of the pipeline's page. -Clicking any vulnerability in the table takes you to its -[vulnerability details](../vulnerabilities) page to see more information on that vulnerability. +To access the report, navigate to **Security & Compliance > Vulnerability Report**. -The **Activity** column indicates the number of issues that have been created for the vulnerability. -Hover over an **Activity** entry and select a link go to that issue. +## Vulnerability Report actions - +From the Vulnerability Report you can: -Contents of the unfiltered vulnerability report can be exported using our [export feature](#export-vulnerabilities). +- [Filter the list of vulnerabilities](#filter-the-list-of-vulnerabilities). +- [View more details about a vulnerability](#view-details-of-a-vulnerability). +- [View an issue raised for a vulnerability](#view-issues-raised-for-a-vulnerability). +- [Change the status of vulnerabilities](#change-status-of-vulnerabilities). +- [Export details of vulnerabilities](#export-vulnerability-details). -You can also dismiss vulnerabilities in the table: +## Vulnerability Report filters -1. Select the checkbox for each vulnerability you want to dismiss. -1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. +You can filter the vulnerabilities table by: - +| Filter | Available options | +|:---------|:------------------| +| Status | Detected, Confirmed, Dismissed, Resolved. | +| Severity | Critical, High, Medium, Low, Info, Unknown. | +| Scanner | [Available scanners](../index.md#security-scanning-tools). | +| Project | For more details, see [Project filter](#project-filter). | +| Activity | For more details, see [Activity filter](#activity-filter). | -## Project Vulnerability Report +### Filter the list of vulnerabilities -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. +To filter the list of vulnerabilities: -The vulnerabilities that exist in your project's -[default branch](../../project/repository/branches/index.md#default-branch) are accessed by navigating to -**Security & Compliance > Vulnerability Report**. +1. Select a filter. +1. Select values from the dropdown. +1. Repeat the above steps for each desired filter. -The project vulnerability report first displays the time at which the last pipeline completed on the project's -default branch. There's also a link to view this in more detail. In the case of any pipeline failures, -the number of failures is indicated. The failure notification takes you directly to -the **Failed jobs** tab of the pipeline page. +The vulnerability table is applied immediately. The vulnerability severity totals are also updated. - +The filters' criteria are combined to show only vulnerabilities matching all criteria. +An exception to this behavior is the Activity filter. For more details about how it works, see +[Activity filter](#activity-filter). -## Export vulnerabilities +### Project filter -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +The content of the Project filter depends on the current level: -You can export all your vulnerabilities in CSV (comma separated values) format by clicking the -**{upload}** **Export** button located at top right of the Security Dashboard. When the report is -ready, the CSV report downloads to your local machine. The report contains all vulnerabilities for -the projects defined in the Security Dashboard, as filters don't apply to the export function. +| Level | Content of the Project filter | +|:---------------|:------------------------------| +| Instance level | Only projects you've [added to the instance-level Security Center](../security_dashboard/index.md#adding-projects-to-the-security-center). | +| Group level | All projects in the group. | +| Project level | Not applicable. | -NOTE: -It may take several minutes for the download to start if your project contains -thousands of vulnerabilities. Don't close the page until the download finishes. +### Activity filter + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259255) in GitLab 13.9 -The fields in the export include: +The Activity filter behaves differently from the other filters. The selected values form mutually +exclusive sets to allow for precisely locating the desired vulnerability records. Additionally, not +all options can be selected in combination. + +Selection behavior when using the Activity filter: + +| Activity selection | Results displayed | +|:------------------------------------|:------------------| +| All | Vulnerabilities with any Activity status (same as ignoring this filter). Selecting this will deselect any other Activity filter options. | +| No activity | Only vulnerabilities without either an associated Issue or that are no longer detected. Selecting this will deselect any other Activity filter options. | +| With issues | Only vulnerabilities with one or more associated issues. Does not include vulnerabilities that also are no longer detected. | +| No longer detected | Only vulnerabilities that are no longer detected in the latest pipeline scan of the `default` branch. Does not include vulnerabilities with one or more associated issues. | +| With issues and No longer detected | Only vulnerabilities that have one or more associated issues and also are no longer detected in the latest pipeline scan of the `default` branch. | + +## View details of a vulnerability + +To view more details of a vulnerability, select the vulnerability's **Description**. The +[vulnerability's details](../vulnerabilities) page is opened. + +## View issues raised for a vulnerability + +The **Activity** column indicates the number of issues that have been created for the vulnerability. +Hover over an **Activity** entry and select a link go to that issue. -- Group Name -- Project Name -- Scanner Type -- Scanner Name + + +## Change status of vulnerabilities + +To change the status of vulnerabilities in the table: + +1. Select the checkbox for each vulnerability you want to update the status of. +1. In the dropdown that appears select the desired status, then select **Change status**. + + + +## Export vulnerability details + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in the Security Center (previously known as the Instance Security Dashboard) and project-level Vulnerability Report (previously known as the Project Security Dashboard) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213013) to the group-level Vulnerability Report in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + +You can export details of the vulnerabilities listed in the Vulnerability Report. The export format +is CSV (comma separated values). Note that all vulnerabilities are included because filters don't +apply to the export. + +Fields included are: + +- Group name +- Project name +- Scanner type +- Scanner name - Status - Vulnerability - Details -- Additional Information +- Additional information - Severity - [CVE](https://cve.mitre.org/) (Common Vulnerabilities and Exposures) - [CWE](https://cwe.mitre.org/) (Common Weakness Enumeration) -- Other Identifiers +- Other identifiers + +### Export details in CSV format + +To export details of all vulnerabilities listed in the Vulnerability Report, select **Export**. + +The details are retrieved from the database, then the CSV file is downloaded to your local +computer. + +NOTE: +It may take several minutes for the download to start if your project contains +thousands of vulnerabilities. Don't close the page until the download finishes. |
