diff options
Diffstat (limited to 'doc/user/application_security')
31 files changed, 309 insertions, 133 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 db0b2a32bcf..1ba19359fde 100644 --- a/doc/user/application_security/api_fuzzing/create_har_files.md +++ b/doc/user/application_security/api_fuzzing/create_har_files.md @@ -1,7 +1,7 @@ --- stage: Secure group: Dynamic Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 4eb721f8832..5413c28912a 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -87,9 +87,6 @@ In GitLab 14.0 and later, API fuzzing configuration files must be in your reposi > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - The API fuzzing configuration form helps you create or modify your project's API fuzzing configuration. The form lets you choose values for the most common API fuzzing options and builds a YAML snippet that you can paste in your GitLab CI/CD configuration. @@ -804,7 +801,7 @@ variables: If the value must be generated or regenerated on expiration, you can provide a program or script for the API fuzzer to execute on a specified interval. The provided script runs in an Alpine Linux -container that has Python 3 and Bash installed. +container that has Python 3 and Bash installed. You have to set the environment variable `FUZZAPI_OVERRIDES_CMD` to the program or script you would like to execute. The provided command creates the overrides JSON file as defined previously. @@ -813,7 +810,7 @@ You might want to install other scripting runtimes like NodeJS or Ruby, or maybe your overrides command. In this case, we recommend setting the `FUZZAPI_PRE_SCRIPT` to the file path of a script which provides those prerequisites. The script provided by `FUZZAPI_PRE_SCRIPT` is executed once, before the analyzer starts. -See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) +See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) page for information about installing Alpine Linux packages. You must provide three CI/CD variables, each set for correct operation: diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md index 0db9af7a0d3..293645b8de6 100644 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ b/doc/user/application_security/cluster_image_scanning/index.md @@ -29,7 +29,7 @@ To integrate GitLab with security scanners other than those listed here, see You can use cluster image scanning through the following methods: - [The cluster image scanning analyzer](#use-the-cluster-image-scanning-analyzer) -- [The GitLab Agent](#cluster-image-scanning-with-the-gitlab-agent) +- [The GitLab agent](#cluster-image-scanning-with-the-gitlab-agent) ## Use the cluster image scanning analyzer @@ -46,7 +46,7 @@ To enable cluster image scanning in your pipeline, you need the following: - [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) - executor. + executor on Linux/amd64. - Docker `18.09.03` or later installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. - [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/installation/kubectl/) @@ -277,22 +277,22 @@ Here's an example cluster image scanning report: } ``` -## Cluster image scanning with the GitLab Agent +## Cluster image scanning with the GitLab agent -You can use the [GitLab Agent](../../clusters/agent/index.md) to +You can use the [GitLab agent](../../clusters/agent/index.md) to scan images from within your Kubernetes cluster and record the vulnerabilities in GitLab. ### Prerequisites - [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/installation/kubectl/) installed and configured in your cluster. -- [GitLab Agent](../../clusters/agent/install/index.md) +- [GitLab agent](../../clusters/agent/install/index.md) set up in GitLab, installed in your cluster, and configured using a configuration repository. ### Configuration -The Agent runs the cluster image scanning once the `cluster_image_scanning` -directive is added to your [Agent's configuration repository](../../clusters/agent/repository.md#scan-your-container-images-for-vulnerabilities). +The agent runs the cluster image scanning once the `cluster_image_scanning` +directive is added to your [agent's configuration repository](../../clusters/agent/vulnerabilities.md). ## Security Dashboard @@ -302,7 +302,7 @@ the security vulnerabilities in your groups, projects, and pipelines. ## Interacting with the vulnerabilities After you find a vulnerability, you can address it in the [vulnerability report](../vulnerabilities/index.md) -or the [GitLab Agent's](../../clusters/agent/install/index.md#view-vulnerabilities-in-cluster-images) +or the [GitLab agent's](../../clusters/agent/vulnerabilities.md) details section. ## Troubleshooting diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 430f8e1a2a2..61a2121b9c6 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -49,7 +49,9 @@ You can configure the following security controls: - Select **Configure with a merge request** to create a merge request with the changes required to enable Dependency Scanning. For more details, see [Enable Dependency Scanning via an automatic merge request](../dependency_scanning/index.md#enable-dependency-scanning-via-an-automatic-merge-request). - [Container Scanning](../container_scanning/index.md) - - Can be configured with `.gitlab-ci.yml`. For more details, read [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). + - Select **Configure with a merge request** to create a merge request with the changes required to + enable Container Scanning. For more details, see + [Enable Container Scanning through an automatic merge request](../container_scanning/index.md#enable-container-scanning-through-an-automatic-merge-request). - [Cluster Image Scanning](../cluster_image_scanning/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). - [Secret Detection](../secret_detection/index.md) @@ -66,3 +68,6 @@ You can configure the following security controls: - [License Compliance](../../../user/compliance/license_compliance/index.md) - Can be configured with `.gitlab-ci.yml`. For more details, read [License Compliance](../../../user/compliance/license_compliance/index.md#enable-license-compliance). + +- [Security Training](../../../user/application_security/vulnerabilities/index.md#enable-security-training-for-vulnerabilities) + - Enable **Security training** for the current project. For more details, read [security training](../../../user/application_security/vulnerabilities/index.md#enable-security-training-for-vulnerabilities). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 08a8c46cc72..f2d6cef669d 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -50,7 +50,7 @@ To enable container scanning in your pipeline, you need the following: - Container 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. - [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) - or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. + or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor on Linux/amd64. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. - An image matching the [supported distributions](#supported-distributions). @@ -145,7 +145,7 @@ For example, to scan an image from AWS Elastic Container Registry: ```yaml container_scanning: before_script: - - curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" --output "awscliv2.zip" + - ruby -r open-uri -e "IO.copy_stream(URI.open('https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip'), 'awscliv2.zip')" - unzip awscliv2.zip - ./aws/install - aws --version @@ -253,6 +253,24 @@ images. To configure the images, set the `CS_ANALYZER_IMAGE` variable to the sta | Grype | `registry.gitlab.com/security-products/container-scanning/grype:4-ubi` | | Trivy | `registry.gitlab.com/security-products/container-scanning/trivy:4-ubi` | +### Enable Container Scanning through an automatic merge request + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6334) in GitLab 14.9. + +To enable Container Scanning in a project, create a merge request from the Security Configuration +page: + +1. In the project where you want to enable Container Scanning, go to + **Security & Compliance > Configuration**. +1. In the **Container Scanning** row, select **Configure with a merge request**. + +This automatically creates a merge request with the changes necessary to enable Container Scanning. +To complete the configuration, review and merge this merge request. + +The configuration tool works best with no existing `.gitlab-ci.yml` file, or with a minimal +configuration file. If you have a complex GitLab configuration file, it may not be parsed +successfully and an error may occur. + ### Overriding the container scanning template If you want to override the job definition (for example, to change properties like `variables`), you diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 290d4a06dcc..14e98766f0f 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -121,7 +121,7 @@ Use the following variables to configure coverage-guided fuzz testing in your CI | `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this value when using an offline environment. Default: `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | | `COVFUZZ_USE_REGISTRY` | Set to `true` to have the corpus stored in the GitLab corpus registry. The variables `COVFUZZ_CORPUS_NAME` and `COVFUZZ_GITLAB_TOKEN` are required if this variable is set to `true`. Default: `false`. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | | `COVFUZZ_CORPUS_NAME` | Name of the corpus to be used in the job. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | -| `COVFUZZ_GITLAB_TOKEN` | Environment variable configured with [Personal Access Token](../../../user/profile/personal_access_tokens.md#create-a-personal-access-token) with API read/write access. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | +| `COVFUZZ_GITLAB_TOKEN` | Environment variable configured with [Personal Access Token](../../../user/profile/personal_access_tokens.md#create-a-personal-access-token) or [Project Access Token](../../../user/project/settings/project_access_tokens.md#create-a-project-access-token) with API read/write access. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. | #### Seed corpus @@ -144,12 +144,8 @@ You can download the JSON report file from the CI/CD pipelines page. For more in ## Corpus registry -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an -administrator to [disable the feature flags](../../../administration/feature_flags.md) named -`corpus_management` and `corpus_management_ui`. On GitLab.com, this feature is available. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5017) in GitLab 14.8. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/347187) in GitLab 14.9. [Feature flags `corpus_management` and `corpus_management_ui`](https://gitlab.com/gitlab-org/gitlab/-/issues/328418) removed. The corpus registry is a library of corpuses. Corpuses in a project's registry are available to all jobs in that project. A project-wide registry is a more efficient way to manage corpuses than diff --git a/doc/user/application_security/dast/checks/200.1.md b/doc/user/application_security/dast/checks/200.1.md index 98a482b4a0f..9795ad11b0b 100644 --- a/doc/user/application_security/dast/checks/200.1.md +++ b/doc/user/application_security/dast/checks/200.1.md @@ -8,13 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description -A private RFC 1918 was identified in the target application. Public facing websites should not be issuing -requests to private IP Addresses. Attackers attempting to execute subsequent attacks, such as Server-Side +A private RFC 1918 was identified in the target application. Public facing websites should not be issuing +requests to private IP Addresses. Attackers attempting to execute subsequent attacks, such as Server-Side Request Forgery (SSRF), may be able to use this information to identify additional internal targets. ## Remediation -Identify the resource that is incorrectly specifying an internal IP address and replace it with it's public +Identify the resource that is incorrectly specifying an internal IP address and replace it with it's public facing version, or remove the reference from the target application. ## Details diff --git a/doc/user/application_security/dast/checks/548.1.md b/doc/user/application_security/dast/checks/548.1.md index 94f747739c5..d6371c5491d 100644 --- a/doc/user/application_security/dast/checks/548.1.md +++ b/doc/user/application_security/dast/checks/548.1.md @@ -8,8 +8,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description -The target web server is configured to list the contents of directories that do not contain an index file -such as `index.html`. This could lead to accidental exposure of sensitive information, or give an attacker +The target web server is configured to list the contents of directories that do not contain an index file +such as `index.html`. This could lead to accidental exposure of sensitive information, or give an attacker details on how filenames and directories are structured and stored. ## Remediation @@ -17,11 +17,11 @@ details on how filenames and directories are structured and stored. Directory indexing should be disabled. Apache: -For Apache based web sites, ensure all `<Directory>` definitions have `Options -Indexes` configured in the +For Apache based web sites, ensure all `<Directory>` definitions have `Options -Indexes` configured in the `apache2.conf` or `httpd.conf` configuration file. NGINX: -For NGINX based websites, ensure all `location` definitions have the `autoindex off` directive set in the +For NGINX based websites, ensure all `location` definitions have the `autoindex off` directive set in the `nginx.conf` file. IIS: diff --git a/doc/user/application_security/dast/checks/598.1.md b/doc/user/application_security/dast/checks/598.1.md new file mode 100644 index 00000000000..817e20ec413 --- /dev/null +++ b/doc/user/application_security/dast/checks/598.1.md @@ -0,0 +1,31 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Use of GET request method with sensitive query strings (session ID) + +## Description + +A session ID was identified in the request URL as well as a cookie value. Session +IDs should not be sent in GET requests as they maybe captured by proxy systems, stored in +browser history, or stored in log files. If an attacker were to get access to the session +ID they would potentially be able to gain access to the target account. + +## Remediation + +As request headers are rarely logged or captured by third party systems, ensure session ID +values are only sent in cookies (assigned via `Set-Cookie` response headers) and never sent +in the request URL. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 598.1 | true | 598 | Passive | Medium | + +## Links + +- [OWASP](https://owasp.org/www-community/vulnerabilities/Information_exposure_through_query_strings_in_url) +- [CWE](https://cwe.mitre.org/data/definitions/598.html) diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 97224554723..435bc28c4aa 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -19,5 +19,6 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | [16.6](16.6.md) | AspNetMvc header exposes version information | Low | Passive | | [200.1](200.1.md) | Exposure of sensitive information to an unauthorized actor (private IP address) | Low | Passive | | [548.1](548.1.md) | Exposure of information through directory listing | Low | Passive | +| [598.1](598.1.md) | Use of GET request method with sensitive query strings (session ID) | Medium | Passive | | [614.1](614.1.md) | Sensitive cookie without Secure attribute | Low | Passive | | [693.1](693.1.md) | Missing X-Content-Type-Options: nosniff | Low | Passive | diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 0865cc10691..fd6c39ffbf1 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -51,7 +51,7 @@ results. On failure, the analyzer outputs an ## Prerequisites - [GitLab Runner](../../../ci/runners/index.md) available, with the -[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). +[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html) on Linux/amd64. - Target application deployed. For more details, read [Deployment options](#deployment-options). - DAST runs in the `dast` stage, which must be added manually to your `.gitlab-ci.yml`. @@ -105,7 +105,7 @@ services: # use services to link your app container to the dast job variables: DAST_FULL_SCAN_ENABLED: "true" # do a full scan - DAST_ZAP_USE_AJAX_SPIDER: "true" # use the ajax spider + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ``` Most applications depend on multiple services such as databases or caching services. By default, services defined in the services fields cannot communicate @@ -314,6 +314,7 @@ include: variables: DAST_FULL_SCAN_ENABLED: "true" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ``` If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some @@ -455,6 +456,7 @@ include: variables: GIT_STRATEGY: fetch DAST_PATHS_FILE: url_file.txt # url_file.txt lives in the root directory of the project + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ``` ##### Use `DAST_PATHS` CI/CD variable @@ -470,6 +472,7 @@ include: variables: DAST_PATHS: "/page1.html,/category1/page1.html,/page3.html" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ``` When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: @@ -547,6 +550,7 @@ include: variables: DAST_WEBSITE: https://example.com DAST_SPIDER_MINS: 120 + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ``` Because the template is [evaluated before](../../../ci/yaml/index.md#include) the pipeline @@ -628,7 +632,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_AUTH_VERIFICATION_SELECTOR` <sup>2</sup> | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo`. | | `DAST_AUTH_VERIFICATION_URL` <sup>1,2</sup> | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. Example: `"http://example.com/loggedin_page"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false`. | -| `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that will be clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | +| `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that are clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | | `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | | `DAST_EXCLUDE_URLS` <sup>1,2</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. Example, `http://example.com/sign-out`. | @@ -737,7 +741,7 @@ Only run an authenticated scan against a test server. ### Log in using automatic detection of the login form -By providing a `DAST_USERNAME`, `DAST_PASSWORD`, and `DAST_AUTH_URL`, DAST will attempt to authenticate to the +By providing a `DAST_USERNAME`, `DAST_PASSWORD`, and `DAST_AUTH_URL`, DAST attempts to authenticate to the target application by locating the login form based on a determination about whether or not the form contains username or password fields. Automatic detection is "best-effort", and depending on the application being scanned may provide either a resilient login experience or one that fails to authenticate the user. @@ -753,8 +757,8 @@ Login process: ### Log in using explicit selection of the login form By providing a `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, and `DAST_SUBMIT_FIELD`, in addition to the fields required for automatic login, -DAST will attempt to authenticate to the target application by locating the login form based on the selectors provided. -Most applications will benefit from this approach to authentication. +DAST attempts to authenticate to the target application by locating the login form based on the selectors provided. +Most applications benefit from this approach to authentication. Login process: @@ -790,6 +794,7 @@ include: dast: variables: DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ... DAST_AUTH_VERIFICATION_URL: "https://example.com/user/welcome" ``` @@ -808,6 +813,7 @@ include: dast: variables: DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ... DAST_AUTH_VERIFICATION_SELECTOR: "css:.welcome-user" ``` @@ -826,6 +832,7 @@ include: dast: variables: DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ... DAST_AUTH_VERIFICATION_LOGIN_FORM: "true" ``` @@ -847,6 +854,7 @@ include: dast: variables: DAST_WEBSITE: "https://my.site.com" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ... DAST_AUTH_URL: "https://my.site.com/admin" DAST_BROWSER_PATH_TO_LOGIN_FORM: "css:.navigation-menu,css:.login-menu-item" @@ -875,6 +883,7 @@ An example configuration where the authentication debug report is exported may l dast: variables: DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" # use the browser-based GitLab DAST crawler ... DAST_AUTH_REPORT: "true" artifacts: @@ -885,7 +894,7 @@ dast: ### Selectors Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. -Selectors have the format `type`:`search string`. The crawler will search for the selector using the search string based on the type. +Selectors have the format `type`:`search string`. The crawler searches for the selector using the search string based on the type. | Selector type | Example | Description | | ------------- | ---------------------------------- | ----------- | diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index cc20b49764f..839833d9d98 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -479,8 +479,8 @@ Follow these steps to provide the bearer token with `DAST_API_OVERRIDES_ENV`: `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the **Variables** section. - Due to the format of `TEST_API_BEARERAUTH` it's not possible to mask the variable. - To mask the token's value, you can create a second variable with the token value's, and define + Due to the format of `TEST_API_BEARERAUTH` it's not possible to mask the variable. + To mask the token's value, you can create a second variable with the token value's, and define `TEST_API_BEARERAUTH` with the value `{"headers":{"Authorization":"Bearer $MASKED_VARIABLE"}}`. 1. In your `.gitlab-ci.yml` file, set `DAST_API_OVERRIDES_ENV` to the variable you just created: @@ -876,7 +876,7 @@ variables: If the value must be generated or regenerated on expiration, you can provide a program or script for the DAST API scanner to execute on a specified interval. The provided command runs in an Alpine Linux -container that has Python 3 and Bash installed. +container that has Python 3 and Bash installed. You have to set the environment variable `DAST_API_OVERRIDES_CMD` to the program or script you would like to execute. The provided command creates the overrides JSON file as defined previously. @@ -885,7 +885,7 @@ You might want to install other scripting runtimes like NodeJS or Ruby, or maybe your overrides command. In this case, we recommend setting the `DAST_API_PRE_SCRIPT` to the file path of a script which provides those prerequisites. The script provided by `DAST_API_PRE_SCRIPT` is executed once, before the analyzer starts. -See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) +See the [Alpine Linux package management](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management) page for information about installing Alpine Linux packages. You must provide three CI/CD variables, each set for correct operation: diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index baafdcda6e0..78de740c96d 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -15,7 +15,7 @@ details about those dependencies, including their known vulnerabilities. It is a To see the dependency list, go to your project and select **Security & Compliance > Dependency List**. -This information is sometimes referred to as a Software Bill of Materials or SBoM / BOM. +This information is sometimes referred to as a Software Bill of Materials, SBOM, or BOM. The dependency list only shows the results of the last successful pipeline to run on the default branch. This is why we recommend not changing the default behavior of allowing the secure jobs to fail. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 551488c0dc0..665d29c4017 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -50,7 +50,7 @@ Any custom change to the official analyzers can be achieved by using a You can switch to a custom Docker registry that provides the official analyzer images under a different prefix. For instance, the following instructs Dependency Scanning to pull `my-docker-registry/gl-images/gemnasium` -instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium`. +instead of `registry.gitlab.com/security-products/gemnasium`. In `.gitlab-ci.yml` define: ```yaml diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index a169b78a193..a4a7e6703ab 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -69,7 +69,8 @@ stages in the `.gitlab-ci.yml` file, the `test` stage is required. To run dependency scanning jobs, by default, you need 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. +If you're using the shared runners on GitLab.com, this is enabled by default. The analyzer images +provided are for the Linux/amd64 architecture. WARNING: If you use your own runners, make sure your installed version of Docker @@ -181,7 +182,7 @@ table.supported-languages ul { </tr> <tr> <td rowspan="2">Java</td> - <td rowspan="2">8, 11, 13, 14, 15, or 16</td> + <td rowspan="2">8, 11, 13, 14, 15, 16, or 17</td> <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers-1">1</a></b></sup></td> <td> <ul> @@ -335,27 +336,61 @@ To support the following package managers, the GitLab analyzers proceed in two s 1. Execute the package manager or a specific task, to export the dependency information. 1. Parse the exported dependency information. -| Package Manager | Preinstalled Versions | Tested Versions | -| ------ | ------ | ------ | -| Bundler | [2.1.4](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/blob/v2.11.3/Dockerfile#L15)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | -| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L330), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L339), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L348), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L357), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L366), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L384) | -| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/blob/master/pom.xml#L3) | -| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5) | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3) | -| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/tests/python-setuptools/-/blob/main/setup.py) | -| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/blob/master/requirements.txt) | -| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | +| Package Manager | Pre-installed Versions | Tested Versions | +| ------ | ------ | ------ | +| Bundler | [2.1.4](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/blob/v2.11.3/Dockerfile#L15)<sup><b><a href="#exported-dependency-information-notes-1">1</a></b></sup> | [1.17.3](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/master/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | +| sbt | [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/config/.tool-versions#L4) | [1.0.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L330), [1.1.4](https://gitlab.com/gitlab-org/security-products/tests/scala-sbt-multiproject/-/blob/main/project/build.properties#L1), [1.1.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L339), [1.2.8](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L348), [1.3.12](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L357), [1.4.6](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L366), [1.6.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.24.6/.gitlab-ci.yml#L384) | +| Maven | [3.6.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L3) | [3.6.3](https://gitlab.com/gitlab-org/security-products/tests/java-maven/-/blob/master/pom.xml#L3) | +| Gradle | [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.23.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup>, [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.26.0/config/.tool-versions#L5)<sup><b><a href="#exported-dependency-information-notes-2">2</a></b></sup> | [5.6.4](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/master/gradle/wrapper/gradle-wrapper.properties#L3), [6.5](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14/gradle/wrapper/gradle-wrapper.properties#L3), [6.7-rc-1](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-15/gradle/wrapper/gradle-wrapper.properties#L3), [6.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.27.1/.gitlab-ci.yml#L289-297)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup>, [6.9](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-6-9/gradle/wrapper/gradle-wrapper.properties#L3), [7.0-rc-2](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-16/gradle/wrapper/gradle-wrapper.properties#L3), [7.3](https://gitlab.com/gitlab-org/security-products/tests/java-gradle/-/blob/java-14-gradle-7-3/gradle/wrapper/gradle-wrapper.properties#L3), [7.3.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/blob/v2.27.1/.gitlab-ci.yml#L299-317)<sup><b><a href="#exported-dependency-information-notes-3">3</a></b></sup> | +| setuptools | [50.3.2](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L27) | [57.5.0](https://gitlab.com/gitlab-org/security-products/tests/python-setuptools/-/blob/main/setup.py) | +| pip | [20.2.4](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/v2.29.9/Dockerfile#L26) | [20.x](https://gitlab.com/gitlab-org/security-products/tests/python-pip/-/blob/master/requirements.txt) | +| Pipenv | [2018.11.26](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/blob/v2.18.4/requirements.txt#L13) | [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/pipfile-lock-FREEZE/Pipfile.lock#L6)<sup><b><a href="#exported-dependency-information-notes-4">4</a></b></sup>, [2018.11.26](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/master/Pipfile) | <!-- markdownlint-disable MD044 --> <ol> <li> <a id="exported-dependency-information-notes-1"></a> <p> - The installed version of <code>Bundler</code> is only used for the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit">bundler-audit</a> analyzer, and is not used for <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">gemnasium</a> + The pre-installed version of <code>Bundler</code> is only used for the <a href="https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit">bundler-audit</a> analyzer, and is not used for <a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">gemnasium</a>. </p> </li> <li> <a id="exported-dependency-information-notes-2"></a> <p> + Different versions of Java require different versions of Gradle. The versions of Gradle listed in the above table are pre-installed + in the analyzer image. The version of Gradle used by the analyzer depends on whether your project uses a <code>gradlew</code> + (Gradle wrapper) file or not: + </p> + <ul> + <li> + <p> + If your project <i>does not use</i> a <code>gradlew</code> file, then the analyzer automatically switches to one of the + pre-installed Gradle versions, based on the version of Java specified by the + <a href="#configuring-specific-analyzers-used-by-dependency-scanning"><code>DS_JAVA_VERSION</code></a> variable. + </p> + <p>You can view the + <a href="https://docs.gradle.org/current/userguide/compatibility.html#java">Gradle Java compatibility matrix</a> to see which version + of Gradle is selected for each Java version. Note that we only support switching to one of these pre-installed Gradle versions + for Java versions 13 to 17. + </p> + </li> + <li> + <p> + If your project <i>does use</i> a <code>gradlew</code> file, then the version of Gradle pre-installed in the analyzer image is + ignored, and the version specified in your <code>gradlew</code> file is used instead. + </p> + </li> + </ul> + </li> + <li> + <a id="exported-dependency-information-notes-3"></a> + <p> + These tests confirm that if a <code>gradlew</code> file does not exist, the version of <code>Gradle</code> pre-installed in the analyzer image is used. + </p> + </li> + <li> + <a id="exported-dependency-information-notes-4"></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. </p> </li> @@ -563,7 +598,7 @@ The following variables are used for configuring specific analyzers (used for a | `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. | | `DS_REMEDIATE` | `gemnasium` | `"true"` | Enable automatic remediation of vulnerable dependencies. | | `GEMNASIUM_LIBRARY_SCAN_ENABLED` | `gemnasium` | `"true"` | Enable detecting vulnerabilities in vendored JavaScript libraries. For now, `gemnasium` leverages [`Retire.js`](https://github.com/RetireJS/retire.js) to do this job. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350512) in GitLab 14.8. | -| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`, `16`. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`, `16`, `17`. | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | @@ -767,13 +802,13 @@ Here's an example dependency scanning report: } ``` -### CycloneDX reports +### CycloneDX Software Bill of Materials > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/350509) in GitLab 14.8 in [Beta](../../../policy/alpha-beta-support.md#beta-features). In addition to the [JSON report file](#reports-json-format), the [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) -Dependency Scanning tool outputs a [CycloneDX](https://cyclonedx.org/) report for -each supported lock or build file it detects. These CycloneDX reports are named +Dependency Scanning tool outputs a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM) for +each supported lock or build file it detects. These CycloneDX SBOMs are named `cyclonedx-<package-type>-<package-manager>.json`, and are saved in the same directory as the detected lock or build files. @@ -791,7 +826,7 @@ For example, if your project has the following structure: └── go.sum ``` -Then the Gemnasium scanner generates the following CycloneDX reports: +Then the Gemnasium scanner generates the following CycloneDX SBOMs: ```plaintext . @@ -809,23 +844,23 @@ Then the Gemnasium scanner generates the following CycloneDX reports: └── cyclonedx-go-go.json ``` -The CycloneDX reports can be downloaded [the same way as other job artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +The CycloneDX SBOMs can be downloaded [the same way as other job artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). -### Merging multiple CycloneDX Reports +### Merging multiple CycloneDX SBOMs -You can use a CI/CD job to merge multiple CycloneDX Reports into a single report. +You can use a CI/CD job to merge multiple CycloneDX SBOMs into a single SBOM. For example: ```yaml stages: - test - - merge-cyclonedx-reports + - merge-cyclonedx-sboms include: - template: Security/Dependency-Scanning.gitlab-ci.yml -merge cyclonedx reports: - stage: merge-cyclonedx-reports +merge cyclonedx sboms: + stage: merge-cyclonedx-sboms image: alpine:latest script: - wget https://github.com/CycloneDX/cyclonedx-cli/releases/download/v0.22.0/cyclonedx-linux-musl-x64 -O /usr/local/bin/cyclonedx-cli @@ -838,14 +873,14 @@ merge cyclonedx reports: ``` GitLab uses [CycloneDX Properties](https://cyclonedx.org/use-cases/#properties--name-value-store) -to store implementation-specific details in the metadata of each CycloneDX report, -such as the location of build and lock files. If multiple CycloneDX reports are merged together, +to store implementation-specific details in the metadata of each CycloneDX SBOM, +such as the location of build and lock files. If multiple CycloneDX SBOMs are merged together, this information is removed from the resulting merged file. NOTE: -CycloneDX reports are a [Beta](../../../policy/alpha-beta-support.md#beta-features) feature, +CycloneDX SBOMs are a [Beta](../../../policy/alpha-beta-support.md#beta-features) feature, and the reports are subject to change during the beta period. Do not build integrations -that rely on the format of these reports staying consistent, as the format might change +that rely on the format of these SBOMs staying consistent, as the format might change before the feature is made generally available. ## Versioning and release process @@ -892,11 +927,11 @@ import the following default dependency scanning analyzer images from `registry. your [local Docker container registry](../../packages/container_registry/index.md): ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/retire.js:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/bundler-audit:2 +registry.gitlab.com/security-products/gemnasium:2 +registry.gitlab.com/security-products/gemnasium-maven:2 +registry.gitlab.com/security-products/gemnasium-python:2 +registry.gitlab.com/security-products/retire.js:2 +registry.gitlab.com/security-products/bundler-audit:2 ``` The process for importing Docker images into a local offline Docker registry depends on @@ -961,7 +996,13 @@ BUNDLER_AUDIT_ADVISORY_DB_REF_NAME: "master" BUNDLER_AUDIT_ADVISORY_DB_URL: "gitlab.example.com/ruby-advisory-db.git" ``` -#### Python (setup tools) +#### Python (pip) + +If you need to install Python packages before the analyzer runs, you should use `pip install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies. + +#### Python (setuptools) + +If you need to install Python packages before the analyzer runs, you should use `python setup.py install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies. When using self-signed certificates for your private PyPi repository, no extra job configuration (aside from the template `.gitlab-ci.yml` above) is needed. However, you must update your `setup.py` to diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 89d3531bccd..b72f54b4493 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -22,7 +22,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 container type. Windows containers are not yet supported. +Our IaC scanning jobs require a Linux/amd64 container type. Windows containers are not yet supported. WARNING: If you use your own runners, make sure the Docker version installed @@ -58,7 +58,7 @@ as shown in the following table: |:---------------------------------------------------------------------------------------|:--------------------|:-------------------| | [Configure IaC Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | +| Presentation of JSON Report in merge request | **{dotted-circle}** | **{check-circle}** | | [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](../../application_security/security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -76,7 +76,12 @@ To configure IaC Scanning for a project you can: ### Configure IaC Scanning manually To enable IaC Scanning you must [include](../../../ci/yaml/index.md#includetemplate) the -[`SAST-IaC.latest.gitlab-ci.yml template`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST-IaC.latest.gitlab-ci.yml) provided as part of your GitLab installation. +[`SAST-IaC.latest.gitlab-ci.yml template`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST-IaC.latest.gitlab-ci.yml) provided as part of your GitLab installation. Here is an example of how to include it: + +```yaml +include: + - template: Security/SAST-IaC.latest.gitlab-ci.yml +``` The included template creates IaC scanning jobs in your CI/CD pipeline and scans your project's configuration files for possible vulnerabilities. diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 6a0b81335fd..ff548f1d29f 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -110,11 +110,9 @@ For more details about each of the security scanning tools, see their respective ### Override the default registry base address -By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the +By default, GitLab security scanners use `registry.gitlab.com/security-products` as the base address for Docker images. You can override this globally by setting the CI/CD variable -`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once, except -the container-scanning analyzer which uses -`registry.gitlab.com/security-products/container-scanning` as its registry. +`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. ### Use security scanning tools with merge request pipelines @@ -221,7 +219,7 @@ security issues: WARNING: This feature is in its end-of-life process. It is [deprecated](../../update/deprecations.md#vulnerability-check) for use in GitLab 14.8, and is planned for removal in GitLab 15.0. Users should migrate to the new -[Security Approval Policies](policies/#scan-result-policy-editor). +[Security Approval Policies](policies/scan-result-policies.md). To prevent a merge request introducing a security vulnerability in a project, enable the Vulnerability-Check rule. While this rule is enabled, additional merge request approval by @@ -397,6 +395,8 @@ any report artifacts that failed validation. ### Enable security report validation +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/354928) in GitLab 14.9, and planned for removal in GitLab 15.0. + To enable report artifacts validation, set the `VALIDATE_SCHEMA` environment variable to `"true"` for the desired jobs in the `.gitlab-ci.yml` file. diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 915e43d0fa5..7aeb094093c 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -179,7 +179,7 @@ set -ux # Specify needed analyzer images analyzers=${SAST_ANALYZERS:-"bandit eslint gosec"} -gitlab=registry.gitlab.com/gitlab-org/security-products/analyzers/ +gitlab=registry.gitlab.com/security-products/ for i in "${analyzers[@]}" do diff --git a/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png b/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png Binary files differdeleted file mode 100644 index b21d0330b2f..00000000000 --- a/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png Binary files differdeleted file mode 100644 index 31d5eb57228..00000000000 --- a/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/policy_rule_mode_v14_9.png b/doc/user/application_security/policies/img/policy_rule_mode_v14_9.png Binary files differnew file mode 100644 index 00000000000..8ca7547a33c --- /dev/null +++ b/doc/user/application_security/policies/img/policy_rule_mode_v14_9.png diff --git a/doc/user/application_security/policies/img/policy_yaml_mode_v14_9.png b/doc/user/application_security/policies/img/policy_yaml_mode_v14_9.png Binary files differnew file mode 100644 index 00000000000..1d71e8684e9 --- /dev/null +++ b/doc/user/application_security/policies/img/policy_yaml_mode_v14_9.png diff --git a/doc/user/application_security/policies/img/scan_result_policy_yaml_mode_v14_6.png b/doc/user/application_security/policies/img/scan_result_policy_yaml_mode_v14_6.png Binary files differdeleted file mode 100644 index 57649c58d8b..00000000000 --- a/doc/user/application_security/policies/img/scan_result_policy_yaml_mode_v14_6.png +++ /dev/null diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 803f3983b96..8a39220da35 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -64,13 +64,13 @@ The policy editor has two modes: - The visual _Rule_ mode allows you to construct and preview policy rules using rule blocks and related controls. -  +  - YAML mode allows you to enter a policy definition in `.yaml` format and is aimed at expert users and cases that the Rule mode doesn't support. -  +  You can use both modes interchangeably and switch between them at any time. If a YAML resource is incorrect or contains data not supported diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index 4e44162d5c5..c3778ac97de 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -8,14 +8,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w Project owners can use scan execution policies to require that security scans run on a specified schedule or with the project 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. +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. This feature has some overlap with [compliance framework pipelines](../../project/settings/#compliance-pipeline-configuration), 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](../#enforce-scan-execution). +NOTE: +Policy jobs 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`. + ## Scan execution policy editor NOTE: diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index 7857de8c780..8215316bcab 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -13,7 +13,7 @@ job is fully executed. ## Scan result policy editor -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77814) in GitLab 14.8 with a flag named `scan_result_policy`. Disabled by default. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77814) in GitLab 14.8. NOTE: Only project Owners have the [permissions](../../permissions.md#project-members-permissions) @@ -28,10 +28,7 @@ the bottom of the editor. All scan result policy changes are applied through a background job that runs once every 10 minutes. Allow up to 10 minutes for any policy changes committed to this project to take effect. -The policy editor only supports YAML mode. To follow work on Rule mode, see the epic -[Allow Users to Edit Rule-mode scan result policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363). - - +The [policy editor](index.md#policy-editor) supports YAML mode and rule mode. ## Scan result policies schema diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 3c0a2caf114..d3a79410eea 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -57,7 +57,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 container type. Windows containers are not yet supported. +Our SAST jobs require a Linux/amd64 container type. Windows containers are not yet supported. WARNING: If you use your own runners, make sure the Docker version installed @@ -315,7 +315,6 @@ To disable analyzer rules: 1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: - a `type` field, to name the predefined rule identifier that the targeted analyzer uses. - - a `value` field, to name the rule to be disabled. ##### Example: Disable predefined rules of SAST analyzers @@ -345,6 +344,9 @@ and `sobelow` by matching the `type` and `value` of identifiers: value = "sql_injection" ``` +Those vulnerabilities containing the provided type and value are now disabled, meaning +they won't be displayed in Merge Request nor the Vulnerability Report. + #### Override predefined analyzer rules To override analyzer rules: @@ -365,30 +367,40 @@ To override analyzer rules: ##### Example: Override predefined rules of SAST analyzers -In the following example, rules from `eslint` -and `gosec` are matched by the `type` and `value` of identifiers and -then overridden: +Before adding a ruleset, we verify which vulnerability will be overwritten by viewing the [`gl-sast-report.json`](#reports-json-format): + +```json +"identifiers": [ + { + "type": "gosec_rule_id", + "name": "Gosec Rule ID G307", + "value": "G307" + }, + { + "type": "CWE", + "name": "CWE-703", + "value": "703", + "url": "https://cwe.mitre.org/data/definitions/703.html" + } + ] +``` + +In the following example, rules from `gosec` are matched by the `type` +and `value` of identifiers and then overridden: ```toml -[eslint] - [[eslint.ruleset]] - [eslint.ruleset.identifier] - type = "eslint_rule_id" - value = "security/detect-object-injection" - [eslint.ruleset.override] - description = "OVERRIDDEN description" - message = "OVERRIDDEN message" - name = "OVERRIDDEN name" - severity = "Critical" [gosec] [[gosec.ruleset]] [gosec.ruleset.identifier] type = "CWE" - value = "CWE-79" + value = "703" [gosec.ruleset.override] severity = "Critical" ``` +If a vulnerability is found with a type `CWE` with a value of `703` then +the vulnerability severity is overwritten to `Critical`. + #### Synthesize a custom configuration To create a custom configuration, you can use passthrough chains. @@ -661,6 +673,25 @@ repositories and thus require credentials like username and password to download Depending on the analyzer, such credentials can be provided to it via [custom CI/CD variables](#custom-cicd-variables). +#### Using a CI/CD variable to pass username and password to a private Go repository + +If your Go project depends on private modules, see +[Fetch modules from private projects](../../packages/go_proxy/index.md#fetch-modules-from-private-projects) +for how to provide authentication over HTTPS. + +To specify credentials via `~/.netrc` provide a `before_script` containing the following: + +```yaml +gosec-sast: + before_script: + - | + cat <<EOF > ~/.netrc + machine gitlab.com + login $CI_DEPLOY_USER + password $CI_DEPLOY_PASSWORD + EOF +``` + #### Using a CI/CD variable to pass username and password to a private Maven repository If your private Maven repository requires login credentials, @@ -878,12 +909,12 @@ variables: ## Reports JSON format -SAST outputs a report file in JSON format. The report file contains details of all found vulnerabilities. -To download the report file, you can either: +SAST outputs a report file in JSON format. The report file contains details of all found vulnerabilities. +To download the report file, you can either: - Download the file from the CI/CD pipelines page. -- In the pipelines tab on merge requests, set [`artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. - +- In the pipelines tab on merge requests, set [`artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. + For information, see [Download job artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). For details of the report file's schema, see diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 2ce2d59898f..582497eb465 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -42,7 +42,7 @@ To run Secret Detection 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 Secret Detection jobs expect a Linux container type. Windows containers are not supported. +Our Secret Detection jobs expect a Linux/amd64 container type. Windows containers are not supported. WARNING: If you use your own runners, make sure the Docker version installed @@ -328,14 +328,6 @@ as part of your normal job definition. A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-cicd-variables)) can be set to change the behavior of the GitLab Secret Detection scan to run on the entire Git history of a repository. -We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a full history secret detection scan. -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=wDtc_K00Y0A">Walkthrough of historical secret detection scan</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/wDtc_K00Y0A" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - ## Running Secret Detection in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access @@ -450,9 +442,9 @@ secret_detection: ### `secret-detection` job fails with `ERR fatal: ambiguous argument` message -Your `secret-detection` job can fail with `ERR fatal: ambiguous argument` error if your -repository's default branch is unrelated to the branch the job was triggered for. +Your `secret-detection` job can fail with `ERR fatal: ambiguous argument` error if your +repository's default branch is unrelated to the branch the job was triggered for. See issue [!352014](https://gitlab.com/gitlab-org/gitlab/-/issues/352014) for more details. -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. +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. diff --git a/doc/user/application_security/secret_detection/post_processing.md b/doc/user/application_security/secret_detection/post_processing.md index 972558c3b95..643da47d876 100644 --- a/doc/user/application_security/secret_detection/post_processing.md +++ b/doc/user/application_security/secret_detection/post_processing.md @@ -56,7 +56,7 @@ A vendor revocation receiver service integrates with a GitLab instance to receiv 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`) diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 7b39002bac3..0b27760b4bb 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -27,8 +27,9 @@ On the vulnerability's page, you can: - [Change the vulnerability's status](#change-vulnerability-status). - [Create an issue](#create-an-issue-for-a-vulnerability). - [Link issues to the vulnerability](#linked-issues). -- [Resolve a vulnerability](#resolve-a-vulnerability), if a solution is - available. +- [Resolve a vulnerability](#resolve-a-vulnerability) if a solution is + available. +- [View security training specific to the detected vulnerability](#view-security-training-for-a-vulnerability). ## Vulnerability status values @@ -80,7 +81,7 @@ The issue is then opened so you can take further action. Prerequisites: - [Enable Jira integration](../../../integration/jira/index.md). - The **Enable Jira issues creation from vulnerabilities** option must be selected as part of the configuration. + The **Enable Jira issue creation from vulnerabilities** option must be selected as part of the configuration. - Each user must have a personal Jira user account with permission to create issues in the target project. To create a Jira issue for a vulnerability: @@ -159,3 +160,29 @@ To manually apply the patch that GitLab generated for a vulnerability: 1. Ensure your local project has the same commit checked out that was used to generate the patch. 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. + +## Enable security training for vulnerabilities + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6176) in GitLab 14.9. + +Security training helps your developers learn how to fix vulnerabilities. Developers can view security training from selected educational providers, relevant to the detected vulnerability. + +To enable security training for vulnerabilities in your project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. On the tab bar, select **Vulnerability Management**. +1. To enable a security training provider, turn on the toggle. + +## View security training for a vulnerability + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6176) in GitLab 14.9. + +If security training is enabled, the vulnerability page includes a training link relevant to the detected vulnerability. + +To view the security training for a vulnerability: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Vulnerability report**. +1. Select the vulnerability for which you want to view security training. +1. Select **View training**. diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index ba1455ab70a..eb59c289700 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Report **(ULTIMATE)** -The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It contains cumulative results of all successful jobs, regardless of whether the pipeline was successful. +The Vulnerability Report provides information about vulnerabilities from scans of the default branch. It contains cumulative results of all successful jobs, regardless of whether the pipeline was successful. The scan results from a pipeline are only ingested after all the jobs in the pipeline complete. Partial results for a pipeline with jobs in progress can be seen in the pipeline security tab. @@ -52,6 +52,7 @@ From the Vulnerability Report you can: - [View an issue raised for a vulnerability](#view-issues-raised-for-a-vulnerability). - [Change the status of vulnerabilities](#change-status-of-vulnerabilities). - [Export details of vulnerabilities](#export-vulnerability-details). +- [Manually add a vulnerability finding](#manually-add-a-vulnerability-finding). ## Vulnerability Report filters @@ -219,6 +220,25 @@ You can dismiss a vulnerability for the entire project: To undo this action, select a different status from the same menu. +## Manually add a vulnerability finding + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301003) in GitLab 14.9. Disabled by default. + +FLAG: +This feature is not enabled by default. To make it available, ask an administrator to +[enable the feature flag](../../feature_flags.md) named `new_vulnerability_form`. +On GitLab.com, this feature is not yet available. + +To add a new vulnerability finding from your project level Vulnerability Report page: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Vulnerability Report**. +1. Click on **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 +Group, Project, and Security Center Vulnerability Reports. To filter them, use the Generic Tool filter. + ## Operational vulnerabilities > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6345) in GitLab 14.6. |
