diff options
Diffstat (limited to 'doc/user/application_security/index.md')
| -rw-r--r-- | doc/user/application_security/index.md | 165 |
1 files changed, 68 insertions, 97 deletions
diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 82a018c0ae9..bf812b25b5f 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,11 +1,11 @@ --- -stage: secure -group: secure +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/engineering/ux/technical-writing/#assignments type: reference, howto --- -# Application security **(ULTIMATE)** +# Secure your application **(ULTIMATE)** GitLab can check your application for security vulnerabilities including: @@ -92,7 +92,9 @@ For more details about each of the security scanning tools, see their respective By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the base address for Docker images. You can override this globally by setting the CI/CD variable -`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. +`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once, except +the container-scanning analyzer which uses +`registry.gitlab.com/security-products/container-scanning` as its registry. ### Use security scanning tools with Pipelines for Merge Requests @@ -182,84 +184,51 @@ By default, the vulnerability report does not show vulnerabilities of `dismissed > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2. -Merge Request Approvals can be configured to require approval from a member of your -security team when a merge request would introduce one of the following security issues: +You can implement merge request approvals to require approval by selected users or a group when a +merge request would introduce one of the following security issues: - A security vulnerability - A software license compliance violation -The security vulnerability threshold is defined as `high`, `critical`, or `unknown` severity. The -`Vulnerability-Check` approver group must approve merge requests that contain vulnerabilities. +When the Vulnerability-Check merge request rule is enabled, additional merge request approval +is required when the latest security report in a merge request: -When GitLab can assess vulnerability severity, the rating can be one of the following: - -- `unknown` -- `low` -- `medium` -- `high` -- `critical` +- Contains a vulnerability of `high`, `critical`, or `unknown` severity that is not present in the + target branch. Note that approval is still required for dismissed vulnerabilities. +- Is not generated during pipeline execution. -The rating `unknown` indicates that the underlying scanner doesn't contain or provide a severity -rating. +An approval is optional when the security report: -### Enabling Security Approvals within a project +- Contains no new vulnerabilities when compared to the target branch. +- Contains only new vulnerabilities of `low` or `medium` severity. -To enable the `Vulnerability-Check` or `License-Check` Security Approvals, a [project approval rule](../project/merge_requests/approvals/rules.md#add-an-approval-rule) -must be created. A [security scanner job](#security-scanning-tools) must be enabled for -`Vulnerability-Check`, and a [license scanning](../compliance/license_compliance/index.md#configuration) -job must be enabled for `License-Check`. When the proper jobs aren't configured, the following -appears: +When the License-Check merge request rule is enabled, additional approval is required if a merge +request contains a denied license. For more details, see [Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). - +### Enable the Vulnerability-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. +Prerequisites: - +- At least one [security scanner job](#security-scanning-tools) must be enabled. +- Maintainer or Owner [role](../permissions.md#project-members-permissions). -For this approval group, you must set the number of approvals required to greater than zero. You -must have Maintainer or Owner [permissions](../permissions.md#project-members-permissions) -to manage approval rules. +For this approval group, you must set the number of approvals required to greater than zero. Follow these steps to enable `Vulnerability-Check`: -1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. -1. Click **Enable**, or **Edit**. +1. Go to your project and select **Settings > General**. +1. Expand **Merge request approvals**. +1. Select **Enable** or **Edit**. 1. Add or change the **Rule name** to `Vulnerability-Check` (case sensitive). - - +1. Set the **No. of approvals required** to greater than zero. +1. Select the **Target branch**. +1. Select the users or groups to provide approval. +1. Select **Add approval rule**. Once this group is added to your project, the approval rule is enabled for all merge requests. - Any code changes cause the approvals required to reset. -An approval is required when the latest security report in a merge request: - -- Contains a vulnerability of `high`, `critical`, or `unknown` severity that is not present in the - target branch. Note that approval is still required for dismissed vulnerabilities. -- Is not generated during pipeline execution. - -An approval is optional when the security report: - -- Contains no new vulnerabilities when compared to the target branch. -- Contains only new vulnerabilities of `low` or `medium` severity. - -### Enabling License Approvals within a project - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. - -`License-Check` is a [security approval rule](#enabling-security-approvals-within-a-project) -you can enable to allow an individual or group to approve a merge request that contains a `denied` -license. For instructions on enabling this rule, see -[Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). - -## Working in an offline environment - -It is possible to run most of the GitLab security scanners when not -connected to the internet, in what is sometimes known as an offline, -limited connectivity, Local Area Network (LAN), Intranet, or "air-gap" -environment. - -Read how to [operate the Secure scanners in an offline environment](offline_deployments/index.md). + ## Using private Maven repositories @@ -290,47 +259,22 @@ under your project's settings: </settings> ``` -## Outdated security reports - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4913) in GitLab 12.7. - -When a security report generated for a merge request becomes outdated, the merge request shows a warning -message in the security widget and prompts you to take an appropriate action. - -This can happen in two scenarios: - -1. Your [source branch is behind the target branch](#source-branch-is-behind-the-target-branch). -1. The [target branch security report is out of date](#target-branch-security-report-is-out-of-date). - -### Source branch is behind the target branch - -This means the most recent common ancestor commit between the target branch and the source branch is -not the most recent commit on the target branch. This is by far the most common situation. - -In this case you must rebase or merge to incorporate the changes from the target branch. - - - -### Target branch security report is out of date - -This can happen for many reasons, including failed jobs or new advisories. When the merge request shows that a -security report is out of date, you must run a new pipeline on the target branch. -You can do it quickly by following the hyperlink given to run a new pipeline. - - - ## DAST On-Demand Scans If you don’t want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. ## Security report validation -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. +> - Schema validation message [added](https://gitlab.com/gitlab-org/gitlab/-/issues/321730) in GitLab 14.0. -As of GitLab 13.11, we've introduced the **optional** validation of the security report artifacts based on the +You can optionally enable validation of the security report artifacts based on the [report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/tree/master/dist). If you enable validation, GitLab validates the report artifacts before ingesting the vulnerabilities. -This prevents ingesting broken vulnerability data into the database. +This prevents ingestion of broken vulnerability data into the database. + +In GitLab 14.0 and later, the pipeline's **Security** tab lists any report artifacts +that failed validation. Security report validation must first be enabled. ### Enable security report validation @@ -381,14 +325,41 @@ For more details about which findings or vulnerabilities you can view in each of - Change the status. - Create an issue. - Link it to an existing issue. -- In some cases, [apply an automatic remediation for a vulnerability](vulnerabilities/index.md#remediate-a-vulnerability-automatically). +- [Resolve the vulnerability](vulnerabilities/index.md#resolve-a-vulnerability), if a solution is known. ## Troubleshooting +### Outdated security reports + +When a security report generated for a merge request becomes outdated, the merge request shows a warning +message in the security widget and prompts you to take an appropriate action. + +This can happen in two scenarios: + +- Your [source branch is behind the target branch](#source-branch-is-behind-the-target-branch). +- The [target branch security report is out of date](#target-branch-security-report-is-out-of-date). + +#### Source branch is behind the target branch + +This means the most recent common ancestor commit between the target branch and the source branch is +not the most recent commit on the target branch. This is by far the most common situation. + +In this case you must rebase or merge to incorporate the changes from the target branch. + + + +#### Target branch security report is out of date + +This can happen for many reasons, including failed jobs or new advisories. When the merge request shows that a +security report is out of date, you must run a new pipeline on the target branch. +You can do it quickly by following the hyperlink given to run a new pipeline. + + + ### Getting error message `sast job: stage parameter should be [some stage name here]` When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template -like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), +like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), the following error may occur, depending on your GitLab CI/CD configuration: ```plaintext @@ -441,7 +412,7 @@ This provides useful information to investigate further. ### Getting error message `sast job: config key may not be used with 'rules': only/except` When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template -like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), +like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), the following error may occur, depending on your GitLab CI/CD configuration: ```plaintext |