diff options
Diffstat (limited to 'doc/user/application_security')
33 files changed, 619 insertions, 256 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index c365c7f6bab..1bac636ac3f 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -101,7 +101,7 @@ a YAML snippet that you can paste in your GitLab CI/CD configuration. To generate an API Fuzzing configuration snippet: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **API Fuzzing** row, select **Enable API Fuzzing**. 1. Complete the fields. For details see [Available CI/CD variables](#available-cicd-variables). diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 10e16a173d8..1e9163a4c26 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -1,5 +1,4 @@ --- -type: reference, howto 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 @@ -7,11 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Security configuration **(FREE ALL)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in GitLab 12.6. -> - SAST configuration was [enabled](https://gitlab.com/groups/gitlab-org/-/epics/3659) in 13.3 and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in 13.4. -> - DAST Profiles feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40474) in 13.4. -> - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.10. -> - [Redesigned](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in 14.2. +> Security configuration page was [redesigned](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in GitLab 14.2. The **Security configuration** page lists the following for the security testing and compliance tools: @@ -40,7 +35,7 @@ all security features are configured by default. To view a project's security configuration: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. Select **Configuration history** to see the `.gitlab-ci.yml` file's history. diff --git a/doc/user/application_security/continuous_vulnerability_scanning/index.md b/doc/user/application_security/continuous_vulnerability_scanning/index.md new file mode 100644 index 00000000000..4094a0add28 --- /dev/null +++ b/doc/user/application_security/continuous_vulnerability_scanning/index.md @@ -0,0 +1,59 @@ +--- +stage: Secure +group: Composition 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 +--- + +# Continuous Vulnerability Scanning **(ULTIMATE EXPERIMENT)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371063) in GitLab 16.4 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) with two [features flags](../../../administration/feature_flags.md) named `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_sync`. Enabled by default. + +NOTE: +This feature is an [Experiment](../../../policy/experiment-beta-support.md#experiment) and subject to change without notice. +If you have any feedback, you can let us know in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/425072). + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flags](../../feature_flags.md) named `dependency_scanning_on_advisory_ingestion` and `package_metadata_advisory_sync`. +On GitLab.com, this feature is available. + +Continuous Vulnerability Scanning detects new vulnerabilities outside a pipeline. +Your projects are automatically scanned whenever advisories are added to the [`GitLab Advisory Database`](https://advisories.gitlab.com/). +Projects that depend on the affected components have new vulnerabilities automatically created. + +Continuous Vulnerability Scanning detects vulnerabilities in the latest CycloneDX SBOM reports for the default branch. +[Dependency Scanning](../dependency_scanning/index.md) is used to generate these reports. + +## Configuration + +To enable Continuous Vulnerability Scanning: + +- Enable the Continuous Vulnerability Scanning setting in the project's [security configuration](../configuration/index.md). +- Enable [Dependency Scanning](../dependency_scanning/index.md#configuration) and ensure that its prerequisites are met. + +On GitLab self-managed only, you can [choose package registry metadata to sync](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the Admin Area for the GitLab instance. + +### Requirements for offline environments + +For self-managed GitLab instances in an environment with limited, restricted, or intermittent access to external resources through the internet, +some adjustments are required to successfully scan CycloneDX reports for vulnerabilities. +For more information, see the offline [quick start guide](../../../topics/offline/quick_start_guide.md#enabling-the-package-metadata-database). + +## Supported languages and package managers + +The supported files and versions are the ones supported by +[Dependency Scanning](../dependency_scanning/index.md#supported-languages-and-package-managers). + +Go pseudo versions are not supported. A project dependency that references a Go pseudo version is never considered as affected. This might result in false negatives. + +## Checking new vulnerabilities + +New vulnerabilities detected by Continuous Vulnerability Scanning are visible on the [Vulnerability Report](../vulnerability_report/index.md). +However, they are not listed on the [Dependency List](../dependency_list/index.md) or in the pipeline where the affected SBOM component was detected. + +After an advisory is added to the [`GitLab Advisory Database`](https://advisories.gitlab.com/), +it might take a few hours before the corresponding vulnerabilities are added to your projects. + +## Contributing to the vulnerability database + +To find a vulnerability, you can search the [`GitLab Advisory Database`](https://advisories.gitlab.com/). +You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 59bd2b1ffb3..599203dedcc 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -58,7 +58,7 @@ You can use the following fuzzing engines to test the specified languages. To confirm the status of coverage-guided fuzz testing: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Coverage Fuzzing** section the status is: - **Not configured** @@ -172,7 +172,7 @@ artifacts files you can download from the CI/CD pipeline. Also, a project member To view details of the corpus registry: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Coverage Fuzzing** section, select **Manage corpus**. @@ -200,7 +200,7 @@ provided by the `COVFUZZ_CORPUS_NAME` variable. The corpus is updated on every p To upload an existing corpus file: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Coverage Fuzzing** section, select **Manage corpus**. 1. Select **New corpus**. diff --git a/doc/user/application_security/dast/authentication.md b/doc/user/application_security/dast/authentication.md index b13b41e4a37..aed4066bc52 100644 --- a/doc/user/application_security/dast/authentication.md +++ b/doc/user/application_security/dast/authentication.md @@ -412,9 +412,12 @@ Authentication failed because a home page should be displayed after login. Inste ### Configure the authentication report +WARNING: +The authentication report can contain sensitive information such as the credentials used to perform the login. + An authentication report can be saved as a CI/CD job artifact to assist with understanding the cause of an authentication failure. -The report contains steps during the login process, HTTP requests and responses, the Document Object Model (DOM) and screenshots. +The report contains steps performed during the login process, HTTP requests and responses, the Document Object Model (DOM) and screenshots.  diff --git a/doc/user/application_security/dast/checks/113.1.md b/doc/user/application_security/dast/checks/113.1.md new file mode 100644 index 00000000000..44c3be330f2 --- /dev/null +++ b/doc/user/application_security/dast/checks/113.1.md @@ -0,0 +1,27 @@ +--- +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 Neutralization of CRLF Sequences in HTTP Headers + +## Description + +By inserting Carriage Return / Line Feed (CRLF) characters, malicious users could potentially inject arbitrary data into HTTP responses. By modifying HTTP responses, attackers could conduct cross-site scripting or cache poisoning attacks against other users of the system. + +## Remediation + +User input should never be used in constructing HTTP header responses without some form +of validation against newlines. This includes URLs supplied by the user for HTTP redirects. + +## Details + +| ID | Aggregated | CWE | Type | Risk | +|:---|:--------|:--------|:--------|:--------| +| 113.1 | false | 113 | Active | high | + +## Links + +- [OWASP](https://owasp.org/www-community/attacks/HTTP_Response_Splitting) +- [CWE](https://cwe.mitre.org/data/definitions/113.html) diff --git a/doc/user/application_security/dast/checks/16.7.md b/doc/user/application_security/dast/checks/16.7.md index edaace407ae..d407234d2c2 100644 --- a/doc/user/application_security/dast/checks/16.7.md +++ b/doc/user/application_security/dast/checks/16.7.md @@ -22,8 +22,8 @@ Only three directives are applicable for the `Strict-Transport-Security` header. 1. `includeSubDomains`: This optional, valueless directive signals that the policy applies to this host as well as any subdomains found under this host's domain. 1. `preload`: While not part of the specification, setting this optional value allows major browser organizations to add this site into the browser's preloaded set of HTTPS sites. This requires further action on behalf of the website operator to submit their domain to the browser's HSTS preload list. See [hstspreload.org](https://hstspreload.org/) for more information. -Invalid directives, or the `Strict-Transport-Security` header appearing more than once (if the -values are different) is considered invalid. +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). diff --git a/doc/user/application_security/dast/checks/16.9.md b/doc/user/application_security/dast/checks/16.9.md index c63a620794e..b0ba502b578 100644 --- a/doc/user/application_security/dast/checks/16.9.md +++ b/doc/user/application_security/dast/checks/16.9.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Description A `Content-Security-Policy-Report-Only` (CSPRO) was identified on the target site. CSP-Report-Only headers -aid in determining how to implement a `Content-Security-Policy` that does not disrupt use of the target +aid in determining how to implement a `Content-Security-Policy` that does not disrupt normal use of the target site. ## Remediation diff --git a/doc/user/application_security/dast/checks/index.md b/doc/user/application_security/dast/checks/index.md index 1b3ce45dc43..035f4a4b486 100644 --- a/doc/user/application_security/dast/checks/index.md +++ b/doc/user/application_security/dast/checks/index.md @@ -4,7 +4,7 @@ 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 --- -# DAST browser-based crawler vulnerability checks **(ULTIMATE ALL)** +# DAST browser-based crawler vulnerability checks **(ULTIMATE)** 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. @@ -167,4 +167,5 @@ The [DAST browser-based crawler](../browser_based.md) provides a number of vulne | ID | Check | Severity | Type | |:---|:------|:---------|:-----| +| [113.1](113.1.md) | Improper Neutralization of CRLF Sequences in HTTP Headers | High | Active | | [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/index.md b/doc/user/application_security/dast/index.md index 24aadd14dd1..4ec693593fb 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -81,8 +81,8 @@ analyzer-specific configuration instructions. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. -Detected vulnerabilities are shown in [Merge requests](../index.md#view-security-scan-information-in-merge-requests), the [Pipeline security tab](../index.md#view-security-scan-information-in-the-pipeline-security-tab), -and the [Vulnerability report](../index.md#view-security-scan-information-in-the-vulnerability-report). +Detected vulnerabilities appear in [merge requests](../index.md#merge-request), the [pipeline security tab](../index.md#pipeline-security-tab), +and the [vulnerability report](../index.md#vulnerability-report). 1. To see all vulnerabilities detected, either: - From your project, select **Security & Compliance**, then **Vulnerability report**. diff --git a/doc/user/application_security/dast/proxy-based.md b/doc/user/application_security/dast/proxy-based.md index 7538bd38d9f..86af7d4c5da 100644 --- a/doc/user/application_security/dast/proxy-based.md +++ b/doc/user/application_security/dast/proxy-based.md @@ -89,7 +89,7 @@ In this method you manually edit the existing `.gitlab-ci.yml` file. Use this me To include the DAST template: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Build > Pipeline editor**. 1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file. @@ -156,7 +156,7 @@ snippet is created that you paste into the `.gitlab-ci.yml` file. To configure DAST using the UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Enable DAST** or **Configure DAST**. @@ -467,6 +467,9 @@ The DAST job does not require the project's repository to be present when runnin > - Runner tags selection [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345430) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `on_demand_scans_runner_tags. Disabled by default. > - Runner tags selection [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111499) in GitLab 16.3. +WARNING: +On-demand scans are not available when GitLab is running in FIPS mode. + An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger the scan. You must either start it manually, or schedule it to run. For on-demand DAST scans, a [site profile](#site-profile) defines **what** is to be scanned, and a @@ -483,7 +486,7 @@ An on-demand scan can be run in active or passive mode: To view on-demand scans: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Secure > On-demand scans**. On-demand scans are grouped by their status. The scan library contains all available on-demand @@ -499,7 +502,7 @@ Prerequisites: To run an existing on-demand scan: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > On-demand scans**. 1. Select the **Scan library** tab. 1. In the scan's row, select **Run scan**. @@ -522,7 +525,7 @@ Create an on-demand scan to: To create an on-demand DAST scan: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. On the left sidebar, select **Search or go to** and find your project or group. 1. Select **Secure > On-demand scans**. 1. Select **New scan**. 1. Complete the **Scan name** and **Description** fields. @@ -550,7 +553,7 @@ The on-demand DAST scan runs as specified and the project's dashboard shows the To view details of an on-demand scan: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > On-demand scans**. 1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. @@ -559,7 +562,7 @@ To view details of an on-demand scan: To edit an on-demand scan: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > On-demand scans**. 1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. @@ -570,7 +573,7 @@ To edit an on-demand scan: To delete an on-demand scan: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > On-demand scans**. 1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. @@ -632,7 +635,7 @@ equivalent in functionality, so use whichever is most suitable: To create a site profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select **New > Site profile**. @@ -654,7 +657,7 @@ When a validated site profile's file, header, or meta tag is edited, the site's To edit a site profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Site Profiles** tab. @@ -669,7 +672,7 @@ See [Scan execution policies](../policies/scan-execution-policies.md) for more i To delete a site profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Site Profiles** tab. @@ -687,7 +690,7 @@ Prerequisites: To validate a site profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Site Profiles** tab. @@ -724,7 +727,7 @@ page. To retry a site profile's failed validation: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Site Profiles** tab. @@ -738,7 +741,7 @@ have their validation status revoked. To revoke a site profile's validation status: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Beside the validated profile, select **Revoke validation**. @@ -809,7 +812,7 @@ A scanner profile contains: To create a scanner profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select **New > Scanner profile**. @@ -824,7 +827,7 @@ For more information, see [Scan execution policies](../policies/scan-execution-p To edit a scanner profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Scanner profiles** tab. @@ -840,7 +843,7 @@ page. For more information, see [Scan execution policies](../policies/scan-execu To delete a scanner profile: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dynamic Application Security Testing (DAST)** section, select **Manage profiles**. 1. Select the **Scanner profiles** tab. diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png b/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png Binary files differdeleted file mode 100644 index 5b2bd985ce4..00000000000 --- a/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png +++ /dev/null diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png b/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png Binary files differindex f3a8f3d8d5d..7e4e80f9c00 100644 --- a/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png +++ b/doc/user/application_security/dependency_list/img/dependency_list_v16_3.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index a55f26f529d..d8726cbd456 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -9,17 +9,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - System dependencies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6698) in GitLab 14.6. > - Group-level dependency list [introduced](https://gitlab.com/groups/gitlab-org/-/epics/8090) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `group_level_dependencies`. Disabled by default. +> - Group-level dependency list [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/411257) in GitLab 16.4. -Use the dependency list to review your project or group's dependencies and key -details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. +Use the dependency list to review your project or group's dependencies and key details about those +dependencies, including their known vulnerabilities. This list is a collection of dependencies in your +project, including existing and new findings. This information is sometimes referred to as a +Software Bill of Materials, SBOM, or BOM. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an overview, see [Project Dependency](https://www.youtube.com/watch?v=ckqkn9Tnbw4). -To see the dependency list, go to your project or group and select **Secure > Dependency list**. - -This information is sometimes referred to as a Software Bill of Materials, SBOM, or BOM. - ## Prerequisites To view your project's dependencies, ensure you meet the following requirements: @@ -34,21 +33,33 @@ To view your project's dependencies, ensure you meet the following requirements: You should not change the default behavior of allowing the [application security jobs](../../application_security/index.md#application-coverage) to fail. -## View a project's dependencies +## View project dependencies + +To view the dependencies of a project or all projects in a group: - +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Secure > Dependency list**. -GitLab displays dependencies with the following information: +Details of each dependency are listed, sorted by decreasing severity of vulnerabilities (if any). You can sort the list instead by component name or packager. | Field | Description | -|-----------|-------------| +|:----------|:-----------| | Component | The dependency's name and version. | | Packager | The packager used to install the dependency. | | Location | For system dependencies, this lists the image that was scanned. For application dependencies, this shows a link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. | -| License | Links to dependency's software licenses. | +| License<sup>1</sup> | Links to dependency's software licenses. A warning badge that includes the number of vulnerabilities detected in the dependency. | +| Projects<sup>2</sup> | Links to the project with the dependency. If multiple projects have the same dependency, the total number of these projects is shown. To go to a project with this dependency, select the **Projects** number, then search for and select its name. The project search feature is supported only on groups that have up to 600 occurrences in their group hierarchy. | + +<html> +<small>Footnotes: + <ol> + <li>Project-level only.</li> + <li>Group-level only.</li> + </ol> +</small> +</html> -Displayed dependencies are initially sorted by the severity of their known vulnerabilities, if any. They -can also be sorted by name or by the packager that installed them. + ### Vulnerabilities @@ -60,7 +71,7 @@ select the vulnerability's description. The [vulnerability's details](../vulnera ### Dependency paths The dependency list shows the path between a dependency and a top-level dependency it's connected -to, if any. There are many possible paths connecting a transient dependency to top-level +to, if any. Multiple paths may connect a transient dependency to top-level dependencies, but the user interface shows only one of the shortest paths. NOTE: @@ -73,42 +84,20 @@ Dependency paths are supported for the following package managers: - [NuGet](https://www.nuget.org/) - [Yarn 1.x](https://classic.yarnpkg.com/lang/en/) - [sbt](https://www.scala-sbt.org) +- [Conan](https://conan.io) ### Licenses -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10536) in GitLab 12.3. - If the [Dependency Scanning](../../application_security/dependency_scanning/index.md) CI job is configured, -[discovered licenses](../../compliance/license_scanning_of_cyclonedx_files/index.md#enable-license-scanning) are displayed on this page. - -## View a group's dependencies - -FLAG: -On self-managed GitLab, and GitLab.com the feature is disabled by default. To show the feature, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `group_level_dependencies`. - - - -GitLab displays dependencies with the following information: - -| Field | Description | -|-----------|-------------| -| Component | The dependency's name and version. | -| Packager | The packager used to install the dependency. | -| Location | For operating system dependencies, this lists the image that was scanned. For application dependencies, this shows a link to the packager-specific lock file in your project that declared the dependency. It also shows the [dependency path](#dependency-paths) to a top-level dependency, if any, and if supported. If there are multiple locations, the total number of locations is displayed. | -| Projects | Links to the project related to the dependency. If there are multiple projects, the total number of projects is displayed. | - -Displayed dependencies are initially sorted by packager. They -can also be sorted by name. - -## Downloading the dependency list - -You can download the full list of dependencies and their details in -`JSON` format. +[discovered licenses](../../compliance/license_scanning_of_cyclonedx_files/index.md) are displayed on this page. -### In the UI +## Download the dependency list -You can download your group's or 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. +You can download the full list of dependencies and their details in JSON format. The dependency +list shows only the results of the last successful pipeline that ran on the default branch. -### Using the API +To download the dependency list: -You can download your project's list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the [Gemnasium family of analyzers](../dependency_scanning/index.md#dependency-analyzers) and not any other of the GitLab dependency analyzers. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project or group. +1. Select **Secure > Dependency list**. +1. Select **Export**. diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 5a2394113cb..f8bd5b99cb6 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -18,6 +18,8 @@ Dependency Scanning can run in the development phase of your application's life pipeline runs, vulnerabilities are identified and compared between the source and target branches. Vulnerabilities and their severity are listed in the merge request, enabling you to proactively address the risk to your application, before the code change is committed. +Vulnerabilities can also be identified outside a pipeline by +[Continuous Vulnerability Scanning](../continuous_vulnerability_scanning/index.md). GitLab offers both Dependency Scanning and [Container Scanning](../container_scanning/index.md) to ensure coverage for all of these dependency types. To cover as much of your risk area as possible, @@ -327,7 +329,7 @@ GitLab analyzers obtain dependency information using one of the following two me The following package managers use lockfiles that GitLab analyzers are capable of parsing directly: -| Package Manager | Supported File Format Versions | Tested Versions | +| Package Manager | Supported File Format Versions | Tested Package Manager Versions | | ------ | ------ | ------ | | Bundler | Not applicable | [1.17.3](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/ruby-bundler/default/Gemfile.lock#L118), [2.1.4](https://gitlab.com/gitlab-org/security-products/tests/ruby-bundler/-/blob/bundler2-FREEZE/Gemfile.lock#L118) | | Composer | Not applicable | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/php-composer/default/composer.lock) | @@ -335,7 +337,7 @@ The following package managers use lockfiles that GitLab analyzers are capable o | 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, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-2">2</a></b></sup> | [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<sup><b><a href="#notes-regarding-parsing-lockfiles-3">3</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) | -| pnpm | v5.3, v5.4, v6 | [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-pnpm/default/pnpm-lock.yaml#L1), [8.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/pnpm/fixtures/v6/simple/pnpm-lock.yaml#L1) | +| pnpm | v5, v6 | [7.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-pnpm/default/pnpm-lock.yaml#L1), [8.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/scanner/parser/pnpm/fixtures/v6/simple/pnpm-lock.yaml#L1) | | yarn | v1, v2<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup>, v3<sup><b><a href="#notes-regarding-parsing-lockfiles-4">4</a></b></sup> | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/classic/default/yarn.lock#L2), [2.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v2/default/yarn.lock), [3.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/js-yarn/berry/v3/default/yarn.lock) | | Poetry | v1 | [1.x](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/blob/master/qa/fixtures/python-poetry/default/poetry.lock) | @@ -559,7 +561,7 @@ always take the latest dependency scanning artifact available. To enable Dependency Scanning in a project, you can create a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Dependency Scanning** row, select **Configure with a merge request**. 1. Review and merge the merge request to enable Dependency Scanning. @@ -1019,62 +1021,7 @@ variables: See explanations of the variables above in the [configuration section](#configuration). -### Specific settings for languages and package managers - -See the following sections for configuring specific languages and package managers. - -#### 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 -ensure that it can reach your private repository. Here is an example configuration: - -1. Update `setup.py` to create a `dependency_links` attribute pointing at your private repository for each - dependency in the `install_requires` list: - - ```python - install_requires=['pyparsing>=2.0.3'], - dependency_links=['https://pypi.example.com/simple/pyparsing'], - ``` - -1. Fetch the certificate from your repository URL and add it to the project: - - ```shell - printf "\n" | openssl s_client -connect pypi.example.com:443 -servername pypi.example.com | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt - ``` - -1. Point `setup.py` at the newly downloaded certificate: - - ```python - import setuptools.ssl_support - setuptools.ssl_support.cert_paths = ['internal.crt'] - ``` - -#### Python (Pipenv) - -If running in a limited network connectivity environment, you must configure the `PIPENV_PYPI_MIRROR` -variable to use a private PyPi mirror. This mirror must contain both default and development dependencies. - -```yaml -variables: - PIPENV_PYPI_MIRROR: https://pypi.example.com/simple -``` - -<!-- markdownlint-disable MD044 --> -Alternatively, if it's not possible to use a private registry, you can load the required packages -into the Pipenv virtual environment cache. For this option, the project must check in the -`Pipfile.lock` into the repository, and load both default and development packages into the cache. -See the example [python-pipenv](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/41cc017bd1ed302f6edebcfa3bc2922f428e07b6/.gitlab-ci.yml#L20-42) -project for an example of how this can be done. -<!-- markdownlint-enable MD044 --> - -## Hosting a copy of the `gemnasium_db` advisory database +### Hosting a copy of the `gemnasium_db` advisory database The [`gemnasium_db`](https://gitlab.com/gitlab-org/security-products/gemnasium-db) Git repository is used by `gemnasium`, `gemnasium-maven`, and `gemnasium-python` as the source of vulnerability data. @@ -1085,7 +1032,7 @@ one of the following: - [Host a copy of the advisory database](#host-a-copy-of-the-advisory-database) - [Use a local clone](#use-a-local-clone) -### Host a copy of the advisory database +#### Host a copy of the advisory database If [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is not reachable from within the environment, the user can host their own Git copy. Then the analyzer can be @@ -1098,7 +1045,7 @@ variables: ... ``` -### Use a local clone +#### Use a local clone If a hosted copy is not possible, then the user can clone [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) or create an archive before the scan and point the analyzer to the directory (using: @@ -1129,6 +1076,61 @@ variables: GRADLE_CLI_OPTS: "-Dhttps.proxyHost=squid-proxy -Dhttps.proxyPort=3128 -Dhttp.proxyHost=squid-proxy -Dhttp.proxyPort=3128 -Dhttp.nonProxyHosts=localhost" ``` +## Specific settings for languages and package managers + +See the following sections for configuring specific languages and package managers. + +### 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 +ensure that it can reach your private repository. Here is an example configuration: + +1. Update `setup.py` to create a `dependency_links` attribute pointing at your private repository for each + dependency in the `install_requires` list: + + ```python + install_requires=['pyparsing>=2.0.3'], + dependency_links=['https://pypi.example.com/simple/pyparsing'], + ``` + +1. Fetch the certificate from your repository URL and add it to the project: + + ```shell + printf "\n" | openssl s_client -connect pypi.example.com:443 -servername pypi.example.com | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt + ``` + +1. Point `setup.py` at the newly downloaded certificate: + + ```python + import setuptools.ssl_support + setuptools.ssl_support.cert_paths = ['internal.crt'] + ``` + +### Python (Pipenv) + +If running in a limited network connectivity environment, you must configure the `PIPENV_PYPI_MIRROR` +variable to use a private PyPi mirror. This mirror must contain both default and development dependencies. + +```yaml +variables: + PIPENV_PYPI_MIRROR: https://pypi.example.com/simple +``` + +<!-- markdownlint-disable MD044 --> +Alternatively, if it's not possible to use a private registry, you can load the required packages +into the Pipenv virtual environment cache. For this option, the project must check in the +`Pipfile.lock` into the repository, and load both default and development packages into the cache. +See the example [python-pipenv](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/41cc017bd1ed302f6edebcfa3bc2922f428e07b6/.gitlab-ci.yml#L20-42) +project for an example of how this can be done. +<!-- markdownlint-enable MD044 --> + ## Warnings We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. diff --git a/doc/user/application_security/gitlab_advisory_database/index.md b/doc/user/application_security/gitlab_advisory_database/index.md new file mode 100644 index 00000000000..e59eaccf8f8 --- /dev/null +++ b/doc/user/application_security/gitlab_advisory_database/index.md @@ -0,0 +1,95 @@ +--- +stage: Secure +group: Vulnerability Research +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 +--- + +# GitLab Advisory Database + +The [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db) serves as a repository for security advisories related to software dependencies. + +The database is an essential component of both [Dependency Scanning](../dependency_scanning/index.md) and [Container Scanning](../container_scanning/index.md). + +A free and open-source version of the GitLab Advisory Database is also available as [GitLab Advisory Database (Open Source Edition)](https://gitlab.com/gitlab-org/advisories-community). However, there is a 30-day delay in updates. + +## Standardization + +In our advisories, we adopt standardized practices to effectively communicate vulnerabilities and their impact. + +- [CVE](../terminology/index.md#cve) +- [CVSS](../terminology/index.md#cvss) +- [CWE](../terminology/index.md#cwe) + +## Explore the database + +To view the database content, go to the [GitLab Advisory Database](https://advisories.gitlab.com) home page. On the home page you can: + +- Search the database, by identifier, package name, and description. +- View advisories that were added recently. +- View statistical information, including coverage and update frequency. + +### Search + +Each advisory has a page with the following details: + +- **Identifiers**: Public identifiers. For example, CVE ID, GHSA ID, or the GitLab internal ID (`GMS-<year>-<nr>`). +- **Package Slug**: Package type and package name separated by a slash. +- **Vulnerability**: A short description of the security flaw. +- **Description**: A detailed description of the security flaw and potential risks. +- **Affected Versions**: The affected versions. +- **Solution**: How to remediate the vulnerability. +- **Last Modified**: The date when the advisory was last modified. + +### Statistics + +The home page also offers a [statistic section](https://advisories.gitlab.com/stats/index.html) that provides valuable insights into advisory distribution, the origins of vulnerabilities, dependency scanning coverage, and timelines for vulnerability resolution. + +## Open Source Edition + +GitLab provides a free and open-source version of the database, the [GitLab Advisory Database (Open Source Edition)](https://gitlab.com/gitlab-org/advisories-community). + +The open-source version is a time-delayed clone of the GitLab Advisory Database, MIT-licensed and contains all advisories from the GitLab Advisory Database that are older than 30 days or with the `community-sync` flag. + +## Integrations + +- [Dependency Scanning](../dependency_scanning/index.md) +- [Container Scanning](../container_scanning/index.md) +- Third-party tools + +NOTE: +GitLab Advisory Database Terms prohibit the use of data contained in the GitLab Advisory Database by third-party tools. Third-party integrators can use the MIT-licensed, time-delayed [repository clone](https://gitlab.com/gitlab-org/advisories-community) instead. + +### How the database can be used + +As an example, we highlight the use of the database as a source for an Advisory Ingestion process as part of Continuous Vulnerability Scans. + +```mermaid +flowchart TB + subgraph Dependency Scanning + A[GitLab Advisory Database] + end + subgraph Container Scanning + C[GitLab Advisory Database \n Open Source Edition \n integrated into Trivy] + end + A --> B{Ingest} + C --> B + B --> |store| D{{"Cloud Storage \n (NDJSON format)"}} + F[\GitLab Instance/] --> |pulls data| D + F --> |stores| G[(Relational Database)] +``` + +## Maintenance + +The [Vulnerability Research](https://about.gitlab.com/handbook/engineering/development/sec/secure/vulnerability-research/) team is responsible for the maintenance and regular updates of the GitLab Advisory Database and the GitLab Advisory Database (Open Source Edition). + +Community contributions are accessible in [advisories-community](https://gitlab.com/gitlab-org/advisories-community) via the `community-sync` flag. + +## Contributing to the vulnerability database + +If you know about a vulnerability that is not listed, you can contribute to the GitLab Advisory Database by either opening an issue or submit the vulnerability. + +For more information, see [Contribution Guidelines](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/CONTRIBUTING.md). + +## License + +The GitLab Advisory Database is freely accessible in accordance with the [GitLab Advisory Database Terms](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/LICENSE.md#gitlab-advisory-database-term). diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index 334e8c28378..8cdeeb92e09 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -121,7 +121,7 @@ The **Configure with a merge request** button been temporarily disabled due to a To enable IaC Scanning in a project, you can create a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Infrastructure as Code (IaC) Scanning** row, select **Configure with a merge request**. 1. Review and merge the merge request to enable IaC Scanning. @@ -130,7 +130,7 @@ Pipelines now include an IaC Scanning job. ## Customize rulesets **(ULTIMATE ALL)** -> [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. +> Support for overriding rules [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) in GitLab 14.8. You can customize the default IaC Scanning rules provided with GitLab. diff --git a/doc/user/application_security/img/security_widget_v13_7.png b/doc/user/application_security/img/security_widget_v13_7.png Binary files differdeleted file mode 100644 index fb1eaf9a2be..00000000000 --- a/doc/user/application_security/img/security_widget_v13_7.png +++ /dev/null diff --git a/doc/user/application_security/img/security_widget_v16_4.png b/doc/user/application_security/img/security_widget_v16_4.png Binary files differnew file mode 100644 index 00000000000..dfed372ba31 --- /dev/null +++ b/doc/user/application_security/img/security_widget_v16_4.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 615ff7e3fda..62155e07fbc 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -103,7 +103,7 @@ 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. GitLab monitors this job through an internal alert that tells the engineering team when the database becomes more than 48 hours old. For more information, see the [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. | +| [Dynamic Application Security Testing (DAST)](dast/index.md) | [DAST proxy-based](dast/proxy-based.md) and [browser-based](dast/browser_based.md) engines are updated on a periodic basis. [DAST proxy-based](dast/proxy-based.md) analyzer downloads the scanning rules at scan runtime. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L27). [DAST browser-based](dast/browser_based.md) rules run [different vulnerability checks](dast/checks/index.md). | | [Secret Detection](secret_detection/index.md#detected-secrets) | GitLab maintains the [detection rules](secret_detection/index.md#detected-secrets) and [accepts community contributions](secret_detection/index.md#adding-new-patterns). The scanning engine is updated at least once per month if a relevant update is available. | | [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. | @@ -223,20 +223,30 @@ We do not recommend changing the job [`allow_failure` setting](../../ci/yaml/ind The artifact generated by the secure analyzer contains all findings it discovers on the target branch, regardless of whether they were previously found, dismissed, or completely new (it puts in everything that it finds). -## View security scan information in merge requests **(FREE ALL)** +## View security scan information + +Security scan information appears in multiple locations and formats: + +- Merge request +- Pipeline security tab +- Security dashboard +- Vulnerability report +- GitLab Workflow extension for VS Code + +### Merge request **(FREE ALL)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Free 13.5. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. > - Report download dropdown list [added](https://gitlab.com/gitlab-org/gitlab/-/issues/273418) in 13.7. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249550) in GitLab 13.9. -### All tiers +#### All tiers Merge requests which have run security scans let you know that the generated reports are available to download. To download a report, select **Download results**, and select the desired report. - + Security scans produce at least one of these [CI `artifacts:reports` types](../../ci/yaml/artifacts_reports.md): @@ -248,7 +258,9 @@ Security scans produce at least one of these [CI `artifacts:reports` types](../. - `artifacts:reports:sast` - `artifacts:reports:secret_detection` -### Ultimate +In the Free tier, the reports above aren't parsed by GitLab. As a result, the widget does not change based on the results of the security scans. + +#### Ultimate 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 commit when the feature branch was created from the target branch. @@ -263,26 +275,32 @@ findings, select **View full report** to go directly to the **Security** tab in  -## View security scan information in the pipeline Security tab +### Pipeline security tab A pipeline's security tab lists all findings in the current branch. It includes new findings introduced by this branch and existing vulnerabilities already present when you created the branch. These results likely do not match the findings displayed in the Merge Request security widget, as those do not include the existing vulnerabilities. Refer to [View vulnerabilities in a pipeline](vulnerability_report/pipeline.md) for more information. -## View security scan information in the Security Dashboard +### Security dashboard -The Security Dashboard show vulnerabilities present in a project's default branch. Data is updated every 24 hours. Vulnerability count updates resulting from any feature branches introducing new vulnerabilities that are merged to default are included after the daily data refresh. +The security dashboard shows the vulnerabilities on a project's default branch. Data is updated every 24 hours. Vulnerability count updates resulting from any feature branches introducing new vulnerabilities that are merged to default are included after the daily data refresh. For more details, see [Security Dashboard](security_dashboard/index.md). -## View security scan information in the Vulnerability Report +### Vulnerability report -The vulnerability report shows the results of the last completed pipeline on the default branch. It is updated on every pipeline completion. All detected vulnerabilities are shown as well as any previous ones that are no longer detected in the latest scan. Vulnerabilities that are no longer detected may have been remediated or otherwise removed and can be marked as `Resolved` after proper verification. Vulnerabilities that are no longer detected are denoted with an icon for filtering and review. +The vulnerability report shows the results of the last completed pipeline on the default branch. It is updated on every pipeline completion. All detected vulnerabilities are shown and any previous ones that are no longer detected in the latest scan. Vulnerabilities that are no longer detected may have been remediated or otherwise removed and can be marked as `Resolved` after proper verification. Vulnerabilities that are no longer detected are denoted with an icon for filtering and review. By default, the vulnerability report does not show vulnerabilities of `dismissed` or `resolved` status so you can focus on open vulnerabilities. You can change the Status filter to see these. [Read more about the Vulnerability report](vulnerability_report/index.md). +### GitLab Workflow extension for VS Code + +You can now see security findings directly in Visual Studio Code (VS Code) using [GitLab Workflow VS Code extension](../../editor_extensions/visual_studio_code/index.md), just as you would in a merge request. + +For more details, see [extension page](https://marketplace.visualstudio.com/items?itemName=gitlab.gitlab-workflow#security-findings). + ## Security approvals in merge requests > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in GitLab 12.2. @@ -453,7 +471,7 @@ 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) +- [Scan information in merge requests](#merge-request) - [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#view-vulnerabilities-over-time-for-a-group) @@ -526,7 +544,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, SAST IaC, 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 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. | +| **Schedulable** | Has to be scheduled through a scheduled pipeline on each project. | 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. | @@ -721,8 +739,8 @@ Instructions are available in the [legacy template project](https://gitlab.com/g In these circumstances, that the job succeeds is the default behavior. The job's status indicates success or failure of the analyzer itself. Analyzer results are displayed in the [job logs](../../ci/jobs/index.md#expand-and-collapse-job-log-sections), -[Merge Request widget](#view-security-scan-information-in-merge-requests) or -[Security Dashboard](security_dashboard/index.md). +[merge request widget](#merge-request), or +[security dashboard](security_dashboard/index.md). ### Error: job `is used for configuration only, and its script should not be executed` diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 25e2f523f08..84c28d4008c 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -58,7 +58,7 @@ to select, edit, and unlink a security policy project. As a project owner, take the following steps to create or edit an association between your current project and a project that you would like to designate as the security policy project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**. 1. Select **Edit Policy Project**, and search for and select the project you would like to link from the dropdown list. @@ -82,7 +82,7 @@ policies for all available environments. You can check a policy's information (for example, description or enforcement status), and create and edit deployed policies: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**.  @@ -93,7 +93,7 @@ status), and create and edit deployed policies: You can use the policy editor to create, edit, and delete policies: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Policies**. - To create a new policy, select **New policy** which is located in the **Policies** page's header. You can then select which type of policy to create. @@ -142,12 +142,13 @@ The workaround is to amend your group or instance push rules to allow branches f ### Troubleshooting common issues configuring security policies - Confirm that scanners are properly configured and producing results for the latest branch. Security Policies are designed to require approval when there are no results (no security report), as this ensures that no vulnerabilities are introduced. We cannot know if there are any vulnerabilities unless the scans enforced by the policy complete successfully and are evaluated. +- For scan result policies, we require artifacts for each scanner defined in the policy for both the source and target branch. To ensure scan result policies capture the necessary results, confirm your scan execution is properly implemented and enforced. If using scan execution policies, enforcing on `all branches` often address this need. - When running scan execution policies based on a SAST action, ensure target repositories contain proper code files. SAST runs different analyzers [based on the types of files in the repo](../sast/index.md#supported-languages-and-frameworks), and if no supported files are found it will not run any jobs. See the [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) for more details. -- Check for any branch configuration conflicts. If your policy is configured to enforce rules on `main` but some projects within the scope are using `master` as their default branch, the policy is not applied for the latter. Support for specifying the `default` branch in your policies is proposed in [epic 9468](https://gitlab.com/groups/gitlab-org/-/epics/9468). +- Check for any branch configuration conflicts. If your policy is configured to enforce rules on `main` but some projects within the scope are using `master` as their default branch, the policy is not applied for the latter. You can define policies to enforce rules generically on `default` branches regardless of the name used in the project or on `all protected branches` to address this issue. - Scan result policies created at the group or sub-group level can take some time to apply to all the merge requests in the group. - Scheduled scan execution policies run with a minimum 15 minute cadence. Learn more [about the schedule rule type](../policies/scan-execution-policies.md#schedule-rule-type). - When scheduling pipelines, keep in mind that CRON scheduling is based on UTC on GitLab SaaS and is based on your server time for self managed instances. When testing new policies, it may appear pipelines are not running properly when in fact they are scheduled in your server's timezone. -- When enforcing scan execution policies, security policies creates a bot in the target project that will trigger scheduled pipelines to ensure enforcement. If the bot is +- When enforcing scan execution policies, security policies creates a bot in the target project that will trigger scheduled pipelines to ensure enforcement. If the bot is deleted or missing, the target project's pipeline will not be executed. To recreate a security policy bot user unlink and link the security policy project again. - You should not link a security policy project to a development project and to the group or sub-group the development project belongs to at the same time. Linking this way will result in approval rules from the Scan Result Policy not being applied to merge requests in the development project. - When creating a Scan Result Policy, neither the array `severity_levels` nor the array `vulnerability_states` in the [scan_finding rule](../policies/scan-result-policies.md#scan_finding-rule-type) can be left empty; for a working rule, at least one entry must exist. diff --git a/doc/user/application_security/policies/scan-execution-policies.md b/doc/user/application_security/policies/scan-execution-policies.md index 834a50f39ef..ac15dfc0a47 100644 --- a/doc/user/application_security/policies/scan-execution-policies.md +++ b/doc/user/application_security/policies/scan-execution-policies.md @@ -97,7 +97,12 @@ the following sections and tables provide an alternative. ## `pipeline` rule type > - The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Disabled by default. -> - The `branch_type` field was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/413062) in GitLab 16.2. +> - Generally available in GitLab 16.2. Feature flag `security_policies_branch_type` removed. +> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. + +FLAG: +On self-managed GitLab, by default the `branch_exceptions` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. +On GitLab.com, this feature is available. This rule enforces the defined actions whenever the pipeline runs for a selected branch. @@ -106,33 +111,35 @@ This rule enforces the defined actions whenever the pipeline runs for a selected | `type` | `string` | true | `pipeline` | The rule's type. | | `branches` <sup>1</sup> | `array` of `string` | true if `branch_type` field does not exist | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `branch_type` <sup>1</sup> | `string` | true if `branches` field does not exist | `default`, `protected` or `all` | The types of branches the given policy applies to. | +| `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | 1. You must specify only one of `branches` or `branch_type`. ## `schedule` rule type > - The `branch_type` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404774) in GitLab 16.1 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_type`. Disabled by default. -> - The `branch_type` field was [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/413062) in GitLab 16.2. -> - The security policy bot users were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/394958) in GitLab 16.3 [with flags](../../../administration/feature_flags.md) named `scan_execution_group_bot_users` and `scan_execution_bot_users`. Enabled by default. +> - Generally available in GitLab 16.2. Feature flag `security_policies_branch_type` removed. +> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. FLAG: -On self-managed GitLab, security policy bot users are available. To hide the feature, an administrator can [disable the feature flags](../../../administration/feature_flags.md) named `scan_execution_group_bot_users` and `scan_execution_bot_users`. +On self-managed GitLab, by default the `branch_exceptions` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. On GitLab.com, this feature is available. -This rule enforces the defined actions and schedules a scan on the provided date/time. +This rule schedules a scan pipeline, enforcing the defined actions on the schedule defined in the `cadence` field. A scheduled pipeline does not run other jobs defined in the project's `.gitlab-ci.yml` file. When a project is linked to a security policy project, a security policy bot is created in the project and will become the author of any scheduled pipelines. | Field | Type | Required | Possible values | Description | |------------|------|----------|-----------------|-------------| | `type` | `string` | true | `schedule` | The rule's type. | | `branches` <sup>1</sup> | `array` of `string` | true if either `branch_type` or `agents` fields does not exist | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `branch_type` <sup>1</sup> | `string` | true if either `branches` or `agents` fields does not exist | `default`, `protected` or `all` | The types of branches the given policy applies to. | +| `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `cadence` | `string` | true | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. Minimum of 15 minute intervals when used together with the `branches` field. | | `timezone` | `string` | false | Time zone identifier (for example, `America/New_York`) | Time zone to apply to the cadence. Value must be an IANA Time Zone Database identifier. | | `agents` <sup>1</sup> | `object` | true if either `branch_type` or `branches` fields do not exists | | 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. | 1. You must specify only one of `branches`, `branch_type`, or `agents`. -Scheduled scan pipelines are triggered by a security policy bot user that is a guest member of the project. Security policy bot users are automatically created when the security policy project is linked, and removed when the security policy project is unlinked. +Scheduled scan pipelines are triggered by a security policy bot user that is a guest member of the project with elevated permissions for users of type `security_policy_bot` so it may carry out this task. Security policy bot users are automatically created when the security policy project is linked, and removed when the security policy project is unlinked. If the project does not have a security policy bot user, the scheduled scan pipeline will not be triggered. To recreate a security policy bot user unlink and link the security policy project again. @@ -214,11 +221,12 @@ Note the following: is not scheduled successfully. - For a secret detection scan, only rules with the default ruleset are supported. [Custom rulesets](../secret_detection/index.md#custom-rulesets) are not supported. -- A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in +- A secret detection scan runs in `default` mode when executed as part of a pipeline, and in [`historic`](../secret_detection/index.md#full-history-secret-detection) mode when executed as part of a scheduled scan. - A container scanning scan that is configured for the `pipeline` rule type ignores the agent defined in the `agents` object. The `agents` object is only considered for `schedule` rule types. An agent with a name provided in the `agents` object must be created and configured for the project. +- Variables defined in a Scan Execution Policy follow the standard [CI/CD variable precedence](../../../ci/variables/index.md#cicd-variable-precedence). ## Example security policies project diff --git a/doc/user/application_security/policies/scan-result-policies.md b/doc/user/application_security/policies/scan-result-policies.md index c5cfd63641b..a42b3f02c26 100644 --- a/doc/user/application_security/policies/scan-result-policies.md +++ b/doc/user/application_security/policies/scan-result-policies.md @@ -84,23 +84,36 @@ the following sections and tables provide an alternative. ## Scan result policy schema +> The `approval_settings` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4 [with a flag](../../../administration/feature_flags.md) named `scan_result_policy_settings`. 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 `scan_result_policy_settings`. +On GitLab.com, this feature is not available. + | Field | Type | Required |Possible values | Description | |-------|------|----------|----------------|-------------| | `name` | `string` | true | | Name of the policy. Maximum of 255 characters.| | `description` (optional) | `string` | true | | Description of the policy. | | `enabled` | `boolean` | true | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | | `rules` | `array` of rules | true | | List of rules that the policy applies. | -| `actions` | `array` of actions | true | | List of actions that the policy enforces. | +| `actions` | `array` of actions | false| | List of actions that the policy enforces. | +| `approval_settings` | `object` | false | `{prevent_approval_by_author: boolean, prevent_approval_by_commit_author: boolean, remove_approvals_with_new_commit: boolean, require_password_to_approve: boolean}` | Project settings that the policy overrides. | ## `scan_finding` rule type > - The scan result policy field `vulnerability_attributes` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123052) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `enforce_vulnerability_attributes_rules`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/418784) in GitLab 16.3. > - The scan result policy field `vulnerability_age` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123956) in GitLab 16.2. +> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. FLAG: On self-managed GitLab, by default the `vulnerability_attributes` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `enforce_vulnerability_attributes_rules`. On GitLab.com, this feature is available. + +FLAG: +On self-managed GitLab, by default the `branch_exceptions` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. +On GitLab.com, this feature is available. + This rule enforces the defined actions based on security scan findings. | Field | Type | Required | Possible values | Description | @@ -108,6 +121,7 @@ This rule enforces the defined actions based on security scan findings. | `type` | `string` | true | `scan_finding` | The rule's type. | | `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | | `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `scanners` | `array` of `string` | true | `sast`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`, `coverage_fuzzing`, `api_fuzzing` | The security scanners for this rule to consider. `sast` includes results from both SAST and SAST IaC scanners. | | `vulnerabilities_allowed` | `integer` | true | Greater than or equal to zero | Number of vulnerabilities allowed before this rule is considered. | | `severity_levels` | `array` of `string` | true | `info`, `unknown`, `low`, `medium`, `high`, `critical` | The severity levels for this rule to consider. | @@ -119,6 +133,11 @@ This rule enforces the defined actions based on security scan findings. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8092) in GitLab 15.9 [with a flag](../../../administration/feature_flags.md) named `license_scanning_policies`. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/397644) in GitLab 15.11. Feature flag `license_scanning_policies` removed. +> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. + +FLAG: +On self-managed GitLab, by default the `branch_exceptions` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. +On GitLab.com, this feature is available. This rule enforces the defined actions based on license findings. @@ -127,10 +146,30 @@ This rule enforces the defined actions based on license findings. | `type` | `string` | true | `license_finding` | The rule's type. | | `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | | `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | | `match_on_inclusion` | `boolean` | true | `true`, `false` | Whether the rule matches inclusion or exclusion of licenses listed in `license_types`. | | `license_types` | `array` of `string` | true | license types | [SPDX license names](https://spdx.org/licenses) to match on, for example `Affero General Public License v1.0` or `MIT License`. | | `license_states` | `array` of `string` | true | `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. | +## `any_merge_request` rule type + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418752) in GitLab 16.4. +> - The `branch_exceptions` field was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418741) in GitLab 16.3 [with a flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. Enabled by default. + +FLAG: +On self-managed GitLab, by default the `branch_exceptions` field is available. To hide the feature, an administrator can [disable the feature flag](../../../administration/feature_flags.md) named `security_policies_branch_exceptions`. +On GitLab.com, this feature is available. + +This rule enforces the defined actions for any merge request based on the commits signature. + +| Field | Type | Required | Possible values | Description | +|---------------|---------------------|--------------------------------------------|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | `string` | true | `any_merge_request` | The rule's type. | +| `branches` | `array` of `string` | true if `branch_type` field does not exist | `[]` or the branch's name | Applicable only to protected target branches. An empty array, `[]`, applies the rule to all protected target branches. Cannot be used with the `branch_type` field. | +| `branch_type` | `string` | true if `branches` field does not exist | `default` or `protected` | The types of branches the given policy applies to. Cannot be used with the `branches` field. | +| `branch_exceptions` | `array` of `string` | false | Names of branches | Branches to exclude from this rule. | +| `commits` | `string` | true | `any`, `unsigned` | Whether the rule matches for any commits, or only if unsigned commits are detected in the merge request. | + ## `require_approval` action type This action sets an approval rule to be required when conditions are met for at least one rule in diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 832ad100701..f896616d537 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -64,7 +64,7 @@ content directly. Instead, it enhances the results with additional properties, i - CWEs. - Location tracking fields. -- A means of identifying false positives or insignificant findings. **(ULTIMATE)** +- A means of identifying false positives or insignificant findings. **(ULTIMATE ALL)** ## Transition to Semgrep-based scanning diff --git a/doc/user/application_security/sast/customize_rulesets.md b/doc/user/application_security/sast/customize_rulesets.md index 4ae8f1c4f8b..90731114303 100644 --- a/doc/user/application_security/sast/customize_rulesets.md +++ b/doc/user/application_security/sast/customize_rulesets.md @@ -7,10 +7,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Customize rulesets **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for > passthrough chains. Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. -> - [Added](https://gitlab.com/gitlab-org/security-products/analyzers/ruleset/-/merge_requests/18) support for specifying ambiguous passthrough refs in GitLab 16.2. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in GitLab 14.8. +> - [Enabled](https://gitlab.com/gitlab-org/security-products/analyzers/ruleset/-/merge_requests/18) support for specifying ambiguous passthrough refs in GitLab 16.2. You can customize the behavior of our SAST analyzers by [defining a ruleset configuration file](#create-the-configuration-file) in the repository being scanned. There are two kinds of customization: @@ -29,8 +29,8 @@ You can disable predefined rules for any SAST analyzer. When you disable a rule: - Most analyzers still scan for the vulnerability. The results are removed as a processing step after the scan completes, and they don't appear in the [`gl-sast-report.json` artifact](index.md#reports-json-format). -- Findings for the disabled rule no longer appear in the [Pipeline Security tab](../index.md#view-security-scan-information-in-the-pipeline-security-tab). -- Existing findings for the disabled rule on the default branch are marked ["No longer detected"](../vulnerability_report/index.md#activity-filter) in the [Vulnerability Report](../index.md#view-security-scan-information-in-the-vulnerability-report). +- Findings for the disabled rule no longer appear in the [pipeline security tab](../index.md#pipeline-security-tab). +- Existing findings for the disabled rule on the default branch are marked as [`No longer detected`](../vulnerability_report/index.md#activity-filter) in the [vulnerability report](../index.md#vulnerability-report). The Semgrep-based analyzer handles disabled rules differently: diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 717608274e5..acc7e9d9e84 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -55,21 +55,16 @@ For more information about our plans for language support in SAST, see the [cate | Language / framework | [Analyzer](analyzers.md) used for scanning | Minimum supported GitLab version | |------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| -| .NET Core<sup>3</sup> | [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | 11.0 | -| .NET Framework<sup>3</sup> | [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | 13.0 | | .NET (all versions, C# only) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 15.4 | | Apex (Salesforce) | [PMD](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) | 12.1 | | C | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 14.2 | | C/C++ | [Flawfinder](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) | 11.1 | -| Go<sup>2</sup> | [Gosec](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | 10.7 | | Go | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 14.4 | | Groovy<sup>1</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 11.3 (Gradle) & 11.9 (Maven, SBT) | | Helm Charts | [Kubesec](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) | 13.1 | | Java (any build system) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 14.10 | -| Java<sup>1, 2</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (SBT) | | Java (Android) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | -| JavaScript<sup>2</sup> | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.8 | | JavaScript | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.10 | | Kotlin (Android) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | | Kotlin (General)<sup>1</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 13.11 | @@ -77,24 +72,34 @@ For more information about our plans for language support in SAST, see the [cate | Node.js | [NodeJsScan](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) | 11.1 | | Objective-C (iOS) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | | PHP | [phpcs-security-audit](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) | 10.8 | -| Python<sup>2</sup> | [bandit](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | 10.3 | | Python | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.9 | -| React<sup>2</sup> | [ESLint react plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 12.5 | | React | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.10 | | Ruby | [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | 13.9 | | Ruby on Rails | [brakeman](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) | 10.3 | | Scala (any build system) | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 16.0 | | Scala<sup>1</sup> | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 11.0 (SBT) & 11.9 (Gradle, Maven) | | Swift (iOS) | [MobSF (beta)](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) | 13.5 | -| TypeScript<sup>2</sup> | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | | TypeScript | [Semgrep](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep) with [GitLab-managed rules](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/RULES.md) | 13.10 | 1. The SpotBugs-based analyzer supports [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/). It can also be used with variants like the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), [Grails](https://grails.org/), and the [Maven wrapper](https://github.com/takari/maven-wrapper). However, SpotBugs has [limitations](https://gitlab.com/gitlab-org/gitlab/-/issues/350801) when used against [Ant](https://ant.apache.org/)-based projects. We recommend using the Semgrep-based analyzer for Ant-based Java or Scala projects. -1. These analyzers reached [End of Support](https://about.gitlab.com/handbook/product/gitlab-the-product/#end-of-support) status [in GitLab 15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554). -1. Security Code Scan reached [End of Support](https://about.gitlab.com/handbook/product/gitlab-the-product/#end-of-support) status [in GitLab 16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/390416). + +## End of supported analyzers + +GitLab has reached [End of Support](https://about.gitlab.com/handbook/product/gitlab-the-product/#end-of-support) for the below analyzers. These analyzers have been replaced by the Semgrep-based analyzer. + +| Language / framework | [Analyzer](analyzers.md) used for scanning | Minimum supported GitLab version | End Of Support GitLab version | +|------------------------------|--------------------------------------------------------------------------------------------------------------| --------------------------------- | ------------------------------------------------------------- | +| .NET Core | [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | 11.0 | [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/390416) | +| .NET Framework | [Security Code Scan](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) | 13.0 | [16.0](https://gitlab.com/gitlab-org/gitlab/-/issues/390416) | +| Go | [Gosec](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) | 10.7 | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | +| Java | [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) with the find-sec-bugs plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (SBT) | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | +| Python | [bandit](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) | 10.3 | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | +| React | [ESLint react plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 12.5 | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | +| JavaScript | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.8 | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | +| TypeScript | [ESLint security plugin](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) | 11.9, with ESLint in 13.2 | [15.4](https://gitlab.com/gitlab-org/gitlab/-/issues/352554) | ## Multi-project support @@ -151,8 +156,9 @@ Advanced vulnerability tracking is available in a subset of the [supported langu - C++, in the Flawfinder analyzer only - C#, in the Semgrep-based analyzer only - Go, in the Semgrep-based analyzer only -- Java, in the Semgrep-based and mobsf analyzers +- Java, in the mobsf, Semgrep-based and SpotBugs analyzers - JavaScript, in the Semgrep-based and NodeJS-Scan analyzers +- PHP, in the phpcs-security-audit analyzer - Python, in the Semgrep-based analyzer only - Ruby, in the Brakeman-based analyzer @@ -278,7 +284,7 @@ successfully, and an error may occur. To enable and configure SAST with customizations: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. If the project does not have a `.gitlab-ci.yml` file, select **Enable SAST** in the Static Application Security Testing (SAST) row, otherwise select **Configure SAST**. @@ -300,7 +306,7 @@ successfully, and an error may occur. To enable and configure SAST with default settings: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the SAST section, select **Configure with a merge request**. 1. Review and merge the merge request to enable SAST. @@ -619,7 +625,7 @@ For information, see [Download job artifacts](../../../ci/jobs/job_artifacts.md# For details of the report file's schema, see [SAST report file schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json). -For an example SAST report file, see [`gl-secret-detection-report.json`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/qa/expect/secrets/gl-secret-detection-report.json) example. +For an example SAST report file, see [`gl-sast-report.json`](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/main/qa/expect/js/default/gl-sast-report.json) example. ## Running SAST in an offline environment diff --git a/doc/user/application_security/sast/rules.md b/doc/user/application_security/sast/rules.md new file mode 100644 index 00000000000..4e7a6387f9b --- /dev/null +++ b/doc/user/application_security/sast/rules.md @@ -0,0 +1,101 @@ +--- +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 +--- + +# SAST rules **(FREE)** + +GitLab SAST uses a set of [analyzers](analyzers.md) to scan code for potential vulnerabilities. +Each analyzer processes the code then uses rules to find possible weaknesses in source code. +The rules determine what types of weaknesses the analyzer reports. + +## Source of rules + +### Semgrep-based analyzer + +GitLab creates, maintains, and supports the rules that are used in the Semgrep-based GitLab SAST analyzer. +This analyzer scans [many languages](index.md#supported-languages-and-frameworks) in a single CI/CD pipeline job. +It combines: + +- the Semgrep open-source engine. +- GitLab-managed detection rules. +- GitLab proprietary technology for [vulnerability tracking](index.md#advanced-vulnerability-tracking) and [false positive detection](index.md#false-positive-detection). + +### Other analyzers + +GitLab SAST uses other analyzers to scan the remaining [supported languages](index.md#supported-languages-and-frameworks). +The rules for these scans are defined in the upstream projects for each scanner. + +## How rule updates are released + +GitLab updates rules regularly based on customer feedback and internal research. +Rules are released as part of the container image for each analyzer. +You automatically receive updated analyzers and rules unless you [manually pin analyzers to a specific version](index.md#pinning-to-minor-image-version). + +Analyzers and their rules are updated [at least monthly](../index.md#vulnerability-scanner-maintenance) if relevant updates are available. + +The GitLab ruleset for the Semgrep-based analyzer is managed in [the GitLab-managed open-source `sast-rules` project](https://gitlab.com/gitlab-org/security-products/sast-rules). +When rules are updated, they're released as part of the [Semgrep-based analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep)'s container image. + +## Configure rules in your projects + +You should use the default SAST rules unless you have a specific reason to make a change. +The default ruleset is designed to be relevant to most projects. + +However, you can [customize which rules are used](#apply-local-rule-preferences) or [control how rule changes are rolled out](#coordinate-rule-rollouts) if needed. + +### Apply local rule preferences + +You may want to customize the rules used in SAST scans because: + +- Your organization has assigned priorities to specific vulnerability classes, such as choosing to address Cross-Site Scripting (XSS) or SQL Injection before other classes of vulnerabilities. +- You believe that a specific rule is a false positive result or isn't relevant in the context of your codebase. + +To change which rules are used to scan your projects, adjust their severity, or apply other preferences, see [Customize rulesets](customize_rulesets.md). +If your customization would benefit other users, consider [reporting a problem to GitLab](#report-a-problem-with-a-gitlab-sast-rule). + +### Coordinate rule rollouts + +To control the rollout of rule changes, you can [pin SAST analyzers to a specific version](index.md#pinning-to-minor-image-version). + +If you want to make these changes at the same time across multiple projects, consider setting the variables in: + +- [Group-level CI/CD variables](../../../ci/variables/index.md#for-a-group). +- Custom CI/CD variables in a [Scan Execution Policy](../policies/scan-execution-policies.md). + +## Report a problem with a GitLab SAST rule +<!-- This title is intended to match common search queries users might make. --> + +GitLab welcomes contributions to the rulesets used in SAST. +Contributions might address: + +- False positive results, where the potential vulnerability is incorrect. +- False negative results, where SAST did not report a potential vulnerability that truly exists. +- The name, severity rating, description, guidance, or other explanatory content for a rule. + +If you believe a detection rule could be improved for all users, consider: + +- Submitting a merge request to [the `sast-rules` repository](https://gitlab.com/gitlab-org/security-products/sast-rules). See the [contribution instructions](https://gitlab.com/gitlab-org/security-products/sast-rules#contributing) for details. +- Filing an issue in [the `gitlab-org/gitlab` issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues/). + - Post a comment that says `@gitlab-bot label ~"group::static analysis" ~"Category:SAST"` so your issue lands in the correct triage workflow. + +## Important rule changes + +GitLab updates SAST rules [regularly](#how-rule-updates-are-released). +This section highlights the most important changes. +More details are available in release announcements and in the CHANGELOG links provided. + +### Rule changes in the Semgrep-based analyzer + +Key changes to the GitLab-managed ruleset for Semgrep-based scanning include: + +- Beginning in GitLab 16.3, the GitLab Static Analysis and Vulnerability Research teams are working to remove rules that tend to produce too many false positive results or not enough actionable true positive results. Existing findings from these removed rules are [automatically resolved](index.md#automatic-vulnerability-resolution); they no longer appear in the [Security Dashboard](../security_dashboard/index.md#view-vulnerabilities-over-time-for-a-project) or in the default view of the [Vulnerability Report](../vulnerability_report/index.md). This work is tracked in [epic 10907](https://gitlab.com/groups/gitlab-org/-/epics/10907). +- In GitLab 16.0 through 16.2, the GitLab Vulnerability Research team updated the guidance that's included in each result. +- In GitLab 15.10, the `detect-object-injection` rule was [removed by default](https://gitlab.com/gitlab-org/gitlab/-/issues/373920) and its findings were [automatically resolved](index.md#automatic-vulnerability-resolution). + +For more details, see the [CHANGELOG for `sast-rules`](https://gitlab.com/gitlab-org/security-products/sast-rules/-/blob/main/CHANGELOG.md). + +### Rule changes in other analyzers + +See the CHANGELOG file for each [analyzer](analyzers.md) for details of the changes, including new or updated rules, included in each version. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 10e8356de16..a10c029bec6 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -27,7 +27,7 @@ You can run scans and view [Secret Detection JSON report artifacts](../../../ci/ With GitLab Ultimate, Secret Detection results are also processed so you can: -- See them in the [merge request widget](../index.md#view-security-scan-information-in-merge-requests), [pipeline security report](../vulnerability_report/pipeline.md), and [Vulnerability Report](../vulnerability_report/index.md). +- See them in the [merge request widget](../index.md#merge-request), [pipeline security report](../vulnerability_report/pipeline.md), and [vulnerability report](../vulnerability_report/index.md) UIs. - Use them in approval workflows. - Review them in the security dashboard. - [Automatically respond](automatic_response.md) to leaks in public repositories. @@ -155,7 +155,7 @@ To enable Secret Detection, either: This method requires you to manually edit the existing `.gitlab-ci.yml` file. Use this method if your GitLab CI/CD configuration file is complex. -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Build > Pipeline editor**. 1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file: @@ -188,7 +188,7 @@ error may occur. In that case, use the [manual](#edit-the-gitlab-ciyml-file-manu To enable Secret Detection: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. In the **Secret Detection** row, select **Configure with a merge request**. 1. Optional. Complete the fields. @@ -338,12 +338,14 @@ To enable full history Secret Detection, set the variable `SECRET_DETECTION_HIST ## Custom rulesets **(ULTIMATE ALL)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for passthrough chains. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/339614) support for passthrough chains. > Expanded to include additional passthrough types of `file`, `git`, and `url` in GitLab 14.6. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/235359) support for overriding rules in > GitLab 14.8. -You can customize the default Secret Detection rules provided with GitLab. +You can customize which [secrets are reported in the GitLab UI](#secret-detection). +However, the `secret_detection` job logs always include the number +of secrets detected by the default Secret Detection rules. The following customization options can be used separately, or in combination: @@ -510,7 +512,7 @@ optional authentication, and optional Git SHA. The variable uses the following f ``` NOTE: -Loading local project configuration takes precedence over `SECRET_DETECTION_RULESET_GIT_REFERENCE` values. +A local `.gitlab/secret-detection-ruleset.toml` file in the project takes precedence over `SECRET_DETECTION_RULESET_GIT_REFERENCE`. The following example includes the Secret Detection template in a project to be scanned and specifies the `SECRET_DETECTION_RULESET_GIT_REFERENCE` variable for referencing a separate project configuration. diff --git a/doc/user/application_security/secure_your_application.md b/doc/user/application_security/secure_your_application.md index 0b028f6936d..f4fb8c49277 100644 --- a/doc/user/application_security/secure_your_application.md +++ b/doc/user/application_security/secure_your_application.md @@ -27,3 +27,4 @@ GitLab can check your applications for security vulnerabilities. - [Policies](policies/index.md) - [Security scanner integration](../../development/integrations/secure.md) - [Secure and Govern Terminology](terminology/index.md) +- [GitLab Advisory Database](gitlab_advisory_database/index.md) diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index b6d95e53227..53a6dfe6d0a 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -66,7 +66,7 @@ Project Security Dashboards show statistics for all vulnerabilities with a curre To view total number of vulnerabilities over time: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security dashboard**. 1. Filter and search for what you need. - To filter the chart by severity, select the legend name. @@ -79,7 +79,7 @@ To view total number of vulnerabilities over time: To download an SVG image of the vulnerabilities chart: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security dashboard**. 1. Select **Save chart as an image** (**{download}**). @@ -90,7 +90,7 @@ branches of projects in a group and its subgroups. To view vulnerabilities over time for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Security > Security dashboard**. 1. Hover over the chart to get more details about vulnerabilities. - You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days). @@ -104,7 +104,7 @@ Use the group Security Dashboard to view the security status of projects. To view project security status for a group: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. On the left sidebar, select **Search or go to** and find your group. 1. Select **Secure > Security dashboard**. Each project is assigned a letter [grade](#project-vulnerability-grades) according to the highest-severity open vulnerability. @@ -142,7 +142,7 @@ The Security Center includes: To view the Security Center: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. 1. Select **Security > Security dashboard**. @@ -150,7 +150,7 @@ To view the Security Center: To add projects to the Security Center: -1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. On the left sidebar, select **Search or go to**. 1. Select **Your work**. 1. Expand **Security**. 1. Select **Settings**. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index fa0027754ad..34c57292767 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -24,10 +24,10 @@ change its status to **Resolved**. This ensures that if it is accidentally reint merge, it is reported again as a new record. To change the status of multiple vulnerabilities, use the Vulnerability Report's [Activity filter](../vulnerability_report/index.md#activity-filter). -## Explaining a vulnerability (Beta) **(ULTIMATE SAAS)** +## Explaining a vulnerability **(ULTIMATE SAAS BETA)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/10368) in GitLab 16.0 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) on GitLab.com. -> - Promoted to [Beta](../../../policy/experiment-beta-support.md#beta) status in 16.2. +> - Promoted to [Beta](../../../policy/experiment-beta-support.md#beta) status in GitLab 16.2. GitLab can help you with a vulnerability by using a large language model to: @@ -37,8 +37,8 @@ GitLab can help you with a vulnerability by using a large language model to: ### Explain a vulnerability -Use the explain this vulnerability feature to better understand a vulnerability and its possible -mitigation. +Explain a vulnerability with GitLab Duo Vulnerability summary. Use the explanation to better +understand a vulnerability and its possible mitigation. Prerequisites: @@ -46,11 +46,11 @@ Prerequisites: - You must be a member of the project. - The vulnerability must be a SAST finding. -Learn more about [how to enable all AI features](../../ai_features.md#enable-aiml-features). +Learn more about [how to enable all GitLab Duo features](../../ai_features.md#enable-aiml-features). To explain the vulnerability: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Security and Compliance > Vulnerability report**. 1. In the **Tool** dropdown list, select **SAST**. 1. Select the SAST vulnerability you want explained. @@ -108,7 +108,7 @@ When dismissing a vulnerability, one of the following reasons must be chosen to To change a vulnerability's status from its Vulnerability Page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Status** dropdown list select a status, then select **Change status**. @@ -130,15 +130,11 @@ You can create either: - [A GitLab issue](#create-a-gitlab-issue-for-a-vulnerability) (default). - [A Jira issue](#create-a-jira-issue-for-a-vulnerability). -Creating a Jira issue requires that -[Jira integration](../../../integration/jira/index.md) is enabled on the project. Note -that when Jira integration is enabled, the GitLab issue feature is not available. - ### Create a GitLab issue for a vulnerability To create a GitLab issue for a vulnerability: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. Select **Create issue**. @@ -157,7 +153,7 @@ Prerequisites: To create a Jira issue for a vulnerability: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. Select **Create Jira issue**. @@ -169,28 +165,21 @@ fields are pre-populated from the vulnerability's details. Unlike GitLab issues, the status of whether a Jira issue is open or closed does not display in the GitLab user interface. -## Linking a vulnerability to issues - -NOTE: -If Jira issue support is enabled, GitLab issues are disabled so this feature is not available. +## Linking a vulnerability to GitLab and Jira issues -You can link a vulnerability to one or more existing GitLab issues. Adding a link helps track -the issue that resolves or mitigates a vulnerability. +You can link a vulnerability to one or more existing [GitLab](#create-a-gitlab-issue-for-a-vulnerability) +or [Jira](#create-a-jira-issue-for-a-vulnerability) issues. Only one linking feature is available at the same time. +Adding a link helps track the issue that resolves or mitigates a vulnerability. -Issues linked to a vulnerability are shown in the Vulnerability Report and the vulnerability's page. +### Link a vulnerability to existing GitLab issues -Be aware of the following conditions between a vulnerability and a linked issue: +Prerequisite: -- The vulnerability page shows related issues, but the issue page doesn't show the vulnerability - it's related to. -- An issue can only be related to one vulnerability at a time. -- Issues can be linked across groups and projects. +- [Jira issue integration](../../../integration/jira/configure.md) must not be enabled. -## Link a vulnerability to existing issues +To link a vulnerability to existing GitLab issues: -To link a vulnerability to existing issues: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. In the **Linked issues** section, select the plus icon (**{plus}**). @@ -199,9 +188,43 @@ To link a vulnerability to existing issues: - Enter the issue's ID (prefixed with a hash `#`). 1. Select **Add**. -The selected issues are added to the **Linked issues** section, and the linked issues counter is +The selected GitLab issues are added to the **Linked items** section, and the linked issues counter is +updated. + +GitLab issues linked to a vulnerability are shown in the Vulnerability Report and the vulnerability's page. + +Be aware of the following conditions between a vulnerability and a linked GitLab issue: + +- The vulnerability page shows related issues, but the issue page doesn't show the vulnerability + it's related to. +- An issue can only be related to one vulnerability at a time. +- Issues can be linked across groups and projects. + +### Link a vulnerability to existing Jira issues + +Prerequisite: + +- [Jira issue integration](../../../integration/jira/configure.md) must be enabled, with option **Enable Jira issue creation from vulnerabilities** also enabled. + +To link a vulnerability to existing Jira issues, add the following line to the Jira issue's description: + +```plaintext +/-/security/vulnerabilities/<id> +``` + +`<id>` is any [vulnerability ID](../../../api/vulnerabilities.md#single-vulnerability). +You can add several lines with different IDs to one description. + +Jira issues with appropriate description are added to the **Related Jira issues** section, and the linked issues counter is updated. +Jira issues linked to a vulnerability are shown only on the vulnerability page. + +Be aware of the following conditions between a vulnerability and a linked Jira issue: + +- The vulnerability page and the issue page show the vulnerability they are related to. +- An issue can be related to one or more vulnerabilities at the same time. + ## Resolve a vulnerability For some vulnerabilities a solution is already known. In those instances, a vulnerability's page @@ -225,7 +248,7 @@ To resolve a vulnerability, you can either: To resolve the vulnerability with a merge request: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Resolve with merge request** dropdown list, select **Resolve with merge request**. @@ -237,7 +260,7 @@ Process the merge request according to your standard workflow. To manually apply the patch that GitLab generated for a vulnerability: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select the vulnerability's description. 1. From the **Resolve with merge request** dropdown list, select **Download patch to resolve**. @@ -260,7 +283,7 @@ Security training helps your developers learn how to fix vulnerabilities. Develo To enable security training for vulnerabilities in your project: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Security configuration**. 1. On the tab bar, select **Vulnerability Management**. 1. To enable a security training provider, turn on the toggle. @@ -280,7 +303,7 @@ Vulnerabilities with a CWE are most likely to return a training result. To view the security training for a vulnerability: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > 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 46ce3173ee7..3ec1151b1d6 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -40,8 +40,6 @@ status of a Jira issue is not shown in the GitLab UI. ## Project-level Vulnerability Report -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in GitLab 11.1. - At the project level, the Vulnerability Report also contains: - A time stamp showing when it was updated, including a link to the latest pipeline. @@ -55,7 +53,7 @@ this page displays the vulnerabilities that originate from the selected project. To view the project-level vulnerability report: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. ## Vulnerability Report actions @@ -129,8 +127,6 @@ The content of the Project filter depends on the current level: ### Activity filter -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259255) in GitLab 13.9 - The Activity filter behaves differently from the other filters. The selected values form mutually exclusive sets to allow for precisely locating the desired vulnerability records. Additionally, not all options can be selected in combination. @@ -150,8 +146,6 @@ To view more details of a vulnerability, select the vulnerability's **Descriptio ## View vulnerable source location -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267509) in GitLab 13.10. - Some security scanners output the filename and line number of a potential vulnerability. When that information is available, the vulnerability's details include a link to the relevant file, in the default branch. @@ -160,8 +154,7 @@ To view the relevant file, select the filename in the vulnerability's details. ## Change status of vulnerabilities -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292636) in GitLab 13.10, all statuses became selectable. -> - Providing a comment and dismissal reason [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408366) in GitLab 16.0. +> Providing a comment and dismissal reason [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408366) in GitLab 16.0. From the Vulnerability Report you can change the status of one or more vulnerabilities. @@ -184,9 +177,6 @@ To sort vulnerabilities by the date each vulnerability was detected, select the ## Export vulnerability details -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in the Security Center (previously known as the Instance Security Dashboard) and project-level Vulnerability Report (previously known as the Project Security Dashboard) in GitLab 13.0. -> - [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). All vulnerabilities are included because filters do not apply to the export. @@ -229,8 +219,6 @@ thousands of vulnerabilities. Do not close the page until the download finishes. ## Dismiss a vulnerability -> The option of adding a dismissal reason was introduced in GitLab 12.0. - 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 @@ -260,7 +248,7 @@ To undo this action, select a different status from the same menu. To add a new vulnerability finding from your project level Vulnerability Report page: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Secure > Vulnerability report**. 1. Select **Submit vulnerability**. 1. Complete the fields and submit the form. diff --git a/doc/user/application_security/vulnerability_report/pipeline.md b/doc/user/application_security/vulnerability_report/pipeline.md index 7a414e9a4ae..ef66925b9c9 100644 --- a/doc/user/application_security/vulnerability_report/pipeline.md +++ b/doc/user/application_security/vulnerability_report/pipeline.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w To view vulnerabilities in a pipeline: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Build > Pipelines**. 1. From the list, select the pipeline you want to check for vulnerabilities. 1. Select the **Security** tab. @@ -25,9 +25,11 @@ For example, if a pipeline contains DAST and SAST jobs, but the DAST job fails b [exit code](../../../development/integrations/secure.md#exit-code), the report doesn't show DAST results. The pipeline vulnerability report only shows results contained in the security report artifacts. This report differs from -the [Vulnerability Report](index.md), which contains cumulative results of all successful jobs, and from the merge request -[security widget](../index.md#view-security-scan-information-in-merge-requests), which combines the branch results with -cumulative results. +the [vulnerability report](index.md), which contains cumulative results of all successful jobs, and from the merge request +[security widget](../index.md#merge-request), which contains new vulnerability findings that don't already exist on the default branch. + +NOTE: +If a new advisory is added to our advisory database and the last pipeline for the default branch is stale, the resulting vulnerability may appear in the MR widget as "New" when it is already in the default branch. This will be resolved by [Continuous Vulnerability Scans](https://gitlab.com/groups/gitlab-org/-/epics/7886). The pipeline vulnerability report only displays after the pipeline is complete. If the pipeline has a [blocking manual job](../../../ci/jobs/job_control.md#types-of-manual-jobs), the pipeline waits for the manual job and the vulnerabilities cannot be displayed if the blocking manual job did not run. |
