Commit f71b4946 authored by Evan Read's avatar Evan Read

Merge branch 'russell/edit-application-security-part-3' into 'master'

Improve Application Security content structure

See merge request gitlab-org/gitlab!60684
parents de52a3a2 0e145c64
......@@ -184,39 +184,33 @@ 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).
![Un-configured Approval Rules](img/unconfigured_security_approval_rules_and_jobs_v13_4.png)
### 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:
![Un-configured Approval Rules with valid pipeline jobs](img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png)
- At least one [security scanner job](#security-scanning-tools) must be enabled.
- Maintainer or Owner [permissions](../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)
......@@ -224,44 +218,19 @@ to manage approval rules.
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).
![Vulnerability Check Approver Rule](img/vulnerability-check_v13_4.png)
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).
![Vulnerability Check Approver Rule](img/vulnerability-check_v13_4.png)
## Using private Maven repositories
......@@ -292,35 +261,6 @@ 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.
![Incorporate target branch changes](img/outdated_report_branch_v12_9.png)
### 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.
![Run a new pipeline](img/outdated_report_pipeline_v12_9.png)
## 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.
......@@ -329,10 +269,10 @@ If you don’t want scans running in your normal DevOps process you can use on-d
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11.
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.
### Enable security report validation
......@@ -387,6 +327,33 @@ For more details about which findings or vulnerabilities you can view in each of
## 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.
![Incorporate target branch changes](img/outdated_report_branch_v12_9.png)
#### 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.
![Run a new pipeline](img/outdated_report_pipeline_v12_9.png)
### 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
......
......@@ -93,8 +93,7 @@ above. You can find more information at each of the pages below:
## Loading Docker images onto your offline host
To use many GitLab features, including
[security scans](../index.md#working-in-an-offline-environment)
To use many GitLab features, including security scans
and [Auto DevOps](../../../topics/autodevops/index.md), the runner must be able to fetch the
relevant Docker images.
......
......@@ -680,8 +680,9 @@ Developers of the project can view the policies configured in 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](../../application_security/index.md#enabling-security-approvals-within-a-project) rule you can enable to allow an individual or group to approve a
merge request that contains a `denied` license.
`License-Check` is a [merge request approval](../../project/merge_requests/approvals/index.md) rule
you can enable to allow an individual or group to approve a merge request that contains a `denied`
license.
You can enable `License-Check` one of two ways:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment