diff options
Diffstat (limited to 'doc/user/application_security/index.md')
| -rw-r--r-- | doc/user/application_security/index.md | 167 |
1 files changed, 119 insertions, 48 deletions
diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 413a9f894e2..30852d1bbcd 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference, howto --- @@ -18,7 +21,7 @@ For an overview of application security with GitLab, see ## Quick start Get started quickly with Dependency Scanning, License Scanning, Static Application Security -Testing (SAST), and Secret Detection by adding the following to your `.gitlab-ci.yml`: +Testing (SAST), and Secret Detection by adding the following to your [`.gitlab-ci.yml`](../../ci/yaml/README.md): ```yaml include: @@ -67,12 +70,26 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | | [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | -| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | -| [Secret Detection](secret_detection/index.md) **(ULTIMATE)** | Analyze Git history for leaked secrets. | +| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | +| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | | [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | | [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | | [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | +### Use security scanning tools with Pipelines for Merge Requests + +The security scanning tools can all be added to pipelines with [templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Security). +See each tool for details on how to use include each template in your CI/CD configuration. + +By default, the application security jobs are configured to run for branch pipelines only. +To use them with [pipelines for merge requests](../../ci/merge_request_pipelines/index.md), +you may need to override the default `rules:` configuration to add: + +```yaml +rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" +``` + ## Security Scanning with Auto DevOps When [Auto DevOps](../../topics/autodevops/) is enabled, all GitLab Security scanning tools will be configured using default settings. @@ -93,7 +110,7 @@ The scanning tools and vulnerabilities database are updated regularly. | Secure scanning tool | Vulnerabilities database updates | |:-------------------------------------------------------------|-------------------------------------------| | [Container Scanning](container_scanning/index.md) | Uses `clair`. The latest `clair-db` version is used for each job by running the [`latest` Docker image tag](https://gitlab.com/gitlab-org/gitlab/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | -| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for NPM packages), and `gemnasium` (GitLab's own tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. 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). | +| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for NPM packages), and `gemnasium` (GitLab's own tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. 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/master/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab wraps](sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | @@ -106,6 +123,24 @@ latest versions of the scanning tools without having to do anything. There are s with this approach, however, and there is a [plan to resolve them](https://gitlab.com/gitlab-org/gitlab/-/issues/9725). +## Viewing security scan information in merge requests **(CORE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4393) in GitLab Core 13.5. +> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/273205) in 13.6. +> - It's [deployed behind a feature flag](../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It can be enabled or disabled for a single project. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-basic-security-widget). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +Merge requests which have run security scans let you know that the generated +reports are available to download. + + + ## Interacting with the vulnerabilities > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. @@ -119,7 +154,7 @@ information with several options: - [Create issue](#creating-an-issue-for-a-vulnerability): Create a new issue with the title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../project/issues/confidential_issues.md). -- [Solution](#solutions-for-vulnerabilities-auto-remediation): For some vulnerabilities, +- [Automatic Remediation](#automatic-remediation-for-vulnerabilities): For some vulnerabilities, a solution is provided for how to fix the vulnerability.  @@ -141,21 +176,21 @@ To view details of DAST vulnerabilities: 1. Click on the vulnerability's description. The following details are provided: - | Field | Description | -|:-----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Description | Description of the vulnerability. | -| Project | Namespace and project in which the vulnerability was detected. | -| Method | HTTP method used to detect the vulnerability. | -| URL | URL at which the vulnerability was detected. | -| Request Headers | Headers of the request. | -| Response Status | Response status received from the application. | -| Response Headers | Headers of the response received from the application. | +| Field | Description | +|:-----------------|:------------------------------------------------------------------ | +| Description | Description of the vulnerability. | +| Project | Namespace and project in which the vulnerability was detected. | +| Method | HTTP method used to detect the vulnerability. | +| URL | URL at which the vulnerability was detected. | +| Request Headers | Headers of the request. | +| Response Status | Response status received from the application. | +| Response Headers | Headers of the response received from the application. | | Evidence | Evidence of the data found that verified the vulnerability. Often a snippet of the request or response, this can be used to help verify that the finding is a vulnerability. | -| Identifiers | Identifiers of the vulnerability. | -| Severity | Severity of the vulnerability. | -| Scanner Type | Type of vulnerability report. | -| Links | Links to further details of the detected vulnerability. | -| Solution | Details of a recommended solution to the vulnerability (optional). | +| Identifiers | Identifiers of the vulnerability. | +| Severity | Severity of the vulnerability. | +| Scanner Type | Type of vulnerability report. | +| Links | Links to further details of the detected vulnerability. | +| Solution | Details of a recommended solution to the vulnerability (optional). | #### Hide sensitive information in headers @@ -198,38 +233,60 @@ Pressing the "Dismiss Selected" button will dismiss all the selected vulnerabili  -### Solutions for vulnerabilities (auto-remediation) +### Creating an issue for a vulnerability + +You can create an issue for a vulnerability by visiting the vulnerability's page and clicking +**Create issue**, which you can find in the **Related issues** section. + + + +This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the +vulnerability came from, and pre-populates it with some useful information taken from the vulnerability +report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on +it. + +Upon returning to the group security dashboard, the vulnerability now has an associated issue next +to the name. + + + +### Automatic remediation for vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. Some vulnerabilities can be fixed by applying the solution that GitLab -automatically generates. The following scanners are supported: +automatically generates. Although the feature name is Automatic Remediation, this feature is also commonly called Auto-Remediation, Auto Remediation, or Suggested Solutions. The following scanners are supported: - [Dependency Scanning](dependency_scanning/index.md): Automatic Patch creation is only available for Node.js projects managed with `yarn`. - [Container Scanning](container_scanning/index.md) +When an automatic solution is available, the button in the header shows **Resolve with merge request**: + + + +Selecting the button creates a merge request with the solution. + #### Manually applying the suggested patch -Some vulnerabilities can be fixed by applying a patch that is automatically -generated by GitLab. To apply the fix: +To manually apply the patch that GitLab generated for a vulnerability: + +1. Select the **Resolve with merge request** dropdown, then select **Download patch to resolve**: + +  -1. Click the vulnerability. -1. Download and review the patch file `remediation.patch`. 1. Ensure your local project has the same commit checked out that was used to generate the patch. 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. - - #### Creating a merge request from a vulnerability > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. In certain cases, GitLab allows you to create a merge request that automatically remediates the vulnerability. Any vulnerability that has a -[solution](#solutions-for-vulnerabilities-auto-remediation) can have a merge +[solution](#automatic-remediation-for-vulnerabilities) can have a merge request created to automatically solve the issue. If this action is available, the vulnerability page or modal contains a **Create merge request** button. @@ -237,25 +294,6 @@ Click this button to create a merge request to apply the solution onto the sourc  -### Creating an issue for a vulnerability - -You can create an issue for a vulnerability by visiting the vulnerability's page and clicking -**Create issue**, which you can find in the **Related issues** section. - - - -This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the -vulnerability came from, and pre-populates it with some useful information taken from the vulnerability -report. Once the issue is created, you are redirected to it so you can edit, assign, or comment on -it. CVE identifiers can be requested from GitLab by clicking the -[_CVE ID Request_ button](cve_id_request.md) that is enabled for maintainers of -public projects on GitLab.com - -Upon returning to the group security dashboard, the vulnerability now has an associated issue next -to the name. - - - ### Managing related issues for a vulnerability Issues can be linked to a vulnerability using the related issues block on the vulnerability page. @@ -320,7 +358,7 @@ appears:  -If at least one security scanner is enabled, you will be able to enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you will be able to enable the `License-Check` rule. +If at least one security scanner is enabled, you can enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you can enable the `License-Check` rule.  @@ -566,3 +604,36 @@ Additionally, we provide a dedicated project containing the versioned legacy tem This can be useful for offline setups or anyone wishing to use [Auto DevOps](../../topics/autodevops/index.md). Instructions are available in the [legacy template project](https://gitlab.com/gitlab-org/auto-devops-v12-10). + +#### Vulnerabilities are found, but the job succeeds. How can I have a pipeline fail instead? + +This is the current default behavior, because 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](sast/index.md) +or [Security Dashboard](security_dashboard/index.md). +There is [an open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/235772) in which changes to this behavior are being discussed. + +### Enable or disable the basic security widget **(CORE ONLY)** + +The basic security widget is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +# For the instance +Feature.enable(:core_security_mr_widget) +# For a single project +Feature.enable(:core_security_mr_widget, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# For the instance +Feature.disable(:core_security_mr_widget) +# For a single project +Feature.disable(:core_security_mr_widget, Project.find(<project id>)) +``` |