diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-02-20 13:49:51 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-02-20 13:49:51 +0000 |
| commit | 71786ddc8e28fbd3cb3fcc4b3ff15e5962a1c82e (patch) | |
| tree | 6a2d93ef3fb2d353bb7739e4b57e6541f51cdd71 /doc/user/application_security | |
| parent | a7253423e3403b8c08f8a161e5937e1488f5f407 (diff) | |
| download | gitlab-ce-71786ddc8e28fbd3cb3fcc4b3ff15e5962a1c82e.tar.gz | |
Add latest changes from gitlab-org/gitlab@15-9-stable-eev15.9.0-rc42
Diffstat (limited to 'doc/user/application_security')
36 files changed, 516 insertions, 395 deletions
diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md index 5e033a75902..0ad87facc50 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -109,7 +109,7 @@ responses in HAR format. have an account, first create an account. 1. Browse pages that call an API. Fiddler automatically captures the requests. 1. Select one or more requests, then from the context menu, select **Export > Selected Sessions**. -1. In the **Choose Format** dropdown list select **HTTP Archive v1.2**. +1. In the **Choose Format** dropdown list select **HTTPArchive v1.2**. 1. Enter a filename and select **Save**. Fiddler shows a popup message confirming the export has succeeded. @@ -211,7 +211,7 @@ Review the HAR file for any of the following: We strongly recommended that you [edit or remove it](#edit-or-remove-sensitive-information) any sensitive information. -Use the following as a checklist to start with. Note that it's not an exhaustive list. +Use the following as a checklist to start with. It's not an exhaustive list. - Look for secrets. For example: if your application requires authentication, check common locations or authentication information: diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 31322419902..b55c5a1b299 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -26,7 +26,7 @@ Note the following changes have been made to the API fuzzing template: - In GitLab 14.0 and later, you must define a `fuzz` stage in your `.gitlab-ci.yml` file. - In GitLab 13.12 and earlier, the API fuzzing template defines `build`, `test`, `deploy`, and - `fuzz` stages. The `fuzz` stage runs last by default. The predefined stages were deprecated, and removed from the `API-Fuzzing.latest.gitlab-ci.yml` template. They will be removed in a future GitLab + `fuzz` stages. The `fuzz` stage runs last by default. The predefined stages were deprecated, and removed from the `API-Fuzzing.latest.gitlab-ci.yml` template. We plan to remove them in a future GitLab version. If your pipeline is configured to deploy to the same web server on each run, running a @@ -142,11 +142,11 @@ OpenAPI 2.x lets you specify the accepted media types globally or per operation, - In GitLab 14.9 and earlier, the default behavior is to perform testing using all supported media types. This means if two media types are listed (for example, `application/json` and `application/xml`), tests are performed using JSON, and then the same tests using XML. Testing the same operation (for example, `POST /user`) using different media types (for example, `application/json` and `application/xml`) is not always desirable. -For example, if the target application executes the same code regardless of the request content type, it will take longer to finish the test session, and it may report duplicate vulnerabilities related to the request body depending on the target app. +For example, if the target application executes the same code regardless of the request content type, it takes longer to finish the test session, and it may report duplicate vulnerabilities related to the request body depending on the target app. -The environment variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environmental variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` is set to any value, API Fuzzing will try to generate requests for all supported media types instead of one in a given operation. This will cause testing to take longer as testing is repeated for each provided media type. +The environment variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` lets you specify whether or not to use all supported media types instead of one when generating requests for a given operation. When the environmental variable `FUZZAPI_OPENAPI_ALL_MEDIA_TYPES` is set to any value, API Fuzzing tries to generate requests for all supported media types instead of one in a given operation. This causes testing to take longer as testing is repeated for each provided media type. -Alternatively, the variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is used to provide a list of media types that will each be tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is set to a list of media types, only the listed media types are included when creating requests. +Alternatively, the variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is used to provide a list of media types that each is tested. Providing more than one media type causes testing to take longer, as testing is performed for each media type selected. When the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` is set to a list of media types, only the listed media types are included when creating requests. Multiple media types in `FUZZAPI_OPENAPI_MEDIA_TYPES` must separated by a colon (`:`). For example, to limit request generation to the media types `application/x-www-form-urlencoded` and `multipart/form-data`, set the environment variable `FUZZAPI_OPENAPI_MEDIA_TYPES` to `application/x-www-form-urlencoded:multipart/form-data`. Only supported media types in this list are included when creating requests, though unsupported media types are always skipped. A media type text may contain different sections. For example, `application/vnd.api+json; charset=UTF-8` is a compound of `type "/" [tree "."] subtype ["+" suffix]* [";" parameter]`. Parameters are not taken into account when filtering media types on request generation. @@ -1390,7 +1390,7 @@ By default the output of the overrides command is hidden. If the overrides comma It is also possible to write messages from your script to a log file that is collected when the job completes or fails. The log file must be created in a specific location and follow a naming convention. -Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during normal running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. +Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during typical running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. Following our example, we provided `renew_token.py` in the environmental variable `FUZZAPI_OVERRIDES_CMD`. Notice two things in the script: @@ -1499,7 +1499,7 @@ logging.info("Override file has been updated") # end ``` -In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `FUZZAPI_PRE_SCRIPT` is set to a script that will install the dependencies of your overrides command. +In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `FUZZAPI_PRE_SCRIPT` is set to a script that installs the dependencies of your overrides command. As for example, the following script `user-pre-scan-set-up.sh`: ```shell @@ -1589,7 +1589,7 @@ variables: While testing an API you may might want to exclude a parameter (query string, header, or body element) from testing. This may be needed because a parameter always causes a failure, slows down testing, or for other reasons. To exclude parameters you can use one of the following variables: `FUZZAPI_EXCLUDE_PARAMETER_ENV` or `FUZZAPI_EXCLUDE_PARAMETER_FILE`. -The `FUZZAPI_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and will not often change. Another option is the variable `FUZZAPI_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime from a pre-script using `FUZZAPI_PRE_SCRIPT`. +The `FUZZAPI_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and can not often change. Another option is the variable `FUZZAPI_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime from a pre-script using `FUZZAPI_PRE_SCRIPT`. #### Exclude parameters using a JSON document @@ -1991,7 +1991,7 @@ Repeat this configuration for each profile as needed. When configured correctly, a CI/CD pipeline contains a `fuzz` stage and an `apifuzzer_fuzz` or `apifuzzer_fuzz_dnd` job. The job only fails when an invalid configuration is provided. During -normal operation, the job always succeeds even if faults are identified during fuzz testing. +typical operation, the job always succeeds even if faults are identified during fuzz testing. Faults are displayed on the **Security** pipeline tab with the suite name. When testing against the repositories default branch, the fuzzing faults are also shown on the Security & Compliance's @@ -2026,7 +2026,7 @@ Follow these steps to view details of a fuzzing fault: 1. You can view faults in a project, or a merge request: - - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + - In a project, go to the project's **Security & Compliance > Vulnerability Report** page. This page shows all vulnerabilities from the default branch only. - In a merge request, go the merge request's **Security** section and select the **Expand** button. API Fuzzing faults are available in a section labeled @@ -2042,7 +2042,7 @@ Follow these steps to view details of a fuzzing fault: | Method | HTTP method used to detect the vulnerability. | | URL | URL at which the vulnerability was detected. | | Request | The HTTP request that caused the fault. | - | Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | + | Unmodified Response | Response from an unmodified request. This is what a typical working response looks like. | | Actual Response | Response received from fuzzed request. | | Evidence | How we determined a fault occurred. | | Identifiers | The fuzzing check used to find this fault. | @@ -2377,7 +2377,7 @@ apifuzzer_v2: In the case of one or two slow operations, the team might decide to skip testing the operations, or exclude them from feature branch tests, but include them for default branch tests. Excluding the operation is done using the `FUZZAPI_EXCLUDE_PATHS` configuration [variable as explained in this section.](#exclude-paths) -In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `FUZZAPI_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `apifuzzer_fuzz` job and creates two new jobs `apifuzzer_main` and `apifuzzer_branch`. The `apifuzzer_branch` is set up to exclude the long operation and only run on non-default branches (e.g. feature branches). The `apifuzzer_main` branch is set up to only execute on the default branch (`main` in this example). The `apifuzzer_branch` jobs run faster, allowing for quick development cycles, while the `apifuzzer_main` job which only runs on default branch builds, takes longer to run. +In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `FUZZAPI_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `apifuzzer_fuzz` job and creates two new jobs `apifuzzer_main` and `apifuzzer_branch`. The `apifuzzer_branch` is set up to exclude the long operation and only run on non-default branches (for example, feature branches). The `apifuzzer_main` branch is set up to only execute on the default branch (`main` in this example). The `apifuzzer_branch` jobs run faster, allowing for quick development cycles, while the `apifuzzer_main` job which only runs on default branch builds, takes longer to run. To verify the operation is excluded, run the API Fuzzing job and review the job console output. It includes a list of included and excluded operations at the end of the test. @@ -2538,14 +2538,14 @@ The API Fuzzing engine outputs an error message when it cannot establish a conne **Solution** -- Remove the `FUZZAPI_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the API Fuzzing CI/CD template. We recommend this method instead of manually setting a value. +- Remove the `FUZZAPI_API` variable from the `.gitlab-ci.yml` file. The value is inherited from the API Fuzzing CI/CD template. We recommend this method instead of manually setting a value. - If removing the variable is not possible, check to see if this value has changed in the latest version of the [API Fuzzing CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. ### `Application cannot determine the base URL for the target API` The API Fuzzing analyzer outputs an error message when it cannot determine the target API after inspecting the OpenAPI document. This error message is shown when the target API has not been set in the `.gitlab-ci.yml`file, it is not available in the `environment_url.txt` file, and it could not be computed using the OpenAPI document. -There is an order of precedence in which the API Fuzzing analyzer tries to get the target API when checking the different sources. First, it will try to use the `FUZZAPI_TARGET_URL`. If the environment variable has not been set, then the API Fuzzing analyzer will attempt to use the `environment_url.txt` file. If there is no file `environment_url.txt`, the API Fuzzing analyzer will then use the OpenAPI document contents and the URL provided in `FUZZAPI_OPENAPI` (if a URL is provided) to try to compute the target API. +There is an order of precedence in which the API Fuzzing analyzer tries to get the target API when checking the different sources. First, it tries to use the `FUZZAPI_TARGET_URL`. If the environment variable has not been set, then the API Fuzzing analyzer attempts to use the `environment_url.txt` file. If there is no file `environment_url.txt`, the API Fuzzing analyzer now uses the OpenAPI document contents and the URL provided in `FUZZAPI_OPENAPI` (if a URL is provided) to try to compute the target API. The best-suited solution depends on whether or not your target API changes for each deployment: @@ -2642,7 +2642,7 @@ variables: ### `No operation in the OpenAPI document is consuming any supported media type` -API Fuzzing uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. +API Fuzzing uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error is thrown. **Error message** diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index fc06b50b03d..0a586a14cc4 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -234,7 +234,7 @@ When you enable this feature, you may see [duplicate findings](../terminology/in in the [Vulnerability Report](../vulnerability_report/index.md) if [Dependency Scanning](../dependency_scanning/index.md) is enabled for your project. This happens because GitLab can't automatically deduplicate findings -across different types of scanning tools. Please reference [this comparison](../dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning) +across different types of scanning tools. Reference [this comparison](../dependency_scanning/index.md#dependency-scanning-compared-to-container-scanning) between GitLab Dependency Scanning and Container Scanning for more details on which types of dependencies are likely to be duplicated. #### Available CI/CD variables @@ -268,6 +268,7 @@ including a large number of false positives. | `CS_REGISTRY_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | | `CS_REGISTRY_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. The default is only set if `$CS_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). Not supported when [FIPS mode](../../../development/fips_compliance.md#enable-fips-mode) is enabled. | All | | `CS_DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | +| `CS_QUIET` | `""` | If set, this variable disables output of the [vulnerabilities table](#container-scanning-job-log-format) in the job log. [Introduced](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/merge_requests/50) in GitLab 15.1. | All | | `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | All | ### Supported distributions @@ -532,7 +533,7 @@ To use container scanning in an offline environment, you need: | --- | --- | | [Container-Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) | [Container-Scanning container registry](https://gitlab.com/security-products/container-scanning/container_registry/) | -Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -560,7 +561,7 @@ registry.gitlab.com/security-products/container-scanning/trivy:5 ``` The process for importing Docker images into a local offline Docker registry depends on -**your network security policy**. Please consult your IT staff to find an accepted and approved +**your network security policy**. Consult your IT staff to find an accepted and approved process by which you can import or temporarily access external resources. These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance), and you may be able to make occasional updates on your own. @@ -580,7 +581,7 @@ For details on saving and transporting Docker images as a file, see the Docker d - template: Jobs/Container-Scanning.gitlab-ci.yml container_scanning: - image: $CI_REGISTRY/namespace/gitlab-container-scanning + image: $CI_REGISTRY/namespace/container-scanning ``` 1. If your local Docker container registry is running securely over `HTTPS`, but you're using a @@ -597,7 +598,7 @@ following `.gitlab-ci.yml` example as a template. ```yaml variables: SOURCE_IMAGE: registry.gitlab.com/security-products/container-scanning:5 - TARGET_IMAGE: $CI_REGISTRY/namespace/gitlab-container-scanning + TARGET_IMAGE: $CI_REGISTRY/namespace/container-scanning image: docker:stable diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 71c842ca277..5d2593a1bed 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -102,7 +102,7 @@ targets. Each fuzzing target **must** have a separate job. For example, the [go-fuzzing-example project](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) contains one job that extends `.fuzz_base` for its single fuzzing target. -Note that the hidden job `.fuzz_base` uses several YAML keys that you must not override in your own +The hidden job `.fuzz_base` uses several YAML keys that you must not override in your own job. If you include these keys in your own job, you must copy their original content: - `before_script` diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index d5ba92f399c..77732ab532c 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -5,13 +5,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Authentication (DAST) **(ULTIMATE)** +# DAST authentication **(ULTIMATE)** WARNING: -**Never** run an authenticated scan against a production server. -Authenticated scans may perform *any* function that the authenticated user can, +**DO NOT** use credentials that are valid for production systems, production servers, or any that +contain production data. + +WARNING: +**DO NOT** run an authenticated scan against a production server. +Authenticated scans may perform **any** function that the authenticated user can, including modifying or deleting data, submitting forms, and following links. -Only run an authenticated scan against a test server. +Only run an authenticated scan against non-production systems or servers. Authentication logs a user in before a DAST scan so that the analyzer can test as much of the application as possible when searching for vulnerabilities. @@ -44,8 +48,8 @@ To run a DAST authenticated scan: - You are using either the [DAST proxy-based analyzer](proxy-based.md) or the [DAST browser-based analyzer](browser_based.md). - You know the URL of the login form of your application. Alternatively, you know how to navigate to the login form from the authentication URL (see [clicking to navigate to the login form](#clicking-to-navigate-to-the-login-form)). - You have the username and password of the user you would like to authenticate as during the scan. -- You know the [selectors](#finding-an-elements-selector) of the username and password HTML fields that DAST will use to input the respective values. -- You know the element's [selector](#finding-an-elements-selector) that will submit the login form when selected. +- You know the [selectors](#finding-an-elements-selector) of the username and password HTML fields that DAST uses to input the respective values. +- You know the element's [selector](#finding-an-elements-selector) that submits the login form when selected. - You have thought about how you can [verify](#verifying-authentication-is-successful) whether or not authentication was successful. - You have checked the [known limitations](#known-limitations) to ensure DAST can authenticate to your application. @@ -140,7 +144,7 @@ See [Custom CI/CI variables](../../../ci/variables/index.md#for-a-project) for m ### Configuration for Single Sign-On (SSO) -If a user can log into an application, then in most cases, DAST will also be able to log in. +If a user can log into an application, then in most cases, DAST is also able to log in. This is the case even when an application uses Single Sign-on. Applications using SSO solutions should configure DAST authentication using the [single-step](#configuration-for-a-single-step-login-form) or [multi-step](#configuration-for-a-multi-step-login-form) login form configuration guides. @@ -168,8 +172,8 @@ dast: ### Excluding logout URLs -If DAST crawls the logout URL while running an authenticated scan, the user will be logged out, resulting in the remainder of the scan being unauthenticated. -It is therefore recommended to exclude logout URLs using the CI/CD variable `DAST_EXCLUDE_URLS`. DAST will not access any excluded URLs, ensuring the user remains logged in. +If DAST crawls the logout URL while running an authenticated scan, the user is logged out, resulting in the remainder of the scan being unauthenticated. +It is therefore recommended to exclude logout URLs using the CI/CD variable `DAST_EXCLUDE_URLS`. DAST isn't accessing any excluded URLs, ensuring the user remains logged in. Provided URLs can be either absolute URLs, or regular expressions of URL paths relative to the base path of the `DAST_WEBSITE`. For example: @@ -193,7 +197,7 @@ Selectors have the format `type`:`search string`. DAST searches for the selector | `css` | `css:.password-field` | Searches for a HTML element having the supplied CSS selector. Selectors should be as specific as possible for performance reasons. | | `id` | `id:element` | Searches for an HTML element with the provided element ID. | | `name` | `name:element` | Searches for an HTML element with the provided element name. | -| `xpath` | `xpath://input[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. Note that XPath searches are expected to be less performant than other searches. | +| `xpath` | `xpath://input[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. XPath searches are expected to be less performant than other searches. | | None provided | `a.click-me` | Defaults to searching using a CSS selector. **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383348)** in GitLab 15.8. Replaced by explicitly declaring the selector type. | #### Find selectors with Google Chrome @@ -234,7 +238,7 @@ When using selectors to locate specific fields we recommend you avoid searching ## Verifying authentication is successful Once DAST has submitted the login form, a verification process takes place -to determine if authentication succeeded. The scan will halt with an error if authentication is unsuccessful. +to determine if authentication succeeded. The scan halts with an error if authentication is unsuccessful. Following the submission of the login form, authentication is determined to be unsuccessful when: @@ -247,13 +251,13 @@ Following the submission of the login form, authentication is determined to be u Verification checks run checks on the state of the browser once authentication is complete to determine further if authentication succeeded. -DAST will test for the absence of a login form if no verification checks are configured. +DAST tests for the absence of a login form if no verification checks are configured. #### Verify based on the URL Define `DAST_AUTH_VERIFICATION_URL` as the URL displayed in the browser tab once the login form is successfully submitted. -DAST will compare the verification URL to the URL in the browser after authentication. +DAST compares the verification URL to the URL in the browser after authentication. If they are not the same, authentication is unsuccessful. For example: @@ -270,7 +274,7 @@ dast: #### Verify based on presence of an element -Define `DAST_AUTH_VERIFICATION_SELECTOR` as a [selector](#finding-an-elements-selector) that will find one or many elements on the page +Define `DAST_AUTH_VERIFICATION_SELECTOR` as a [selector](#finding-an-elements-selector) that finds one or many elements on the page displayed once the login form is successfully submitted. If no element is found, authentication is unsuccessful. Searching for the selector on the page displayed when login fails should return no elements. @@ -333,8 +337,8 @@ dast: ## Known limitations -- DAST cannot bypass a CAPTCHA if the authentication flow includes one. Please turn these off in the testing environment for the application being scanned. -- DAST cannot handle multi-factor authentication like one-time passwords (OTP) by using SMS, biometrics, or authenticator apps. Please turn these off in the testing environment for the application being scanned. +- DAST cannot bypass a CAPTCHA if the authentication flow includes one. Turn these off in the testing environment for the application being scanned. +- DAST cannot handle multi-factor authentication like one-time passwords (OTP) by using SMS, biometrics, or authenticator apps. Turn these off in the testing environment for the application being scanned. - DAST cannot authenticate to applications that do not set an [authentication token](#authentication-tokens) during login. - DAST cannot authenticate to applications that require more than two inputs to be filled out. Two inputs must be supplied, username and password. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index 96480bcb6a5..bdc08988cc0 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -227,13 +227,13 @@ In such cases, we recommend you disable Anti-CSRF tokens when running a full sca ## Managing scan time -It is expected that running the browser-based crawler results in better coverage for many web applications, when compared to the normal GitLab DAST solution. +It is expected that running the browser-based crawler results in better coverage for many web applications, when compared to the standard GitLab DAST solution. This can come at a cost of increased scan time. You can manage the trade-off between coverage and scan time with the following measures: - Limit the number of actions executed by the browser with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_ACTIONS`. The default is `10,000`. -- Limit the page depth that the browser-based crawler will check coverage on with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. +- Limit the page depth that the browser-based crawler checks coverage on with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. - Vertically scale the runner and use a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. ## Timeouts diff --git a/doc/user/application_security/dast/browser_based_troubleshooting.md b/doc/user/application_security/dast/browser_based_troubleshooting.md index 78f2723ee38..6cc80bcfbc3 100644 --- a/doc/user/application_security/dast/browser_based_troubleshooting.md +++ b/doc/user/application_security/dast/browser_based_troubleshooting.md @@ -53,7 +53,7 @@ Knowing the outcome you expect, try to replicate it manually using a browser on DAST cannot scan correctly when: -- There is a CAPTCHA. Please turn these off in the testing environment for the application being scanned. +- There is a CAPTCHA. Turn these off in the testing environment for the application being scanned. - It does not have access to the target application. Ensure the GitLab Runner can access the application using the URLs used in the DAST configuration. ### How does your application work? diff --git a/doc/user/application_security/dast/checks/16.7.md b/doc/user/application_security/dast/checks/16.7.md index cef13c9663f..d407234d2c2 100644 --- a/doc/user/application_security/dast/checks/16.7.md +++ b/doc/user/application_security/dast/checks/16.7.md @@ -25,8 +25,7 @@ Only three directives are applicable for the `Strict-Transport-Security` header. Note that invalid directives, or the `Strict-Transport-Security` header appearing more than once (if the values are different) is considered invalid. -Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org -[Deployment Recommendations](https://hstspreload.org/#deployment-recommendations). +Prior to adding to this security configuration to your website, it is recommended you review the hstspreload.org [Deployment Recommendations](https://hstspreload.org/#deployment-recommendations). ## Details diff --git a/doc/user/application_security/dast/checks/16.8.md b/doc/user/application_security/dast/checks/16.8.md index 07bd2a6842f..b8faef75de7 100644 --- a/doc/user/application_security/dast/checks/16.8.md +++ b/doc/user/application_security/dast/checks/16.8.md @@ -8,12 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description -A `Content-Security-Policy` (CSP) was identified on the target site. CSP can aid in hardening -a website against various client side attacks such as Cross-Site Scripting (XSS). +A missing or invalid `Content-Security-Policy` (CSP) was identified on the target site. CSP can aid in +hardening a website against various client side attacks such as Cross-Site Scripting (XSS). ## Remediation -Follow the recommendations to determine if any actions are necessary to harden this `Content-Security-Policy`. +If the target site is missing a CSP, please investigate the relevant URLs for enabling CSP. Otherwise, +follow the recommendations to determine if any actions are necessary. ## Details diff --git a/doc/user/application_security/dast/checks/22.1.md b/doc/user/application_security/dast/checks/22.1.md new file mode 100644 index 00000000000..60a73b4248b --- /dev/null +++ b/doc/user/application_security/dast/checks/22.1.md @@ -0,0 +1,38 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Improper limitation of a pathname to a restricted directory (Path traversal) + +## Description + +The vulnerability can be exploited by inserting a payload into a +parameter on the URL endpoint which allows for reading arbitrary files. +This could be used to read sensitive files, access other users data, or aid in +exploitation to gain further system access. + +## Remediation + +User input should never be used in constructing paths or files for interacting +with the filesystem. This includes filenames supplied by user uploads or downloads. + +If possible, consider hashing the filenames and reference the hashed filenames in +a database or datastore instead of directly attempting to access filenames provided +by users or other system components. + +In the rare cases that the application must work with filenames, use the language +provided functionality to extract only the filename part of the supplied value. +Never attempt to use the path or directory information that comes from user input. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 22.1 | false | 22 | Active | high | + +## Links + +- [OWASP](https://owasp.org/www-community/attacks/Path_Traversal) +- [CWE](https://cwe.mitre.org/data/definitions/22.html) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 56406b24586..bafe426ca43 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -8,6 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w The [DAST browser-based crawler](../browser_based.md) provides a number of vulnerability checks that are used to scan for vulnerabilities in the site under test. +## Passive Checks + | ID | Check | Severity | Type | |:---|:------|:---------|:-----| | [1004.1](1004.1.md) | Sensitive cookie without HttpOnly attribute | Low | Passive | @@ -126,7 +128,7 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [798.94](798.94.md) | Exposure of confidential secret or token Private Key | High | Passive | | [798.95](798.95.md) | Exposure of confidential secret or token Pulumi API token | High | Passive | | [798.96](798.96.md) | Exposure of confidential secret or token PyPI upload token | High | Passive | -| [798.97](798.97.md) | Exposure of confidential secret or token RubyGem API token | High | Passive | +| [798.97](798.97.md) | Exposure of confidential secret or token RubyGems API token | High | Passive | | [798.98](798.98.md) | Exposure of confidential secret or token RapidAPI Access Token | High | Passive | | [798.99](798.99.md) | Exposure of confidential secret or token Sendbird Access ID | High | Passive | | [798.100](798.100.md) | Exposure of confidential secret or token Sendbird Access Token | High | Passive | @@ -160,3 +162,9 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [798.128](798.128.md) | Exposure of confidential secret or token Zendesk Secret Key | High | Passive | | [829.1](829.1.md) | Inclusion of Functionality from Untrusted Control Sphere | Low | Passive | | [829.2](829.2.md) | Invalid Sub-Resource Integrity values detected | Medium | Passive | + +## Active Checks + +| ID | Check | Severity | Type | +|:---|:------|:---------|:-----| +| [22.1](22.1.md) | Improper limitation of a pathname to a restricted directory (Path traversal) | High | Active | diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 0dcf203a3a9..da382920604 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -77,7 +77,7 @@ For information on this, see the [general Application Security troubleshooting s To avoid overwriting stages from other CI files, newer versions of the DAST CI template do not define stages. If you recently started using `DAST.latest.gitlab-ci.yml` or upgraded to a new major release of GitLab and began receiving this error, you must define a `dast` stage with your other -stages. Note that you must have a running application for DAST to scan. If your application is set +stages. You must have a running application for DAST to scan. If your application is set up in your pipeline, it must be deployed in a stage _before_ the `dast` stage: ```yaml diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 283e48ec499..3cb8967afd2 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -57,7 +57,7 @@ which GitLab uses to determine discovered vulnerabilities based on differences b #### Recommendations -- Take care if your pipeline is configured to deploy to the same web server in each run. Running a DAST scan while a server is being updated will lead to inaccurate and non-deterministic results. +- Take care if your pipeline is configured to deploy to the same web server in each run. Running a DAST scan while a server is being updated leads to inaccurate and non-deterministic results. - Configure runners to use the [always pull policy](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy) to run the latest versions of the analyzers. - By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If your DAST job does not rely on `environment_url.txt` to define the URL under test or any other files created @@ -71,7 +71,7 @@ which GitLab uses to determine discovered vulnerabilities based on differences b #### Analyzer configuration -Please see [DAST proxy-based analyzer](proxy-based.md), [DAST browser-based analyzer](browser_based.md) or [DAST API analyzer](../dast_api/index.md) for +See [DAST proxy-based analyzer](proxy-based.md), [DAST browser-based analyzer](browser_based.md) or [DAST API analyzer](../dast_api/index.md) for analyzer-specific configuration instructions. ### View scan results @@ -83,8 +83,8 @@ and the [Vulnerability report](../index.md#view-security-scan-information-in-the 1. To see all vulnerabilities detected, either: - From your project, select **Security & Compliance**, then **Vulnerability report**. - - From your pipeline, click on the **Security** tab. - - From the merge request, go to the **Security scanning** widget and click **Full report** tab. + - From your pipeline, select the **Security** tab. + - From the merge request, go to the **Security scanning** widget and select **Full report** tab. 1. Select a DAST vulnerability's description. The following fields are examples of what a DAST analyzer may produce to aid investigation and rectification of the underlying cause. Each analyzer may output different fields. @@ -142,7 +142,7 @@ After your Docker build job completes and your image is added to your container By using service definitions in your `.gitlab-ci.yml`, you can scan services with the DAST analyzer. -When adding a `services` section to the job, the `alias` is used to define the hostname that can be used to access the service. In the following example, the `alias: yourapp` portion of the `dast` job definition means that the URL to the deployed application will use `yourapp` as the hostname (`https://yourapp/`). +When adding a `services` section to the job, the `alias` is used to define the hostname that can be used to access the service. In the following example, the `alias: yourapp` portion of the `dast` job definition means that the URL to the deployed application uses `yourapp` as the hostname (`https://yourapp/`). ```yaml stages: diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index fc78018bdad..f70afac4c26 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -9,7 +9,7 @@ type: reference, howto The DAST proxy-based analyzer can be added to your [GitLab CI/CD](../../../ci/index.md) pipeline. This helps you discover vulnerabilities in web applications that do not use JavaScript heavily. For applications that do, -please see the [DAST browser-based analyzer](browser_based.md). +see the [DAST browser-based analyzer](browser_based.md). WARNING: Do not run DAST scans against a production server. Not only can it perform *any* function that @@ -231,7 +231,7 @@ variables: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. To specify the paths to scan in a CI/CD variable, add a comma-separated list of the paths to the `DAST_PATHS` -variable. Note that you can only scan paths of a single host. +variable. You can only scan paths of a single host. ```yaml include: @@ -247,7 +247,7 @@ When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: - `DAST_WEBSITE` must be defined when using either `DAST_PATHS_FILE` or `DAST_PATHS`. The paths listed in either use `DAST_WEBSITE` to build the URLs to scan - Spidering is disabled when `DAST_PATHS` or `DAST_PATHS_FILE` are defined - `DAST_PATHS_FILE` and `DAST_PATHS` cannot be used together -- The `DAST_PATHS` variable has a limit of about 130kb. If you have a list or paths +- The `DAST_PATHS` variable has a limit of about 130 kb. If you have a list or paths greater than this, use `DAST_PATHS_FILE`. #### Full Scan @@ -360,13 +360,14 @@ including a large number of false positives. |:------------------------------------------------|:--------------|:------------------------------| | `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. | | `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | +| `DAST_ALLOWED_HOSTS` | Comma-separated list of strings | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. Headers set using `DAST_REQUEST_HEADERS` are added to every request made to these hostnames. Example, `site.com,another.com`. | | `DAST_API_HOST_OVERRIDE` <sup>1</sup> | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. Replaced by [DAST API scan](../dast_api/index.md#available-cicd-variables). Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080`. | | `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383467)** in GitLab 15.7. Replaced by [DAST API scan](../dast_api/index.md#available-cicd-variables). The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. The variable `DAST_WEBSITE` must be specified if this is omitted. | | `DAST_AUTH_EXCLUDE_URLS` | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_URLS`. The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false`. | | `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | -| `DAST_EXCLUDE_URLS` <sup>1</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Example, `http://example.com/sign-out`. | +| `DAST_EXCLUDE_URLS` <sup>1</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Example, `http://example.com/sign-out`. | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Default: `false` | | `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | | `DAST_HTML_REPORT` | string | **{warning}** **[Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/384340)** in GitLab 15.7. The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | @@ -427,7 +428,7 @@ dast: The ZAProxy server contains many [useful configurable values](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_245801885). Many key/values for `-config` remain undocumented, but there is an untested list of [possible keys](https://gitlab.com/gitlab-org/gitlab/-/issues/36437#note_244981023). -Note that these options are not supported by DAST, and may break the DAST scan +These options are not supported by DAST, and may break the DAST scan when used. An example of how to rewrite the Authorization header value with `TOKEN` follows: ```yaml diff --git a/doc/user/application_security/dast/run_dast_offline.md b/doc/user/application_security/dast/run_dast_offline.md index 7cb4eff8e68..a75e5832b7c 100644 --- a/doc/user/application_security/dast/run_dast_offline.md +++ b/doc/user/application_security/dast/run_dast_offline.md @@ -20,7 +20,7 @@ To use DAST in an offline environment, you need: [container image](https://gitlab.com/security-products/dast), found in the [DAST container registry](https://gitlab.com/security-products/dast/container_registry). -Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -34,7 +34,7 @@ For DAST, import the following default DAST analyzer image from `registry.gitlab - `registry.gitlab.com/security-products/dast:latest` The process for importing Docker images into a local offline Docker registry depends on -**your network security policy**. Please consult your IT staff to find an accepted and approved +**your network security policy**. Consult your IT staff to find an accepted and approved process by which external resources can be imported or temporarily accessed. These scanners are [periodically updated](../index.md#vulnerability-scanner-maintenance) with new definitions, and you may be able to make occasional updates on your own. diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 4c324033140..0cdbb879cfc 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -5,13 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# DAST API **(ULTIMATE)** +# DAST API analyzer **(ULTIMATE)** > DAST API analyzer [became the default analyzer for on-demand DAST API scans](https://gitlab.com/groups/gitlab-org/-/epics/4254) in GitLab 15.6. Perform Dynamic Application Security Testing (DAST) of web APIs to help discover bugs and potential security issues that other QA processes may miss. Use DAST API tests in addition to -[GitLab Secure](../index.md)'s other security scanners and your own test processes. You can run DAST +other [GitLab Secure](../index.md) security scanners and your own test processes. You can run DAST API tests either as part your CI/CD workflow, [on-demand](../dast/proxy-based.md#on-demand-scans), or both. WARNING: @@ -1161,7 +1161,7 @@ Example usage for setting a `body-json` override: } ``` -Note that each JSON property name in the object `body-json` is set to a [JSON Path](https://goessner.net/articles/JsonPath/) +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. @@ -1200,7 +1200,7 @@ the second entry overrides an XML element: } ``` -Note that each JSON property name in the object `body-xml` is set to an +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 @@ -1340,7 +1340,7 @@ By default the output of the overrides command is hidden. If the overrides comma It is also possible to write messages from your script to a log file that is collected when the job completes or fails. The log file must be created in a specific location and following a naming convention. -Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during normal running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. +Adding some basic logging to your overrides script is useful in case the script fails unexpectedly during standard running of the job. The log file is automatically included as an artifact of the job, allowing you to download it after the job has finished. Following our example, we provided `renew_token.py` in the environment variable `DAST_API_OVERRIDES_CMD`. Notice two things in the script: @@ -1449,7 +1449,7 @@ logging.info("Override file has been updated") # end ``` -In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `DAST_API_PRE_SCRIPT` is set to a script that will install the dependencies of your overrides command. +In the overrides command example, the Python script depends on the `backoff` library. To make sure the library is installed before executing the Python script, the `DAST_API_PRE_SCRIPT` is set to a script that installs the dependencies of your overrides command. As for example, the following script `user-pre-scan-set-up.sh` ```shell @@ -1495,7 +1495,7 @@ In the previous sample, you could use the script `user-pre-scan-set-up.sh` to al The request headers feature lets you specify fixed values for the headers during the scan session. For example, you can use the configuration variable `DAST_API_REQUEST_HEADERS` to set a fixed value in the `Cache-Control` header. If the headers you need to set include sensitive values like the `Authorization` header, use the [masked variable](../../../ci/variables/index.md#mask-a-cicd-variable) feature along with the [variable `DAST_API_REQUEST_HEADERS_BASE64`](#base64). -Note that if the `Authorization` header or any other header needs to get updated while the scan is in progress, consider using the [overrides](#overrides) feature. +If the `Authorization` header or any other header needs to get updated while the scan is in progress, consider using the [overrides](#overrides) feature. The variable `DAST_API_REQUEST_HEADERS` lets you specify a comma-separated (`,`) list of headers. These headers are included on each request that the scanner performs. Each header entry in the list consists of a name followed by a colon (`:`) and then by its value. Whitespace before the key or value is ignored. For example, to declare a header name `Cache-Control` with the value `max-age=604800`, the header entry is `Cache-Control: max-age=604800`. To use two headers, `Cache-Control: max-age=604800` and `Age: 100`, set `DAST_API_REQUEST_HEADERS` variable to `Cache-Control: max-age=604800, Age: 100`. @@ -1606,7 +1606,7 @@ variables: While testing an API you may might want to exclude a parameter (query string, header, or body element) from testing. This may be needed because a parameter always causes a failure, slows down testing, or for other reasons. To exclude parameters, you can set one of the following variables: `DAST_API_EXCLUDE_PARAMETER_ENV` or `DAST_API_EXCLUDE_PARAMETER_FILE`. -The `DAST_API_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and will not often change. Another option is the variable `DAST_API_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime with a pre-script using `DAST_API_PRE_SCRIPT`. +The `DAST_API_EXCLUDE_PARAMETER_ENV` allows providing a JSON string containing excluded parameters. This is a good option if the JSON is short and does not change often. Another option is the variable `DAST_API_EXCLUDE_PARAMETER_FILE`. This variable is set to a file path that can be checked into the repository, created by another job as an artifact, or generated at runtime with a pre-script using `DAST_API_PRE_SCRIPT`. #### Exclude parameters using a JSON document @@ -1833,7 +1833,7 @@ The `dast-api-exclude-parameters.json` is a JSON document that follows the struc > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357195) in GitLab 14.10. -As an alternative to excluding by paths, you can filter by any other component in the URL by using the `DAST_API_EXCLUDE_URLS` CI/CD variable. This variable can be set in your `.gitlab-ci.yml` file. The variable can store multiple values, separated by commas (`,`). Each value is a regular expression. Because each entry is a regular expression, an entry like `.*` will exclude all URLs because it is a regular expression that matches everything. +As an alternative to excluding by paths, you can filter by any other component in the URL by using the `DAST_API_EXCLUDE_URLS` CI/CD variable. This variable can be set in your `.gitlab-ci.yml` file. The variable can store multiple values, separated by commas (`,`). Each value is a regular expression. Because each entry is a regular expression, an entry like `.*` excludes all URLs because it is a regular expression that matches everything. In your job output you can check if any URLs matched any provided regular expression from `DAST_API_EXCLUDE_URLS`. Matching operations are listed in the **Excluded Operations** section. Operations listed in the **Excluded Operations** should not be listed in the **Tested Operations** section. For example the following portion of a job output: @@ -1888,7 +1888,7 @@ variables: ##### Excluding two URLs and their child resources -In order to exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: +To exclude the URLs: `http://target/api/buy` and `http://target/api/sell`, and their child resources. To provide multiple URLs we use the `,` character as follows: ```yaml stages: @@ -1905,7 +1905,7 @@ variables: ##### Excluding URL using regular expressions -In order to exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. +To exclude exactly `https://target/api/v1/user/create` and `https://target/api/v2/user/create` or any other version (`v3`,`v4`, and more). We could use `https://target/api/v.*/user/create$`, in the previous regular expression `.` indicates any character and `*` indicates zero or more times, additionally `$` indicates that the URL should end there. ```yaml stages: @@ -1922,7 +1922,7 @@ variables: ## Running your first scan -When configured correctly, a CI/CD pipeline contains a `dast` stage and an `dast_api` job. The job only fails when an invalid configuration is provided. During normal operation, the job always succeeds even if vulnerabilities are identified during testing. +When configured correctly, a CI/CD pipeline contains a `dast` stage and an `dast_api` job. The job only fails when an invalid configuration is provided. During typical operation, the job always succeeds even if vulnerabilities are identified during testing. Vulnerabilities are displayed on the **Security** pipeline tab with the suite name. When testing against the repositories default branch, the DAST API vulnerabilities are also shown on the Security & Compliance's Vulnerability Report page. @@ -1941,7 +1941,7 @@ Follow these steps to view details of a vulnerability: 1. You can view vulnerabilities in a project, or a merge request: - - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + - In a project, go to the project's **Security & Compliance > Vulnerability Report** page. This page shows all vulnerabilities from the default branch only. - In a merge request, go the merge request's **Security** section and select the **Expand** button. DAST API vulnerabilities are available in a section labeled @@ -1957,7 +1957,7 @@ Follow these steps to view details of a vulnerability: | Method | HTTP method used to detect the vulnerability. | | URL | URL at which the vulnerability was detected. | | Request | The HTTP request that caused the vulnerability. | - | Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | + | Unmodified Response | Response from an unmodified request. This is what a typical working response looks like.| | Actual Response | Response received from test request. | | Evidence | How we determined a vulnerability occurred. | | Identifiers | The DAST API check used to find this vulnerability. | @@ -2274,7 +2274,7 @@ dast_api_v2: In the case of one or two slow operations, the team might decide to skip testing the operations, or exclude them from feature branch tests, but include them for default branch tests. Excluding the operation is done using the `DAST_API_EXCLUDE_PATHS` configuration [variable as explained in this section.](#exclude-paths) -In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `DAST_API_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `dast_api` job and creates two new jobs `dast_api_main` and `dast_api_branch`. The `dast_api_branch` is set up to exclude the long operation and only run on non-default branches (e.g. feature branches). The `dast_api_main` branch is set up to only execute on the default branch (`main` in this example). The `dast_api_branch` jobs run faster, allowing for quick development cycles, while the `dast_api_main` job which only runs on default branch builds, takes longer to run. +In this example, we have an operation that returns a large amount of data. The operation is `GET http://target:7777/api/large_response_json`. To exclude it we provide the `DAST_API_EXCLUDE_PATHS` configuration variable with the path portion of our operation URL `/api/large_response_json`. Our configuration disables the main `dast_api` job and creates two new jobs `dast_api_main` and `dast_api_branch`. The `dast_api_branch` is set up to exclude the long operation and only run on non-default branches (for example, feature branches). The `dast_api_main` branch is set up to only execute on the default branch (`main` in this example). The `dast_api_branch` jobs run faster, allowing for quick development cycles, while the `dast_api_main` job which only runs on default branch builds, takes longer to run. To verify the operation is excluded, run the DAST API job and review the job console output. It includes a list of included and excluded operations at the end of the test. @@ -2368,7 +2368,7 @@ The DAST API engine outputs an error message when it cannot establish a connecti **Solution** -- Remove the `DAST_API_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the DAST API CI/CD template. We recommend this method instead of manually setting a value. +- Remove the `DAST_API_API` variable from the `.gitlab-ci.yml` file. The value inherits from the DAST API CI/CD template. We recommend this method instead of manually setting a value. - If removing the variable is not possible, check to see if this value has changed in the latest version of the [DAST API CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. ### `Failed to start session with scanner. Please retry, and if the problem persists reach out to support.` @@ -2412,9 +2412,9 @@ Once you have confirmed the issue was produced because the port was already take The DAST API engine outputs an error message when it cannot determine the target API after inspecting the OpenAPI document. This error message is shown when the target API has not been set in the `.gitlab-ci.yml` file, it is not available in the `environment_url.txt` file, and it could not be computed using the OpenAPI document. -There is a order of precedence in which the DAST API engine tries to get the target API when checking the different sources. First, it will try to use the `DAST_API_TARGET_URL`. If the environment variable has not been set, then the DAST API engine will attempt to use the `environment_url.txt` file. If there is no file `environment_url.txt`, then the DAST API engine will use the OpenAPI document contents and the URL provided in `DAST_API_OPENAPI` (if a URL is provided) to try to compute the target API. +There is a order of precedence in which the DAST API engine tries to get the target API when checking the different sources. First, it tries to use the `DAST_API_TARGET_URL`. If the environment variable has not been set, then the DAST API engine attempts to use the `environment_url.txt` file. If there is no file `environment_url.txt`, then the DAST API engine uses the OpenAPI document contents and the URL provided in `DAST_API_OPENAPI` (if a URL is provided) to try to compute the target API. -The best-suited solution will depend on whether or not your target API changes for each deployment. In static environments, the target API is the same for each deployment, in this case refer to the [static environment solution](#static-environment-solution). If the target API changes for each deployment a [dynamic environment solution](#dynamic-environment-solutions) should be applied. +The best-suited solution depends on whether or not your target API changes for each deployment. In static environments, the target API is the same for each deployment, in this case refer to the [static environment solution](#static-environment-solution). If the target API changes for each deployment a [dynamic environment solution](#dynamic-environment-solutions) should be applied. #### Static environment solution @@ -2498,7 +2498,7 @@ variables: ### `No operation in the OpenAPI document is consuming any supported media type` -DAST API uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error will be thrown. +DAST API uses the specified media types in the OpenAPI document to generate requests. If no request can be created due to the lack of supported media types, then an error is thrown. **Error message** diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 9fffdec2612..b86d98471ac 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -81,7 +81,7 @@ You can download your project's full list of dependencies and their details in ### In the UI -You can download your project's list of dependencies and their details in JSON format by selecting the **Export** button. Note that the dependency list only shows the results of the last successful pipeline to run on the default branch. +You can download your project's list of dependencies and their details in JSON format by selecting the **Export** button. The dependency list only shows the results of the last successful pipeline to run on the default branch. ### Using the API diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index d13c4cecdf4..4feac0cb5e6 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -100,7 +100,7 @@ The following table lists the data available for the Gemnasium analyzer. | Property \ Tool | Gemnasium | |---------------------------------------|:------------------:| -| Severity | 𐄂 | +| Severity | ✓ | | Title | ✓ | | File | ✓ | | Start line | 𐄂 | diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 8106201cb99..579dd4dfc4f 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -59,7 +59,7 @@ possible, we encourage you to use all of our security scanning tools: Turning this variable on can result in some duplicate findings, as we do not yet de-duplicate results between Container Scanning and Dependency Scanning. For more details, efforts to de-duplicate these findings can be tracked in - [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/348655). + [this epic](https://gitlab.com/groups/gitlab-org/-/epics/8026). The following table summarizes which types of dependencies each scanning tool can detect: @@ -155,23 +155,14 @@ table.supported-languages ul { </thead> <tbody> <tr> - <td>Ruby</td> - <td>All versions</td> - <td><a href="https://bundler.io/">Bundler</a></td> - <td> - <ul> - <li><code>Gemfile.lock</code></li> - <li><code>gems.locked</code></li> - </ul> - </td> - <td>Y</td> + <td>.NET</td> + <td rowspan="2">All versions</td> + <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> + <td rowspan="2"><a href="https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file"><code>packages.lock.json</code></a></td> + <td rowspan="2">Y</td> </tr> <tr> - <td>PHP</td> - <td>All versions</td> - <td><a href="https://getcomposer.org/">Composer</a></td> - <td><code>composer.lock</code></td> - <td>Y</td> + <td>C#</td> </tr> <tr> <td>C</td> @@ -226,7 +217,7 @@ table.supported-languages ul { <td><a href="https://www.npmjs.com/">npm</a></td> <td> <ul> - <li><code>package-lock.json</code><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-3">3</a></b></sup></li> + <li><code>package-lock.json</code></li> <li><code>npm-shrinkwrap.json</code></li> </ul> </td> @@ -239,14 +230,11 @@ table.supported-languages ul { <td>Y</td> </tr> <tr> - <td>.NET</td> - <td rowspan="2">All versions</td> - <td rowspan="2"><a href="https://www.nuget.org/">NuGet</a></td> - <td rowspan="2"><a href="https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file"><code>packages.lock.json</code></a></td> - <td rowspan="2">Y</td> - </tr> - <tr> - <td>C#</td> + <td>PHP</td> + <td>All versions</td> + <td><a href="https://getcomposer.org/">Composer</a></td> + <td><code>composer.lock</code></td> + <td>Y</td> </tr> <tr> <td rowspan="4">Python</td> @@ -282,6 +270,18 @@ table.supported-languages ul { <td>N</td> </tr> <tr> + <td>Ruby</td> + <td>All versions</td> + <td><a href="https://bundler.io/">Bundler</a></td> + <td> + <ul> + <li><code>Gemfile.lock</code></li> + <li><code>gems.locked</code></li> + </ul> + </td> + <td>Y</td> + </tr> + <tr> <td>Scala</td> <td>All versions</td> <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-6">6</a></b></sup></td> @@ -307,16 +307,10 @@ table.supported-languages ul { </p> </li> <li> - <a id="notes-regarding-supported-languages-and-package-managers-3"></a> - <p> - npm is supported for <code>lockfileVersion = 1</code>, <code>lockfileVersion = 2</code>, and <code>lockfileVersion = 3</code>. Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. - </p> - </li> - <li> <a id="notes-regarding-supported-languages-and-package-managers-4"></a> <p> The presence of a <code>Pipfile.lock</code> file alone will <i>not</i> trigger the analyzer; the presence of a <code>Pipfile</code> is - still required in order for the analyzer to be executed. However, if a <code>Pipfile.lock</code> file is found, it will be used by + still required in order for the analyzer to be executed. However, if a <code>Pipfile.lock</code> file is found, it is used by <code>Gemnasium</code> to scan the exact package versions listed in this file. </p> <p> @@ -360,7 +354,7 @@ The following package managers use lockfiles that GitLab analyzers are capable o | Conan | 0.4 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/c-conan/default/conan.lock#L38) | | Go | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/go-modules/gosum/default/go.sum) <sup><strong><a href="#notes-regarding-parsing-lockfiles-1">1</a></strong></sup> | | NuGet | v1 | [4.9](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/csharp-nuget-dotnetcore/default/src/web.api/packages.lock.json#L2) | -| npm | v1, v2, v3 | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | +| npm | v1, v2, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup> | [6.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/default/package-lock.json#L4), [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-npm/lockfileVersion2/package-lock.json#L4), [9.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/npm/fixtures/lockfile-v3/simple/package-lock.json#L4) | | yarn | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/default/yarn.lock#L2) | | Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock) | @@ -369,10 +363,16 @@ The following package managers use lockfiles that GitLab analyzers are capable o <li> <a id="notes-regarding-parsing-lockfiles-1"></a> <p> - Dependency Scanning will only parse <code>go.sum</code> if it's unable to generate the build list + Dependency Scanning only parses <code>go.sum</code> if it's unable to generate the build list used by the Go project. </p> </li> + <li> + <a id="notes-regarding-parsing-lockfiles-2"></a> + <p> + Support for <code>lockfileVersion = 3</code> was <a href="https://gitlab.com/gitlab-org/gitlab/-/issues/365176">introduced</a> in GitLab 15.7. + </p> + </li> </ol> <!-- markdownlint-enable MD044 --> @@ -431,7 +431,7 @@ To support the following package managers, the GitLab analyzers proceed in two s <li> <a id="exported-dependency-information-notes-3"></a> <p> - This test confirms that if a <code>Pipfile.lock</code> file is found, it will be used by <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a> to scan the exact package versions listed in this file. + This test confirms that if a <code>Pipfile.lock</code> file is found, it is used by <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a> to scan the exact package versions listed in this file. </p> </li> <li> @@ -659,7 +659,7 @@ The following variables are used for configuring specific analyzers (used for a #### Other variables -The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they will work. This is a large list, many of which we may be unaware of, and as such is not documented. +The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they do work. This is a large list, many of which we may be unaware of, and as such is not documented. For example, to pass the non-GitLab environment variable `HTTPS_PROXY` to all Dependency Scanning jobs, set it as a [CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file) @@ -678,7 +678,7 @@ dependency_scanning: HTTPS_PROXY: $HTTPS_PROXY ``` -As we have not tested all variables you may find some will work and others will not. +As we have not tested all variables you may find some do work and others do not. If one does not work and you need it we suggest [submitting a feature request](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal%20-%20detailed&issue[title]=Docs%20feedback%20-%20feature%20proposal:%20Write%20your%20title) or [contributing to the code](../../../development/index.md) to enable it to be used. @@ -966,7 +966,7 @@ Here are the requirements for using dependency scanning in an offline environmen This advisory database is constantly being updated, so you must periodically sync your local copy with GitLab. -Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -1262,7 +1262,7 @@ analyzers, edit your `.gitlab-ci.yml` file and either: [our current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml#L18). - If you hardcoded the `DS_ANALYZER_IMAGE` variable directly, change it to match the latest line as found in our [current Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml). - The line number will vary depending on which scanning job you edited. + The line number varies depending on which scanning job you edited. For example, currently the `gemnasium-maven-dependency_scanning` job pulls the latest `gemnasium-maven` Docker image because `DS_ANALYZER_IMAGE` is set to @@ -1274,7 +1274,7 @@ Support for [2to3](https://docs.python.org/3/library/2to3.html) was [removed](https://setuptools.pypa.io/en/latest/history.html#v58-0-0) in `setuptools` version `v58.0.0`. Dependency Scanning (running `python 3.9`) uses `setuptools` version `58.1.0+`, which doesn't support `2to3`. Therefore, a `setuptools` dependency relying on -`lib2to3` will fail with this message: +`lib2to3` fails with this message: ```plaintext error in <dependency name> setup command: use_2to3 is invalid @@ -1313,12 +1313,12 @@ To avoid this error, follow [Poetry's configuration advice](https://python-poetr ### Error: Project has `<number>` unresolved dependencies -The error message `Project has <number> unresolved dependencies` indicates a dependency resolution problem caused by your `gradle.build` or `gradle.build.kts` file. In the current release, `gemnasium-maven` cannot continue processing when an unresolved dependency is encountered. However, There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337083) to allow `gemnasium-maven` to recover from unresolved dependency errors and produce a dependency graph. Until this issue has been resolved, you'll need to consult the [Gradle dependency resolution docs](https://docs.gradle.org/current/userguide/dependency_resolution.html) for details on how to fix your `gradle.build` file. +The error message `Project has <number> unresolved dependencies` indicates a dependency resolution problem caused by your `gradle.build` or `gradle.build.kts` file. In the current release, `gemnasium-maven` cannot continue processing when an unresolved dependency is encountered. However, There is an [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/337083) to allow `gemnasium-maven` to recover from unresolved dependency errors and produce a dependency graph. Until this issue has been resolved, consult the [Gradle dependency resolution docs](https://docs.gradle.org/current/userguide/dependency_resolution.html) for details on how to fix your `gradle.build` file. ### Setting build constraints when scanning Go projects Dependency scanning runs within a `linux/amd64` container. As a result, the build list generated -for a Go project will contain dependencies that are compatible with this environment. If your deployment environment is not +for a Go project contains dependencies that are compatible with this environment. If your deployment environment is not `linux/amd64`, the final list of dependencies might contain additional incompatible modules. The dependency list might also omit modules that are only compatible with your deployment environment. To prevent this issue, you can configure the build process to target the operating system and architecture of the deployment diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md index 5774bf940b0..c1524c4b517 100644 --- a/doc/user/application_security/get-started-security.md +++ b/doc/user/application_security/get-started-security.md @@ -9,14 +9,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Adopting GitLab application security](https://www.youtube.com/watch?v=5QlxkiKR04k). -The following steps will help you get the most from GitLab application security tools. These steps are a recommended order of operations. You can choose to implement capabilities in a different order or omit features that do not apply to your specific needs. +The following steps help you get the most from GitLab application security tools. These steps are a recommended order of operations. You can choose to implement capabilities in a different order or omit features that do not apply to your specific needs. 1. Enable [Secret Detection](secret_detection/index.md) and [Dependency Scanning](dependency_scanning/index.md) to identify any leaked secrets and vulnerable packages in your codebase. - For all security scanners, enable them by updating your [`.gitlab-ci.yml`](../../ci/yaml/gitlab_ci_yaml.md) directly on your `default` branch. This creates a baseline scan of your `default` branch, which is necessary for feature branch scans to be compared against. This allows [merge requests](../project/merge_requests/index.md) - to display only newly-introduced vulnerabilities. Otherwise, merge requests will display every + to display only newly-introduced vulnerabilities. Otherwise, merge requests display every vulnerability in the branch, regardless of whether it was introduced by a change in the branch. - If you are after simplicity, enable only Secret Detection first. It only has one analyzer, no build requirements, and relatively simple findings: is this a secret or not? @@ -27,8 +27,9 @@ The following steps will help you get the most from GitLab application security 1. Consider creating [labels](../project/labels.md) and [issue boards](../project/issue_board.md) to help manage issues created from vulnerabilities. Issue boards allow all stakeholders to have a common view of all issues and track remediation progress. -1. Use [scheduled pipelines](../../ci/pipelines/schedules.md#scheduled-pipelines) to regularly scan important branches such as `default` or those used for maintenance releases. - - Running regular dependency and [container scans](container_scanning/index.md) will surface newly-discovered vulnerabilities that already exist in your repository. +1. Enforce scheduled security scanning jobs by using a [scan execution policy](policies/scan-execution-policies.md). + - These scheduled jobs run independently from any other security scans you may have defined in a compliance framework pipeline or in the project's `.gitlab-ci.yml` file. + - Running regular dependency and [container scans](container_scanning/index.md) surface newly-discovered vulnerabilities that already exist in your repository. - Scheduled scans are most useful for projects or important branches with low development activity where pipeline scans are infrequent. 1. Create a [scan result policy](policies/index.md) to limit new vulnerabilities from being merged into your `default` branch. @@ -36,7 +37,7 @@ The following steps will help you get the most from GitLab application security remediating existing vulnerabilities and preventing the introduction of new ones. 1. Enable other scan types such as [SAST](sast/index.md), [DAST](dast/index.md), [Fuzz testing](coverage_fuzzing/index.md), or [Container Scanning](container_scanning/index.md). -1. Use [Compliance Pipelines](../group/compliance_frameworks.md#configure-a-compliance-pipeline) +1. Use [Compliance Pipelines](../group/compliance_frameworks.md#compliance-pipelines) or [Scan Execution Policies](policies/scan-execution-policies.md) to enforce required scan types and ensure separation of duties between security and engineering. 1. Consider enabling [Review Apps](../../development/testing_guide/review_apps.md) to allow for DAST diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 24448dc9668..c2f1257f989 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -16,7 +16,7 @@ IaC Scanning supports configuration files for Terraform, Ansible, AWS CloudForma IaC Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. -We recommend a minimum of 4GB RAM to ensure consistent performance. +We recommend a minimum of 4 GB RAM to ensure consistent performance. To run IaC Scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or @@ -24,7 +24,7 @@ To run IaC Scanning jobs, by default, you need GitLab Runner with the If you're using the shared runners on GitLab.com, this is enabled by default. WARNING: -Our IaC Scanning jobs require a Linux/amd64 container type. Windows containers are not supported. +GitLab IaC Scanning analyzers don't support running on Windows or on any CPU architectures other than amd64. WARNING: If you use your own runners, make sure the Docker version installed @@ -222,13 +222,13 @@ To override the automatic update behavior, set the `SAST_ANALYZER_IMAGE_TAG` CI/ in your CI/CD configuration file after you include the [`SAST-IaC.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST-IaC.gitlab-ci.yml). Only set this variable in a specific job. -If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. +If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set is used for other SAST analyzers. You can set the tag to: -- A major version, like `3`. Your pipelines will use any minor or patch updates that are released within this major version. -- A minor version, like `3.7`. Your pipelines will use any patch updates that are released within this minor version. -- A patch version, like `3.7.0`. Your pipelines won't receive any updates. +- A major version, like `3`. Your pipelines use any minor or patch updates that are released within this major version. +- A minor version, like `3.7`. Your pipelines use any patch updates that are released within this minor version. +- A patch version, like `3.7.0`. Your pipelines don't receive any updates. This example uses a specific minor version of the `KICS` analyzer: @@ -241,6 +241,19 @@ kics-iac-sast: SAST_ANALYZER_IMAGE_TAG: "3.1" ``` +## Automatic vulnerability resolution + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`. Enabled by default on GitLab.com; disabled by default in self-managed. On GitLab.com, [contact Support](https://about.gitlab.com/support/) if you need to disable the flag for your project. + +To help you focus on the vulnerabilities that are still relevant, GitLab IaC Scanning automatically [resolves](../vulnerabilities/index.md#vulnerability-status-values) vulnerabilities when: + +- You [disable a predefined rule](#disable-predefined-analyzer-rules). +- We remove a rule from the default ruleset. + +The Vulnerability Management system leaves a comment on automatically-resolved vulnerabilities so you still have a historical record of the vulnerability. + +If you re-enable the rule later, the findings are reopened for triage. + ## Reports JSON format The IaC tool emits a JSON report file in the existing SAST report format. For more information, see the @@ -269,3 +282,8 @@ be ineffective or false positives, and the findings are marked as `No longer det - In GitLab 15.3, [secret detection in the KICS SAST IaC scanner was disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/346181), so IaC findings in the "Passwords and Secrets" family show as `No longer detected`. + +### `exec /bin/sh: exec format error` message in job log + +The GitLab IaC Scanning analyzer [only supports](#requirements) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index a623b819b08..492b200d22b 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -4,7 +4,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/product/ux/technical-writing/#assignments --- -# Secure your application **(ULTIMATE)** +# Application security **(ULTIMATE)** GitLab can check your application for security vulnerabilities including: @@ -104,10 +104,10 @@ The following vulnerability scanners and their databases are regularly updated: | [Container Scanning](container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. For more details, see [Vulnerabilities database update](container_scanning/index.md#vulnerabilities-database). | | [Dependency Scanning](dependency_scanning/index.md) | Relies on the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db). It is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | -| [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab wraps](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | +| [Static Application Security Testing (SAST)](sast/index.md) | The source of scan rules depends on which [analyzer](sast/analyzers.md) is used for each [supported programming language](sast/index.md#supported-languages-and-frameworks). GitLab maintains a ruleset for the Semgrep-based analyzer and updates it regularly based on internal research and user feedback. For other analyzers, the ruleset is sourced from the upstream open-source scanner. Each analyzer is updated at least once per month if a relevant update is available. | In versions of GitLab that use the same major version of the analyzer, you do not have to update -GitLab to benefit from the latest vulnerabilities definitions. The security tools are released as +them to benefit from the latest vulnerabilities definitions. The security tools are released as Docker images. The vendored job definitions that enable them use major release tags according to [semantic versioning](https://semver.org/). Each new release of the tools overrides these tags. Although in a major analyzer version you automatically get the latest versions of the scanning @@ -130,7 +130,7 @@ While you cannot directly customize Auto DevOps, you can [include the Auto DevOp ## Security scanning without Auto DevOps -To enable all GitLab security scanning tools, with the option of customizing settings, add the +To enable all GitLab security scanning tools with the option of customizing settings, add the GitLab CI/CD templates to your `.gitlab-ci.yml` file. WARNING: @@ -164,7 +164,7 @@ variables: By default, GitLab security scanners use `registry.gitlab.com/security-products` as the base address for Docker images. You can override this for most scanners by setting the CI/CD variable -`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. +`SECURE_ANALYZERS_PREFIX` to another location. This affects all scanners at once. The [Container Scanning](container_scanning/index.md) analyzer is an exception, and it does not use the `SECURE_ANALYZERS_PREFIX` variable. To override its Docker image, see @@ -179,7 +179,7 @@ you must reference the [`latest` templates](../../development/cicd/templates.md) All `latest` security templates support merge request pipelines. -For example, to run both SAST and Dependency Scanning: +For example, to run both SAST and Dependency Scanning, the following template is used: ```yaml include: @@ -205,7 +205,7 @@ that rely on this scan data only show results from pipelines on the default bran Our language and package manager specific jobs attempt to assess which analyzers they should run for your project so that you can do less configuration. -If you want to override this to increase the pipeline speed you may choose which analyzers to exclude if you know they are not applicable (languages or package managers not contained in your project) by following variable customization directions for that specific tool. +If you want to override this to increase the pipeline speed, you may choose which analyzers to exclude if you know they are not applicable (languages or package managers not contained in your project) by following variable customization directions for that specific tool. ### Secure job status @@ -242,7 +242,7 @@ reports are available to download. To download a report, select A merge request contains a security widget which displays a summary of the new results. New results are determined by comparing the findings of the merge request against the findings of the most recent completed pipeline (`success`, `failed`, `canceled` or `skipped`) for the latest commit in the target branch. -If security scans have not run for the most recent completed pipeline in the target branch there is no base for comparison. The vulnerabilities from the merge request findings will be listed as new in the merge request security widget. We recommend you run a scan of the `default` (target) branch before enabling feature branch scans for your developers. +If security scans have not run for the most recent completed pipeline in the target branch there is no base for comparison. The vulnerabilities from the merge request findings are listed as new in the merge request security widget. We recommend you run a scan of the `default` (target) branch before enabling feature branch scans for your developers. The merge request security widget displays only a subset of the vulnerabilities in the generated JSON artifact because it contains both new and existing findings. @@ -280,7 +280,7 @@ security issues: - A security vulnerability. For more details, read [Scan result policies](policies/scan-result-policies.md). - A software license compliance violation. For more details, read - [Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). + [Enabling license approvals within a project](../compliance/license_check_rules.md#enabling-license-approvals-within-a-project). ## Using private Maven repositories @@ -397,7 +397,7 @@ To fix this issue, you can either: - echo "custom job" ``` -Learn more on overriding security jobs: +For more information about overriding security jobs, see: - [Overriding SAST jobs](sast/index.md#overriding-sast-jobs). - [Overriding Dependency Scanning jobs](dependency_scanning/index.md#overriding-dependency-scanning-jobs). @@ -443,9 +443,9 @@ You can always find supported and deprecated schema versions in the [source code You can interact with the results of the security scanning tools in several locations: - [Scan information in merge requests](#view-security-scan-information-in-merge-requests) -- [Project Security Dashboard](security_dashboard/index.md) +- [Project Security Dashboard](security_dashboard/index.md#view-vulnerabilities-over-time-for-a-project) - [Security pipeline tab](security_dashboard/index.md) -- [Group Security Dashboard](security_dashboard/index.md) +- [Group Security Dashboard](security_dashboard/index.md#view-vulnerabilities-over-time-for-a-group) - [Security Center](security_dashboard/index.md#security-center) - [Vulnerability Report](vulnerability_report/index.md) - [Vulnerability Pages](vulnerabilities/index.md) @@ -487,7 +487,7 @@ Security and compliance teams must ensure that security scans: GitLab provides two methods of accomplishing this, each with advantages and disadvantages. -- [Compliance framework pipelines](../group/compliance_frameworks.md#configure-a-compliance-pipeline) +- [Compliance framework pipelines](../group/compliance_frameworks.md#compliance-pipelines) are recommended when: - Scan execution enforcement is required for any scanner that uses a GitLab template, such as SAST IaC, DAST, Dependency Scanning, @@ -516,7 +516,7 @@ Additional details about the differences between the two solutions are outlined | ------ | ------ | ------ | | **Flexibility** | Supports anything that can be done in a CI file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, Secret Detection, Dependency Scanning, and Container Scanning scans are supported. | | **Usability** | Requires knowledge of CI YAML. | Follows a `rules` and `actions`-based YAML structure. | -| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are normally available to the CI job. | +| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `.gitlab-ci.yml` file. To include the project's `.gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. All jobs can be customized as part of the security policy itself with the same variables that are usually available to the CI job. | | **Schedulable** | Can be scheduled through a scheduled pipeline on the group. | Can be scheduled natively through the policy configuration itself. | | **Separation of Duties** | Only group owners can create compliance framework labels. Only project owners can apply compliance framework labels to projects. The ability to make or approve changes to the compliance pipeline definition is limited to individuals who are explicitly given access to the project that contains the compliance pipeline. | Only project owners can define a linked security policy project. The ability to make or approve changes to security policies is limited to individuals who are explicitly given access to the security policy project. | | **Ability to apply one standard to multiple projects** | The same compliance framework label can be applied to multiple projects inside a group. | The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group. | @@ -602,7 +602,7 @@ To fix this issue, you must either: - [Transition your `only/except` syntax to `rules`](#transitioning-your-onlyexcept-syntax-to-rules). - (Temporarily) [Pin your templates to the deprecated versions](#pin-your-templates-to-the-deprecated-versions) -[Learn more on overriding SAST jobs](sast/index.md#overriding-sast-jobs). +For more information, see [Overriding SAST jobs](sast/index.md#overriding-sast-jobs). #### Transitioning your `only/except` syntax to `rules` @@ -664,7 +664,7 @@ spotbugs-sast: - if: $CI_COMMIT_TAG == null ``` -[Learn more on the usage of `rules`](../../ci/yaml/index.md#rules). +For more information, see [`rules`](../../ci/yaml/index.md#rules). #### Pin your templates to the deprecated versions @@ -702,7 +702,7 @@ The `sast` or `dependency_scanning` stanzas can be used to make changes to all S such as changing `variables` or the `stage`, but they cannot be used to define shared `rules`. There [is an issue open to improve extendability](https://gitlab.com/gitlab-org/gitlab/-/issues/218444). -Please upvote the issue to help with prioritization, and +You can upvote the issue to help with prioritization, and [contributions are welcomed](https://about.gitlab.com/community/contribute/). ### Empty Vulnerability Report, Dependency List, License list pages @@ -710,9 +710,9 @@ Please upvote the issue to help with prioritization, and If the pipeline has manual steps with a job that has the `allow_failure: false` option, and this job is not finished, GitLab can't populate listed pages with the data from security reports. In this case, [the Vulnerability Report](vulnerability_report/index.md), [the Dependency List](dependency_list/index.md), -and [the License list](../compliance/license_compliance/index.md#license-list) pages will be empty. +and [the License list](../compliance/license_list.md) pages are empty. These security pages can be populated by running the jobs from the manual step of the pipeline. There is [an issue open to handle this scenario](https://gitlab.com/gitlab-org/gitlab/-/issues/346843). -Please upvote the issue to help with prioritization, and +You can upvote the issue to help with prioritization, and [contributions are welcomed](https://about.gitlab.com/community/contribute/). diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 6976956758d..5a075bf731b 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -234,6 +234,6 @@ Once these steps are complete, GitLab has local copies of the Secure analyzers a them instead of an Internet-hosted container image. This allows you to run Secure in AutoDevOps in an offline environment. -Note that these steps are specific to GitLab Secure with AutoDevOps. Using other stages with +These steps are specific to GitLab Secure with AutoDevOps. Using other stages with AutoDevOps may require other steps covered in the [Auto DevOps documentation](../../../topics/autodevops/index.md). diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index c9c48c0c926..26c7e1d9c77 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -11,21 +11,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Operational container scanning [introduced](https://gitlab.com/groups/gitlab-org/-/epics/3410) in GitLab 15.5 Group, subgroup, or project owners can use scan execution policies to require that security scans run on a specified -schedule or with the project (or multiple projects if the policy is defined at a group or subgroup level) pipeline. Required scans are injected into the CI pipeline as new jobs -with a long, random job name. In the unlikely event of a job name collision, the security policy job overwrites -any pre-existing job in the pipeline. If a policy is created at the group-level, it will apply to every child -project or subgroup. A group-level policy cannot be edited from a child project or subgroup. +schedule or with the project pipeline. The security scan runs with multiple project pipelines if you define the policy +at a group or subgroup level. GitLab injects the required scans into the CI pipeline as new jobs. In the event +of a job name collision, GitLab adds a dash and a number to the job name. GitLab increments the number until the name +no longer conflicts with existing job names. If you create a policy at the group level, it applies to every child project +or subgroup. You cannot edit a group-level policy from a child project or subgroup. -This feature has some overlap with [compliance framework pipelines](../../group/compliance_frameworks.md#configure-a-compliance-pipeline), +This feature has some overlap with [compliance framework pipelines](../../group/compliance_frameworks.md#compliance-pipelines), as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). For details on the similarities and differences between these features, see [Enforce scan execution](../index.md#enforce-scan-execution). NOTE: -Policy jobs are created in the `test` stage of the pipeline. If you modify the default pipeline +Policy jobs for scans other than DAST scans are created in the `test` stage of the pipeline. If you modify the default pipeline [`stages`](../../../ci/yaml/index.md#stages), -you must ensure that the `test` stage exists in the list. Otherwise, the pipeline fails to run and -an error appears that states `chosen stage does not exist`. +to remove the `test` stage, jobs will run in the `scan-policies` stage instead. This stage is injected into the CI pipeline at evaluation time if it doesn't exist. If the `build` stage exists, it is injected just after the `build` stage. If the `build` stage does not exist, it is injected at the beginning of the pipeline. DAST scans always run in the `dast` stage. If this stage does not exist, then a `dast` stage is injected at the end of the pipeline. ## Scan execution policy editor @@ -89,7 +89,7 @@ This rule enforces the defined actions and schedules a scan on the provided date | `type` | `string` | `schedule` | The rule's type. | | `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). This field is required if the `agents` field is not set. | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | -| `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [cluster image scanning](../../clusters/agent/vulnerabilities.md) will run. The object key is the name of the Kubernetes agent configured for your project in GitLab. This field is required if the `branches` field is not set. | +| `agents` | `object` | | The name of the [GitLab agents](../../clusters/agent/index.md) where [Operational Container Scanning](../../clusters/agent/vulnerabilities.md) runs. The object key is the name of the Kubernetes agent configured for your project in GitLab. This field is required if the `branches` field is not set. | GitLab supports the following types of CRON syntax for the `cadence` field: @@ -97,10 +97,10 @@ GitLab supports the following types of CRON syntax for the `cadence` field: - A weekly cadence of once per week on a specified day and at a specified hour, for example: `0 13 * * 0` NOTE: -Other elements of the [CRON syntax]((https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm)) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. +Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. NOTE: -If using the `agents` field, required for `Operational Container Scanning`, the CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod. If not using the `agents` field, the CRON expression is evaluated in standard [UTC](https://www.timeanddate.com/worldclock/timezone/utc) time from GitLab.com. If you have a self-managed GitLab instance and have [changed the server timezone](../../../administration/timezone.md), the CRON expression is evaluated with the new timezone. +If using the `agents` field, required for `Operational Container Scanning`, the CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod. If not using the `agents` field, the CRON expression is evaluated in standard [UTC](https://www.timeanddate.com/worldclock/timezone/utc) time from GitLab.com. If you have a self-managed GitLab instance and have [changed the server time zone](../../../administration/timezone.md), the CRON expression is evaluated with the new time zone. ### `agent` schema @@ -108,7 +108,7 @@ Use this schema to define `agents` objects in the [`schedule` rule type](#schedu | Field | Type | Possible values | Description | |--------------|---------------------|--------------------------|-------------| -| `namespaces` | `array` of `string` | | The namespace that is scanned. If empty, all namespaces will be scanned. | +| `namespaces` | `array` of `string` | | The namespace that is scanned. If empty, all namespaces are scanned. | #### Policy example @@ -129,9 +129,9 @@ Use this schema to define `agents` objects in the [`schedule` rule type](#schedu The keys for a schedule rule are: -- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run +- `cadence` (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans are run - `agents:<agent-name>` (required): The name of the agent to use for scanning -- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces will be scanned. +- `agents:<agent-name>:namespaces` (optional): The Kubernetes namespaces to scan. If omitted, all namespaces are scanned. ## `scan` action type @@ -144,7 +144,7 @@ rule in the defined policy are met. | `site_profile` | `string` | Name of the selected [DAST site profile](../dast/proxy-based.md#site-profile). | The DAST site profile to execute the DAST scan. This field should only be set if `scan` type is `dast`. | | `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/proxy-based.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. This field should only be set if `scan` type is `dast`.| | `variables` | `object` | | A set of CI variables, supplied as an array of `key: value` pairs, to apply and enforce for the selected scan. The `key` is the variable name, with its `value` provided as a string. This parameter supports any variable that the GitLab CI job supports for the specified scan. | -| `tags` | `array` of `string` | | A list of runner tags for the policy. The policy jobs will be run by runner with the specified tags. | +| `tags` | `array` of `string` | | A list of runner tags for the policy. The policy jobs are run by runner with the specified tags. | Note the following: @@ -238,3 +238,14 @@ actions: - scan: secret_detection - scan: container_scanning ``` + +## Avoiding duplicate scans + +Scan execution policies can cause the same type of scanner to run more than once if developers include scan jobs in the project's +`.gitlab-ci.yml` file. This behavior is intentional as scanners can run more than once with different variables and settings. For example, a +developer may want to try running a SAST scan with different variables than the one enforced by the security and compliance team. In +this case, two SAST jobs run in the pipeline, one with the developer's variables and one with the security and compliance team's variables. + +If you want to avoid running duplicate scans, you can either remove the scans from the project's `.gitlab-ci.yml` file or disable your +local jobs by setting `SAST_DISABLED: true`. Disabling jobs this way does not prevent the security jobs defined by scan execution +policies from running. diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 6bf3532f95e..bc74b8bdfb1 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -42,7 +42,7 @@ before the policy changes take effect. The [policy editor](index.md#policy-editor) supports YAML mode and rule mode. NOTE: -Propagating scan result policies created for groups with a large number of projects will take a while to complete. +Propagating scan result policies created for groups with a large number of projects take a while to complete. ## Scan result policies schema @@ -79,10 +79,16 @@ This rule enforces the defined actions based on security scan findings. | `scanners` | `array` of `string` | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. | | `vulnerabilities_allowed` | `integer` | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | `info`, `unknown`, `low`, `medium`, `high`, `critical`| The severity levels for this rule to consider. | -| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities that are both `Detected` or `Dismissed` within the merge request itself where the vulnerabilities do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline, and necessary security scans are complete.<br><br> • Detected<br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | +| `vulnerability_states` | `array` of `string` | `newly_detected`, `detected`, `confirmed`, `resolved`, `dismissed` | All vulnerabilities fall into two categories:<br><br>**Newly Detected Vulnerabilities** - the `newly_detected` policy option covers vulnerabilities identified in the merge request branch itself but that do not currently exist on the default branch. This policy option requires a pipeline to complete before the rule is evaluated so that it knows whether vulnerabilities are newly detected or not. Merge requests are blocked until the pipeline and necessary security scans are complete. The `newly_detected` option considers both of the following statuses:<br><br> • Detected<br> • Dismissed<br><br>**Pre-Existing Vulnerabilities** - these policy options are evaluated immediately and do not require a pipeline complete as they consider only vulnerabilities previously detected in the default branch.<br><br> • `Detected` - the policy looks for vulnerabilities in the detected state.<br> • `Confirmed` - the policy looks for vulnerabilities in the confirmed state.<br> • `Dismissed` - the policy looks for vulnerabilities in the dismissed state.<br> • `Resolved` - the policy looks for vulnerabilities in the resolved state. | ## `license_finding` rule type +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `license_scanning_policies`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `license_scanning_policies`. +On GitLab.com, this feature is not available. + This rule enforces the defined actions based on license findings. | Field | Type | Possible values | Description | @@ -91,7 +97,7 @@ This rule enforces the defined actions based on license findings. | `branches` | `array` of `string` | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. | | `match_on_inclusion` | `boolean` | `true`, `false` | Whether the rule matches inclusion or exclusion of licenses listed in `license_types`. | | `license_types` | `array` of `string` | license types | License types to match on, for example `BSD` or `MIT`. | -| `license_states` | `array` of `string` | `newly_detected`, `detected` | Whether to match newly detected and/or previously detected licenses. | +| `license_states` | `array` of `string` | `newly_detected`, `detected` | Whether to match newly detected and/or previously detected licenses. The `newly_detected` state triggers approval when either a new package is introduced or when a new license for an existing package is detected. | ## `require_approval` action type @@ -110,7 +116,7 @@ the defined policy. Requirements and limitations: - You must add the respective [security scanning tools](../index.md#application-coverage). - Otherwise, scan result policies won't have any effect. + Otherwise, scan result policies do not have any effect. - The maximum number of policies is five. - Each policy can have a maximum of five rules. @@ -199,7 +205,7 @@ It corresponds to a single object from the previous example: ## Example situations where scan result policies require additional approval -There are several situations where the scan result policy will require an additional approval step. For example: +There are several situations where the scan result policy requires an additional approval step. For example: - The number of security jobs is reduced in the working branch and no longer matches the number of security jobs in the target branch. Users can't skip the Scanning Result Policies by removing scanning jobs from the CI configuration. - Someone stops a pipeline security job, and users can't skip the security scan. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index efbbf447845..c8542142830 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -12,7 +12,7 @@ Static Application Security Testing (SAST) uses analyzers to detect vulnerabilities in source code. Each analyzer is a wrapper around a [scanner](../terminology/index.md#scanner), a third-party code analysis tool. The analyzers are published as Docker images that SAST uses to launch dedicated containers for each -analysis. We recommend a minimum of 4GB RAM to ensure consistent performance of the analyzers. +analysis. We recommend a minimum of 4 GB RAM to ensure consistent performance of the analyzers. SAST default images are maintained by GitLab, but you can also integrate your own custom image. @@ -77,8 +77,8 @@ Work to remove language-specific analyzers and replace them with the Semgrep-bas You can choose to disable the other analyzers early and use Semgrep-based scanning for supported languages before the default behavior changes. If you do so: -- You'll enjoy significantly faster scanning, reduced CI minutes usage, and more customizable scanning rules. -- However, vulnerabilities previously reported by language-specific analyzers will be reported again under certain conditions, including if you've dismissed the vulnerabilities before. The system behavior depends on: +- You enjoy significantly faster scanning, reduced CI minutes usage, and more customizable scanning rules. +- However, vulnerabilities previously reported by language-specific analyzers are reported again under certain conditions, including if you've dismissed the vulnerabilities before. The system behavior depends on: - whether you've excluded the Semgrep-based analyzer from running in the past. - which analyzer first discovered the vulnerabilities shown in the project's [Vulnerability Report](../vulnerability_report/index.md). @@ -92,7 +92,7 @@ The Vulnerability Management system automatically moves vulnerabilities from the - For Go, a vulnerability is moved if it has only ever been detected by Gosec in pipelines where Semgrep also detected it. Semgrep coverage for Go was introduced by default into the CI/CD template in GitLab 14.2 (August 2021). - For JavaScript and TypeScript, a vulnerability is moved if it has only ever been detected by ESLint in pipelines where Semgrep also detected it. Semgrep coverage for these languages was introduced into the CI/CD template in GitLab 13.12 (May 2021). -However, you'll see old vulnerabilities re-created based on Semgrep results if: +However, old vulnerabilities re-created based on Semgrep results are visible if: - A vulnerability was created by Bandit or SpotBugs and you disable those analyzers. We only recommend disabling Bandit and SpotBugs now if the analyzers aren't working. Work to automatically translate Bandit and SpotBugs vulnerabilities to Semgrep is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328062). - A vulnerability was created by ESLint, Gosec, or Flawfinder in a default-branch pipeline where Semgrep scanning did not run successfully (before Semgrep coverage was introduced for the language, because you disabled Semgrep explicitly, or because the Semgrep scan failed in that pipeline). We do not currently plan to combine these vulnerabilities if they already exist. @@ -119,13 +119,13 @@ To switch to Semgrep-based scanning early, you can: 1. Create a merge request (MR) to set the [`SAST_EXCLUDED_ANALYZERS` CI/CD variable](#disable-specific-default-analyzers) to `"bandit,gosec,eslint"`. - If you also want to disable SpotBugs scanning, add `spotbugs` to the list. We only recommend this for Java projects. SpotBugs is the only current analyzer that can scan Groovy, Kotlin, and Scala. - If you also want to disable Flawfinder scanning, add `flawfinder` to the list. We only recommend this for C projects. Flawfinder is the only current analyzer that can scan C++. -1. Verify that scanning jobs succeed in the MR. You'll notice findings from the removed analyzers in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) +1. Verify that scanning jobs succeed in the MR. Findings from the removed analyzers are available in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) 1. Merge the MR and wait for the default-branch pipeline to run. 1. Use the Vulnerability Report to dismiss the findings that are no longer detected by the language-specific analyzers. #### Preview Semgrep-based scanning -You can see how Semgrep-based scanning will work in your projects before the GitLab-managed Stable CI/CD template for SAST is updated. +You can see how Semgrep-based scanning works in your projects before the GitLab-managed Stable CI/CD template for SAST is updated. We recommend that you test this change in a merge request but continue using the Stable template in your default branch pipeline configuration. In GitLab 15.3, we [activated a feature flag](https://gitlab.com/gitlab-org/gitlab/-/issues/362179) to migrate security findings on the default branch from other analyzers to Semgrep. @@ -148,10 +148,10 @@ To preview the upcoming changes to the CI/CD configuration in GitLab 15.3 or ear remote: 'https://gitlab.com/gitlab-org/gitlab/-/raw/2851f4d5/lib/gitlab/ci/templates/Jobs/SAST.latest.gitlab-ci.yml' ``` -1. Verify that scanning jobs succeed in the MR. You'll notice findings from the removed analyzers in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) +1. Verify that scanning jobs succeed in the MR. You notice findings from the removed analyzers in _Fixed_ and findings from Semgrep in _New_. (Some findings may show different names, descriptions, and severities, since GitLab manages and edits the Semgrep rulesets.) 1. Close the MR. -To learn more about Stable and Latest templates, see documentation on [CI/CD template versioning](../../../development/cicd/templates.md#versioning). +For more information about Stable and Latest templates, see [CI/CD template versioning](../../../development/cicd/templates.md#versioning). ## Customize analyzers diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index aec7158d2e4..d070883df9a 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -23,7 +23,7 @@ repository being scanned. There are two kinds of customization: ## Disable predefined rules -You can disable predefined rules for any SAST analyzer. Disabled rules won't appear +You can disable predefined rules for any SAST analyzer. Disabled rules don't appear on the [Pipeline Security](../index.md#view-security-scan-information-in-the-pipeline-security-tab) tab or the [Vulnerability Report](../index.md#view-security-scan-information-in-the-vulnerability-report). @@ -103,7 +103,7 @@ differ based on the kind of configuration you're making. | `[[$analyzer.ruleset]]` | Predefined rules | Defines modifications to an existing rule. | | `interpolate` | All | If set to `true`, you can use `$VAR` in the configuration to evaluate environment variables. Use this feature with caution, so you don't leak secrets or tokens. (Default: `false`) | | `description` | Passthroughs | Description of the custom ruleset. | -| `targetdir` | Passthroughs | The directory where the final configuration should be persisted. If empty, a directory with a random name is created. The directory can contain up to 100MB of files. | +| `targetdir` | Passthroughs | The directory where the final configuration should be persisted. If empty, a directory with a random name is created. The directory can contain up to 100 MB of files. | | `validate` | Passthroughs | If set to `true`, the content of each passthrough is validated. The validation works for `yaml`, `xml`, `json` and `toml` content. The proper validator is identified based on the extension used in the `target` parameter of the `[[$analyzer.passthrough]]` section. (Default: `false`) | | `timeout` | Passthroughs | The maximum time to spend to evaluate the passthrough chain, before timing out. The timeout cannot exceed 300 seconds. (Default: 60) | @@ -249,13 +249,13 @@ a higher precedence and can overwrite or append to data yielded by previous passthroughs (depending on the `mode`). This is useful for cases where you need to use or modify an existing configuration. -The amount of data generated by a single passthrough is limited to 1MB. +The amount of data generated by a single passthrough is limited to 1 MB. | Setting | Applies to | Description | | ------- | ---------- | ----------- | | `type` | All | One of `file`, `raw`, `git` or `url`. | | `target` | All | The target file to contain the data written by the passthrough evaluation. If empty, a random filename is used. | -| `mode` | All | If `overwrite`, the `target` file is overwritten. If `append`, new content is appended to the `target` file. Note that the `git` type only supports `overwrite`. (Default: `overwrite`) | +| `mode` | All | If `overwrite`, the `target` file is overwritten. If `append`, new content is appended to the `target` file. The `git` type only supports `overwrite`. (Default: `overwrite`) | | `ref` | `type = "git"` | Contains the name of the branch or the SHA to pull. When using a branch name, specify it in the form `refs/heads/<branch>`, not `refs/remotes/<remote_name>/<branch>`. | | `subdir` | `type = "git"` | Used to select a subdirectory of the Git repository as the configuration source. | | `value` | All | For the `file`, `url`, and `git` types, defines the location of the file or Git repository. For the `raw` type, contains the inline configuration. | @@ -273,7 +273,7 @@ The amount of data generated by a single passthrough is limited to 1MB. WARNING: When using the `raw` passthrough with a YAML snippet, it's recommended to format all indentation in the `sast-ruleset.toml` file as spaces. The YAML specification mandates spaces over tabs, and the -analyzer will fail to parse your custom ruleset unless the indentation is represented accordingly. +analyzer fails to parse your custom ruleset unless the indentation is represented accordingly. ## Examples @@ -317,8 +317,7 @@ With the following custom ruleset configuration, the following rules are omitted ### Override predefined rules of SAST analyzers With the following custom ruleset configuration, vulnerabilities found with -`semgrep` with a type `CWE` and a value `322` will have their severity -overridden to `Critical`. +`semgrep` with a type `CWE` and a value `322` have their severity overridden to `Critical`. ```toml [semgrep] @@ -416,7 +415,7 @@ Different passthrough types are demonstrated in this example: - The `sast-rules` entry has a higher precedence because it appears later in the configuration. - If there's a filename collision between the two checkouts, files - from the `sast-rules` repository will overwrite files from the + from the `sast-rules` repository overwrite files from the `myrules` repository. - A `raw` passthrough, which writes its `value` to `/sgrules/insecure.yml`. - A `url` passthrough, which fetches a configuration hosted at a URL and diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index c4352f45704..b0d84e4cff9 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -62,7 +62,7 @@ To run SAST jobs, by default, you need GitLab Runner with the If you're using the shared runners on GitLab.com, this is enabled by default. WARNING: -Our SAST jobs require a Linux/amd64 container type. Windows containers are not yet supported. +GitLab SAST analyzers don't support running on Windows or on any CPU architectures other than amd64. WARNING: If you use your own runners, make sure the Docker version installed @@ -73,7 +73,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae GitLab SAST supports scanning a variety of programming languages and frameworks. Once you [enable SAST](#configuration), the right set of analyzers runs automatically even if your project uses more than one language. -Check the [SAST direction page](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) to learn more about our plans for language support in SAST. +For more information about our plans for language support in SAST, see the [category direction page](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support). | Language / framework | [Analyzer](analyzers.md) used for scanning | Minimum supported GitLab version | |------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| @@ -144,12 +144,15 @@ the repository. For details on the Solution format, see the Microsoft reference ## False positive detection **(ULTIMATE)** -> Introduced in GitLab 14.2. +> - Introduced for Ruby in GitLab 14.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378622) for Go in GitLab 15.8. -Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. +GitLab SAST can identify certain types of false positive results in the output of other tools. +These results are flagged as false positives on the [Vulnerability Report](../vulnerability_report/index.md) and the [Vulnerability Page](../vulnerabilities/index.md). False positive detection is available in a subset of the [supported languages](#supported-languages-and-frameworks) and [analyzers](analyzers.md): +- Go, in the Semgrep-based analyzer - Ruby, in the Brakeman-based analyzer  @@ -168,7 +171,7 @@ GitLab SAST uses an advanced vulnerability tracking algorithm to more accurately Advanced vulnerability tracking is available in a subset of the [supported languages](#supported-languages-and-frameworks) and [analyzers](analyzers.md): - C, in the Semgrep-based analyzer only -- Go, in the Gosec- and Semgrep-based analyzers +- Go, in the Semgrep-based analyzer only - Java, in the Semgrep-based analyzer only - JavaScript, in the Semgrep-based analyzer only - Python, in the Semgrep-based analyzer only @@ -178,9 +181,23 @@ Support for more languages and analyzers is tracked in [this epic](https://gitla For more information, see the confidential project `https://gitlab.com/gitlab-org/security-products/post-analyzers/tracking-calculator`. The content of this project is available only to GitLab team members. +## Automatic vulnerability resolution + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/368284) in GitLab 15.9 [with a project-level flag](../../../administration/feature_flags.md) named `sec_mark_dropped_findings_as_resolved`. Enabled by default on GitLab.com; disabled by default in self-managed. On GitLab.com, [contact Support](https://about.gitlab.com/support/) if you need to disable the flag for your project. + +To help you focus on the vulnerabilities that are still relevant, GitLab SAST automatically [resolves](../vulnerabilities/index.md#vulnerability-status-values) vulnerabilities when: + +- You [disable a predefined rule](customize_rulesets.md#disable-predefined-rules). +- We remove a rule from the default ruleset. + +Automatic resolution is available only for findings from the [Semgrep-based analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep). +The Vulnerability Management system leaves a comment on automatically-resolved vulnerabilities so you still have a historical record of the vulnerability. + +If you re-enable the rule later, the findings are reopened for triage. + ## Supported distributions -The default scanner images are build off a base Alpine image for size and maintainability. +The default scanner images are built on a base Alpine image for size and maintainability. ### FIPS-enabled images @@ -350,13 +367,13 @@ To override the automatic update behavior, set the `SAST_ANALYZER_IMAGE_TAG` CI/ in your CI/CD configuration file after you include the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml). Only set this variable within a specific job. -If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set will be used for other SAST analyzers. +If you set it [at the top level](../../../ci/variables/index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file), the version you set is used for other SAST analyzers. You can set the tag to: -- A major version, like `3`. Your pipelines will use any minor or patch updates that are released within this major version. -- A minor version, like `3.7`. Your pipelines will use any patch updates that are released within this minor version. -- A patch version, like `3.7.0`. Your pipelines won't receive any updates. +- A major version, like `3`. Your pipelines use any minor or patch updates that are released within this major version. +- A minor version, like `3.7`. Your pipelines use any patch updates that are released within this minor version. +- A patch version, like `3.7.0`. Your pipelines don't receive any updates. This example uses a specific minor version of the `semgrep` analyzer and a specific patch version of the `brakeman` analyzer: @@ -552,7 +569,7 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | CI/CD variable | Default value | Description | |------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. To exclude paths, copy and paste the default excluded paths, then **add** your own paths to be excluded. If you don't specify the default excluded paths, you will override the defaults and _only_ paths you specify will be excluded from the SAST scans. | +| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. To exclude paths, copy and paste the default excluded paths, then **add** your own paths to be excluded. If you don't specify the default excluded paths, you override the defaults and _only_ paths you specify are excluded from the SAST scans. | | `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | | `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'`. [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) in GitLab 15.4. | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | @@ -788,6 +805,11 @@ If you're seeing a new error that doesn't appear to be related to [the GitLab-ma Each [analyzer project](analyzers.md#sast-analyzers) has a `CHANGELOG.md` file listing the changes made in each available version. +### `exec /bin/sh: exec format error` message in job log + +GitLab SAST analyzers [only support](#requirements) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. + ### `Error response from daemon: error processing tar file: docker-tar: relocation error` This error occurs when the Docker version that runs the SAST job is `19.03.0`. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index d955170ece2..d6aab71a2c6 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -65,17 +65,76 @@ Different features are available in different [GitLab tiers](https://about.gitla | [Access the Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** No | **{check-circle}** Yes | | [Customize Secret Detection rulesets](#custom-rulesets) | **{dotted-circle}** No | **{check-circle}** Yes | +## Coverage + +Secret Detection scans different aspects of your code, depending on the situation. For all methods +except "Default branch", Secret Detection scans commits, not the working tree. For example, +Secret Detection can detect if a secret was added in one commit and removed in a later commit. + +- Historical scan + + If the `SECRET_DETECTION_HISTORIC_SCAN` variable is set, the content of all + [branches](../../project/repository/branches/index.md) is scanned. Before scanning the + repository's content, Secret Detection runs the command `git fetch --all` to fetch the content of all + branches. + +- Commit range + + If the `SECRET_DETECTION_LOG_OPTS` variable is set, the secrets analyzer fetches the entire + history of the branch or reference the pipeline is being run for. Secret Detection then runs, + scanning the commit range specified. + +- Default branch + + When Secret Detection is run on the default branch, the Git repository is treated as a plain + folder. Only the contents of the repository at the current HEAD are scanned. Commit history is not scanned. + +- Push event + + On a push event, Secret Detection determines what commit range to scan, given the information + available in the runner. To determine the commit range, the variables `CI_COMMIT_SHA` and + `CI_COMMIT_BEFORE_SHA` are important. + + - `CI_COMMIT_SHA` is the commit at HEAD for a given branch. This variable is always set for push events. + - `CI_COMMIT_BEFORE_SHA` is set in most cases. However, it is not set for the first push event on + a new branch, nor for merge pipelines. Because of this, Secret Detection can't be guaranteed + when multiple commits are committed to a new branch. + +- Merge request + + In a merge request, Secret Detection scans every commit made on the source branch. To use this + feature, you must use the [`latest` Secret Detection template](#templates), as it supports + [merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md). + +## Templates + +Secret Detection default configuration is defined in CI/CD templates. Updates to the template are +provided with GitLab upgrades, allowing you to benefit from any improvements and additions. + +Available templates: + +- [`Secret-Detection.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Secret-Detection.gitlab-ci.yml): Stable version of the Secret Detection CI/CD template. +- [`Secret-Detection.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Secret-Detection.latest.gitlab-ci.yml): Latest version of the Secret Detection template. + +WARNING: +The latest version of the template may include breaking changes. Use the stable template unless you +need a feature provided only in the latest template. + +For more information about template versioning, see the +[CI/CD documentation](../../../development/cicd/templates.md#latest-version). + ## Enable Secret Detection Prerequisites: -- GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or +- Linux-based GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. + - Windows Runners are not supported. + - CPU architectures other than amd64 are not supported. - If you use your own runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. -- Linux/amd64 container type. Windows containers are not supported. - GitLab CI/CD configuration (`.gitlab-ci.yml`) must include the `test` stage. To enable Secret Detection, either: @@ -136,7 +195,12 @@ Pipelines now include a Secret Detection job. ## Responding to a leaked secret -If the scanner detects a secret you should rotate it immediately. [Purging a file from the repository's history](../../project/repository/reducing_the_repo_size_using_git.md#purge-files-from-repository-history) may not be effective in removing all references to the file. Also, the secret remains in any forks of the repository. +Secrets detected by the analyzer should be immediately rotated. +[Purging a file from the repository's history](../../project/repository/reducing_the_repo_size_using_git.md#purge-files-from-repository-history) +may not be effective in removing all references to the file. Additionally, the secret will remain in any existing +forks or clones of the repository. + +GitLab will attempt to [automatically revoke](post_processing.md) some types of leaked secrets. ## Pinning to specific analyzer version @@ -150,9 +214,9 @@ in your CI/CD configuration file after you include the [`Secret-Detection.gitlab You can set the tag to: -- A major version, like `4`. Your pipelines will use any minor or patch updates that are released within this major version. -- A minor version, like `4.5`. Your pipelines will use any patch updates that are released within this minor version. -- A patch version, like `4.5.0`. Your pipelines won't receive any updates. +- A major version, like `4`. Your pipelines use any minor or patch updates that are released within this major version. +- A minor version, like `4.5`. Your pipelines use any patch updates that are released within this minor version. +- A patch version, like `4.5.0`. Your pipelines don't receive any updates. This example uses a specific minor version of the analyzer: @@ -531,3 +595,8 @@ repository's default branch is unrelated to the branch the job was triggered for To resolve the issue, make sure to correctly [set your default branch](../../project/repository/branches/default.md#change-the-default-branch-name-for-a-project) on your repository. You should set it to a branch that has related history with the branch you run the `secret-detection` job on. + +### `exec /bin/sh: exec format error` message in job log + +The GitLab Secret Detection analyzer [only supports](#enable-secret-detection) running on the `amd64` CPU architecture. +This message indicates that the job is being run on a different architecture, such as `arm`. diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md index e026c663854..22d7a8ba5af 100644 --- a/doc/user/application_security/secret_detection/post_processing.md +++ b/doc/user/application_security/secret_detection/post_processing.md @@ -4,36 +4,39 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Secret Detection post-processing and revocation **(FREE SAAS)** +# Secret Detection post-processing and revocation **(ULTIMATE SAAS)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. > - [Disabled by default for GitLab personal access tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/371658) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `gitlab_pat_auto_revocation`. Available to GitLab.com only. +> - [Enabled by default for GitLab personal access tokens](https://gitlab.com/gitlab-org/gitlab/-/issues/371658) in GitLab 15.9 -FLAG: -By default, auto revocation of GitLab personal access tokens is not available. To opt-in on GitLab.com -during the [Beta period](../../../policy/alpha-beta-support.md#beta-features), please -[let us know by completing this form](https://docs.google.com/forms/d/e/1FAIpQLSdRbFhvA5jvI-Rt_Qnl1PQ1znOXKK8m6lRtmM0uva4upetKvQ/viewform). - -GitLab supports running post-processing hooks after detecting a secret. These -hooks can perform actions, like notifying the cloud service that issued the secret. -The cloud provider can then confirm the credentials and take remediation actions, like: +GitLab.com and self-managed supports running post-processing hooks after detecting a secret. These +hooks can perform actions, like notifying the vendor that issued the secret. +The vendor can then confirm the credentials and take remediation actions, like: - Revoking a secret. - Reissuing a secret. - Notifying the creator of the secret. -GitLab SaaS supports post-processing for [GitLab personal access tokens](../../profile/personal_access_tokens.md) and Amazon Web Services (AWS). -Post-processing workflows vary by supported cloud providers. +GitLab supports post-processing for the following vendors and secrets: + +| Vendor | Secret | GitLab.com | Self-managed | +| ----- | --- | --- | --- | +| GitLab | [Personal access tokens](../../profile/personal_access_tokens.md) | ✅ | ✅ 15.9 and later | +| Amazon Web Services (AWS) | [IAM access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) | ✅ | ⚙ | + +**Component legend** -Post-processing is limited to a project's default branch. The epic -[Post-processing of leaked secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). -contains: +- ✅ - Available by default +- ⚙ - Requires manual integration using a [Token Revocation API](../../../development/sec/token_revocation_api.md) -- Technical details of post-processing secrets. -- Discussions of efforts to support additional branches. +## Feature availability -NOTE: -Post-processing is currently limited to a project's default branch +Credentials are only post-processed when Secret Detection finds them: + +- In public projects, because publicly exposed credentials pose an increased threat. Expansion to private projects is considered in [issue 391379](https://gitlab.com/gitlab-org/gitlab/-/issues/391379). +- On the project [default branch](../../project/repository/branches/default.md), for technical reasons. Expansion to all branches is tracked in [issue 299212](https://gitlab.com/gitlab-org/gitlab/-/issues/299212). +- In projects with GitLab Ultimate, for technical reasons. Expansion to all tiers is tracked in [issue 391763](https://gitlab.com/gitlab-org/gitlab/-/issues/391763). ## High-level architecture @@ -44,142 +47,51 @@ sequenceDiagram autonumber GitLab Rails->>+Sidekiq: gl-secret-detection-report.json Sidekiq-->+Sidekiq: StoreSecurityReportsWorker - Sidekiq-->+RevocationAPI: GET revocable keys types - RevocationAPI-->>-Sidekiq: OK - Sidekiq->>+RevocationAPI: POST revoke revocable keys - RevocationAPI-->>-Sidekiq: ACCEPTED - RevocationAPI-->>+Cloud Vendor: revoke revocable keys - Cloud Vendor-->>+RevocationAPI: ACCEPTED -``` - -## Integrate your cloud provider service with GitLab SaaS - -Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). - -### Implement a vendor revocation receiver service - -A vendor revocation receiver service integrates with a GitLab instance to receive -a web notification and respond to leaked token requests. - -To implement a receiver service to revoke leaked tokens: - -1. Create a publicly accessible HTTP service matching the corresponding API contract - below. Your service should be idempotent and rate-limited. -1. When a pipeline corresponding to its revocable token type (in the example, `my_api_token`) - completes, GitLab sends a request to your receiver service. -1. The included URL should be publicly accessible, and contain the commit where the - leaked token can be found. For example: - - ```plaintext - POST / HTTP/2 - Accept: */* - Content-Type: application/json - X-Gitlab-Token: MYSECRETTOKEN - - [ - {"type": "my_api_token", "token":"XXXXXXXXXXXXXXXX","url": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile1.java"} - ] - ``` - -## Implement a revocation service for self-managed - -Self-managed instances interested in using the revocation capabilities must: - -- Deploy the [RevocationAPI](#high-level-architecture). -- Configure the GitLab instance to use the RevocationAPI. - -A RevocationAPI must: - -- Match a minimal API specification. -- Provide two endpoints: - - Fetching revocable token types. - - Revoking leaked tokens. -- Be rate-limited and idempotent. - -Requests to the documented endpoints are authenticated via API tokens passed in -the `Authorization` header. Request and response bodies, if present, are -expected to have the content type `application/json`. - -All endpoints may return these responses: - -- `401 Unauthorized` -- `405 Method Not Allowed` -- `500 Internal Server Error` - -### `GET /v1/revocable_token_types` - -Returns the valid `type` values for use in the `revoke_tokens` endpoint. - -NOTE: -These values match the concatenation of [the `secrets` analyzer's](index.md) -[primary identifier](../../../development/integrations/secure.md#identifiers) by means -of concatenating the `primary_identifier.type` and `primary_identifier.value`. -In the case below, a finding identifier matches: - -```json -{"type": "gitleaks_rule_id", "name": "Gitleaks rule ID GitLab Personal Access Token", "value": "GitLab Personal Access Token"} -``` - -| Status Code | Description | -| ----- | --- | -| `200` | The response body contains the valid token `type` values. | - -Example response body: - -```json -{ - "types": ["gitleaks_rule_id_gitlab_personal_access_token"] -} + Sidekiq-->+Token Revocation API: GET revocable keys types + Token Revocation API-->>-Sidekiq: OK + Sidekiq->>+Token Revocation API: POST revoke revocable keys + Token Revocation API-->>-Sidekiq: ACCEPTED + Token Revocation API-->>+Receiver Service: revoke revocable keys + Receiver Service-->>+Token Revocation API: ACCEPTED ``` -### `POST /v1/revoke_tokens` - -Accepts a list of tokens to be revoked by the appropriate provider. - -| Status Code | Description | -| ----- | --- | -| `204` | All submitted tokens have been accepted for eventual revocation. | -| `400` | The request body is invalid or one of the submitted token types is not supported. The request should not be retried. | -| `429` | The provider has received too many requests. The request should be retried later. | - -Example request body: - -```json -[{ - "type": "gitleaks_rule_id_gitlab_personal_access_token", - "token": "glpat--8GMtG8Mf4EnMJzmAWDU", - "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile1.java" -}, -{ - "type": "gitleaks_rule_id_gitlab_personal_access_token", - "token": "glpat--tG84EGK33nMLLDE70zU", - "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile2.java" -}] +1. A pipeline with a Secret Detection job completes on the project's default branch, producing a scan + report (**1**). +1. The report is processed (**2**) by an asynchronous worker, which communicates with an externally + deployed HTTP service (**3** and **4**) to determine which kinds of secrets can be automatically + revoked. +1. The worker sends (**5** and **6**) the list of detected secrets which the Token Revocation API is able to + revoke. +1. The Token Revocation API sends (**7** and **8**) each revocable token to their respective vendor's [receiver service](#integrate-your-cloud-provider-service-with-gitlabcom). + +See the [Token Revocation API](../../../development/sec/token_revocation_api.md) documentation for more +information. + +## Integrate your cloud provider service with GitLab.com + +Third-party cloud and SaaS vendors interested in automated token revocation can +[express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). +Vendors must [implement a revocation receiver service](#implement-a-revocation-receiver-service) +which will be called by the Token Revocation API. + +### Implement a revocation receiver service + +A revocation receiver service integrates with a GitLab instance's Token Revocation API to receive and respond +to leaked token revocation requests. The service should be a publicly accessible HTTP API that is +idempotent and rate-limited. Requests to your service from the Token Revocation API will follow the example +below: + +```plaintext +POST / HTTP/2 +Accept: */* +Content-Type: application/json +X-Gitlab-Token: MYSECRETTOKEN + +[ + {"type": "my_api_token", "token":"XXXXXXXXXXXXXXXX","url": "https://example.com/some-repo/~/raw/abcdefghijklmnop/compromisedfile1.java"} +] ``` -### Configure GitLab to interface with RevocationAPI - -You must configure the following database settings in the GitLab instance: - -- `secret_detection_token_revocation_enabled` -- `secret_detection_token_revocation_url` -- `secret_detection_token_revocation_token` -- `secret_detection_revocation_token_types_url` - -For example, to configure these values in the -[Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): - -```ruby -::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_token: 'MYSECRETTOKEN') -::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_url: 'https://example.gitlab.com/revocation_service/v1/revoke_tokens') -::Gitlab::CurrentSettings.update!(secret_detection_revocation_token_types_url: 'https://example.gitlab.com/revocation_service/v1/revocable_token_types') -::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_enabled: true) -``` - -After you configure these values, completing a pipeline performs these actions: - -1. The revocation service is triggered once. -1. A request is made to `secret_detection_revocation_token_types_url` to fetch a - list of revocable tokens. -1. Any Secret Detection findings matching the results of the `token_types` request - are included in the subsequent revocation request. +In this example, Secret Detection has determined that an instance of `my_api_token` has been leaked. The +value of the token is provided to you, in addition to a publicly accessible URL to the raw content of the +file containing the leaked token. diff --git a/doc/user/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md new file mode 100644 index 00000000000..fb10efff2c6 --- /dev/null +++ b/doc/user/application_security/secure_your_application.md @@ -0,0 +1,29 @@ +--- +stage: Secure +group: Static Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Secure your application **(FREE)** + +GitLab can check your applications for security vulnerabilities. + +- [Get started](get-started-security.md) +- [Security Configuration](configuration/index.md) +- [Container Scanning](container_scanning/index.md) +- [Dependency Scanning](dependency_scanning/index.md) +- [Static Application Security Testing](sast/index.md) +- [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md) +- [Secret Detection](secret_detection/index.md) +- [Dynamic Application Security Testing (DAST)](dast/index.md) +- [API Fuzzing](api_fuzzing/index.md) +- [Coverage-guided fuzz testing](coverage_fuzzing/index.md) +- [Security Dashboard](security_dashboard/index.md) +- [Offline Environments](offline_deployments/index.md) +- [Vulnerability Report](vulnerability_report/index.md) +- [Vulnerability Page](vulnerabilities/index.md) +- [Vulnerability severity levels](vulnerabilities/severities.md) +- [CVE ID requests](cve_id_request.md) +- [Policies](policies/index.md) +- [Security scanner integration](../../development/integrations/secure.md) +- [Secure and Govern Terminology](terminology/index.md) diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 7c44b49b78c..7388ef80e68 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -21,12 +21,18 @@ To use the Security Dashboards, you must: ## When Security Dashboards are updated -The Security Dashboards show results of the most recent security scan on the +The Security Dashboards show results of scans from the most recent completed pipeline on the [default branch](../../project/repository/branches/default.md). -Security scans run only when the default branch updates, so -information on the Security Dashboard might not reflect newly-discovered vulnerabilities. +Dashboards are updated with the result of completed pipelines run on the default branch; they do not include vulnerabilities discovered in pipelines from other un-merged branches. -To run a daily security scan, +If you use manual jobs, for example gate deployments, in the default branch's pipeline, +the results of any scans are only updated when the job has been successfully run. +If manual jobs are skipped regularly, you should to define the job as optional, +using the [`allow_failure`](../../../ci/jobs/job_control.md#types-of-manual-jobs) attribute. + +To ensure regular security scans (even on infrequently developed projects), +you should use [scan execution policies](../../../user/application_security/policies/scan-execution-policies.md). +Alternatively, you can [configure a scheduled pipeline](../../../ci/pipelines/schedules.md). ## Reduce false negatives in dependency scans @@ -51,7 +57,7 @@ To reduce false negatives in [dependency scans](../../../user/application_securi The project Security Dashboard shows the total number of vulnerabilities over time, with up to 365 days of historical data. Data refresh begins daily at 01:15 UTC via a scheduled job. Each refresh captures a snapshot of open vulnerabilities. Data is not backported to prior days -so vulnerabilities opened after the job has already run for the day will not be reflected in the +so vulnerabilities opened after the job has already run for the day cannot be reflected in the counts until the following day's refresh job. Project Security Dashboards show statistics for all vulnerabilities with a current status of `Needs triage` or `Confirmed` . @@ -99,7 +105,7 @@ To view project security status for a group: 1. Select **Security > Security Dashboard**. Each project is assigned a letter [grade](#project-vulnerability-grades) according to the highest-severity open vulnerability. -Dismissed or resolved vulnerabilities are excluded. Each project can receive only one letter grade and will appear only once +Dismissed or resolved vulnerabilities are excluded. Each project can receive only one letter grade and appears only once in the Project security status report. To view vulnerabilities, go to the group's [vulnerability report](../vulnerability_report/index.md). diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index 2666d91c5aa..772a7d17e1e 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -91,7 +91,7 @@ applications, and infrastructure. Findings are all potential vulnerability items scanners identify in MRs/feature branches. Only after merging to default does a finding become a [vulnerability](#vulnerability). -You can interact with vulnerability findings in two ways. +You can interact with vulnerability findings in two ways. 1. You can open an issue or merge request for the vulnerability finding. 1. You can dismiss the vulnerability finding. Dismissing the finding hides it from the default views. @@ -243,7 +243,7 @@ of the finding's [first identifier](https://gitlab.com/gitlab-org/security-produ combine to create the value. Examples of primary identifiers include `PluginID` for OWASP Zed Attack Proxy (ZAP), or `CVE` for -Trivy. Note that the identifier must be stable. Subsequent scans must return the same value for the +Trivy. The identifier must be stable. Subsequent scans must return the same value for the same finding, even if the location has slightly changed. ### Report finding @@ -257,7 +257,6 @@ once it's imported into the database. Describes the type of scan. This must be one of the following: - `api_fuzzing` -- `cluster_image_scanning` - `container_scanning` - `coverage_fuzzing` - `dast` diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 22ef3ed8a1b..67a1257799b 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -213,8 +213,8 @@ Security training uses content from third-party vendors. You must have an intern The vulnerability page may include a training link relevant to the detected vulnerability if security training is enabled. The availability of training depends on whether the enabled training vendor has content matching the particular vulnerability. Training content is requested based on the [vulnerability identifiers](../../../development/integrations/secure.md#identifiers). -The identifier given to a vulnerability will vary from one vulnerability to the next. The available training -content varies between vendors. This means some vulnerabilities will display no training content. +The identifier given to a vulnerability varies from one vulnerability to the next. The available training +content varies between vendors. This means some vulnerabilities do not display training content. Vulnerabilities with a CWE are most likely to return a training result. To view the security training for a vulnerability: diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index dd919889b4d..e6353264f39 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -171,22 +171,6 @@ To change the status of vulnerabilities in the table:  -## Dismissing a vulnerability - -When you evaluate a vulnerability and decide it requires no more action, you can mark it -as **Dismissed**. Dismissed vulnerabilities do not appear in the merge request security widget -when detected in future scans. - -When a vulnerability is dismissed, a record is made of: - -- Who dismissed it. -- Date and time when it was dismissed. -- Optionally, a reason why it was dismissed. - -Vulnerability records cannot be deleted, so a permanent record always remains. - -If a vulnerability is dismissed in error, reverse the dismissal by changing its status. - ## Sort vulnerabilities by date detected By default, vulnerabilities are sorted by severity level, with the highest-severity vulnerabilities listed at the top. @@ -199,7 +183,7 @@ To sort vulnerabilities by the date each vulnerability was detected, select the > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213013) to the group-level Vulnerability Report in GitLab 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 do not +is CSV (comma separated values). All vulnerabilities are included because filters do not apply to the export. Fields included are: @@ -218,7 +202,7 @@ Fields included are: - Other identifiers - Detected At - Location -- Activity +- Activity: Returns `true` if the vulnerability is resolved on the default branch, and `false` if not. - Comments NOTE: @@ -242,10 +226,23 @@ thousands of vulnerabilities. Do not close the page until the download finishes. > The option of adding a dismissal reason was introduced in GitLab 12.0. -You can dismiss a vulnerability for the entire project: +When you evaluate a vulnerability and decide it requires no more action, +you can mark it as **Dismissed**. +Dismissed vulnerabilities do not appear in the merge request security widget +when detected in future scans. + +When a vulnerability is dismissed in a project or group, a record is made of: + +- Who dismissed it. +- Date and time when it was dismissed. +- Optionally, a reason why it was dismissed. + +Vulnerability records cannot be deleted, so a permanent record always remains. + +You can dismiss a vulnerability in projects and groups: 1. Select the vulnerability in the Security Dashboard. -1. In the top-right, from the **Status** selector menu, select **Dismissed**. +1. In the upper 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. @@ -263,7 +260,7 @@ To add a new vulnerability finding from your project level Vulnerability Report 1. Select **Submit vulnerability**. 1. Complete the fields and submit the form. -You will be brought to the newly created vulnerability's detail page. Manually created records appear in the +You are brought to the newly created vulnerability's detail page. Manually created records appear in the Group, Project, and Security Center Vulnerability Reports. To filter them, use the Generic Tool filter. ## Operational vulnerabilities diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index 57c18cb045e..0e5bb5e10f7 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -38,7 +38,7 @@ Before GitLab displays results, the vulnerability findings in all pipeline repor GitLab displays one row of information for each [scan type](../terminology/index.md#scan-type-report-type) artifact present in the pipeline. -Note that each scan type's total number of vulnerabilities includes dismissed findings. If the number of findings +Each scan type's total number of vulnerabilities includes dismissed findings. If the number of findings in the report doesn't match the number in **Scan details**, ensure that **Hide dismissed** is disabled. ### Download security scan outputs @@ -64,7 +64,7 @@ This shows a list of the combined results for all security report artifacts. The the addition of a **Hide dismissed** toggle. When you review the vulnerability findings reported in the pipeline, you can select one or more entries for dismissal, -similar to [Dismissing a vulnerability](index.md#dismissing-a-vulnerability) in the Vulnerability Report. +similar to [Dismissing a vulnerability](index.md#dismiss-a-vulnerability) in the Vulnerability Report. When you merge the branch corresponding to the pipeline into the default branch, all reported findings are combined into the [Vulnerability Report](index.md). Scan results in pipelines executed on the default branch are @@ -77,7 +77,7 @@ incorporated once the pipeline finishes. | Confirmed | No | Confirmed | | Needs triage (Detected) | No | Needs triage (Detected) | | Resolved | No | Needs triage (Detected) | -| N/A (i.e.: new vulnerability) | No | Needs triage (Detected) | +| N/A (That is: new vulnerability) | No | Needs triage (Detected) | ## Retention period for vulnerabilities |