Skip to content

G
gitlab-ce
Commit b6a3bd97 authored by Russell Dickenson's avatar Russell Dickenson
Browse files
Options

Merge branch 'docs-secure-edit' into 'master' 

Wordsmithing for Secure intro

See merge request gitlab-org/gitlab!24715
parents b6ae072f 15ec069f
Show whitespace changes
Inline Side-by-side
Showing with 65 additions and 77 deletions
doc/user/application_security/index.md
View file @ b6a3bd97
......@@ -4,23 +4,18 @@ type: reference, howto
# GitLab Secure **(ULTIMATE)**
Check your application for security vulnerabilities that may lead to
unauthorized access, data leaks, and denial of services.
GitLab can check your application for security vulnerabilities that may lead to unauthorized access,
data leaks, denial of services, and more. GitLab reports vulnerabilities in the merge request so you
can fix them before merging. The [Security Dashboard](security_dashboard/index.md) provides a
high-level view of vulnerabilities detected in your projects, pipeline, and groups. With the
information provided, you can immediately begin risk analysis and remediation.
GitLab will perform static and dynamic tests on the code of your application,
looking for known flaws and report them in the merge request so you can fix
them before merging.
Security teams can use dashboards to get a high-level view on projects and
groups, and start remediation processes when needed.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview of application security with GitLab, see
[Security Deep Dive](https://www.youtube.com/watch?v=k4vEJnGYy84).
## Security scanning tools
GitLab can scan and report any vulnerabilities found in your project.
GitLab uses the following tools to scan and report known vulnerabilities found in your project.
| Secure scanning tool | Description |
|:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------|
......@@ -34,26 +29,22 @@ GitLab can scan and report any vulnerabilities found in your project.
## Maintenance and update of the vulnerabilities database
The various scanning tools and the vulnerabilities database are updated regularly.
The scanning tools and vulnerabilities database are updated regularly.
| Secure scanning tool | Vulnerabilities database updates |
|:-------------------------------------------------------------|-------------------------------------------|
| [Container Scanning](container_scanning/index.md) | Uses `clair` underneath and the latest `clair-db` version is used for each job run 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 Rubygems), `retire.js` (for NPM packages) and `gemnasium` (GitLab's own tool for all libraries). `bundler-audit` and `retire.js` both 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. |
| [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 the runtime of the scan. |
| [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab is wrapping](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. |
You don't have to update GitLab to benefit from the latest vulnerabilities definitions,
but you may have to in the future.
The security tools are released as Docker images, and the vendored job definitions
to enable them are using the `x-y-stable` image tags that get overridden each time a new
release of the tools is pushed. The Docker images are updated to match the
previous GitLab releases, so they automatically get the latest versions of the
scanning tools without the user having to do anything.
This workflow comes with some drawbacks and there's a
[plan to change this](https://gitlab.com/gitlab-org/gitlab/issues/9725).
| [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 Rubygems), `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. |
| [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. |
Currently, you do not have to update GitLab to benefit from the latest vulnerabilities definitions.
The security tools are released as Docker images. The vendored job definitions to enable them use
the `x-y-stable` image tags that get overridden each time a new release of the tools is pushed. The
Docker images are updated to match the previous GitLab releases, so users automatically get the
latest versions of the scanning tools without having to do anything. There are some known issues
with this approach, however, and there is a
[plan to resolve them](https://gitlab.com/gitlab-org/gitlab/issues/9725).
## Interacting with the vulnerabilities
......@@ -63,14 +54,14 @@ CAUTION: **Warning:**
This feature is currently [Alpha](https://about.gitlab.com/handbook/product/#alpha-beta-ga) and while you can start using it, it may receive important changes in the future.
Each security vulnerability in the merge request report or the
[Security Dashboard](security_dashboard/index.md) is actionable. Clicking on an
entry, a detailed information will pop up with different possible options:
- [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability
will place a ~~strikethrough~~ styling on it.
- [Create issue](#creating-an-issue-for-a-vulnerability): The new issue will
have the title and description pre-populated with the information from the
vulnerability report and will be created as [confidential](../project/issues/confidential_issues.md) by default.
[Security Dashboard](security_dashboard/index.md) is actionable. Click an entry to view detailed
information with several options:
- [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability styles it in
strikethrough.
- [Create issue](#creating-an-issue-for-a-vulnerability): Create a new issue with the title and
description prepopulated 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,
a solution is provided for how to fix the vulnerability.
......@@ -88,8 +79,8 @@ If you wish to undo this dismissal, you can click the **Undo dismiss** button.
When dismissing a vulnerability, it's often helpful to provide a reason for doing so.
If you press the comment button next to **Dismiss vulnerability** in the modal,
a text box will appear, allowing you to add a comment with your dismissal.
Once added, you can edit it or delete it. This allows you to add and update
a text box appears for you to add a comment with your dismissal.
Once added, you can edit or delete it. This allows you to add and update
context for a vulnerability as you learn more over time.
![Dismissed vulnerability comment](img/dismissed_info_v12_3.png)
......@@ -97,16 +88,16 @@ context for a vulnerability as you learn more over time.
### Creating an issue for a vulnerability
You can create an issue for a vulnerability by selecting the **Create issue**
button from within the vulnerability modal or using the action buttons to the right of
a vulnerability row when in the group security dashboard.
button from within the vulnerability modal, or by using the action buttons to the right of
a vulnerability row in the group security dashboard.
This will create a [confidential issue](../project/issues/confidential_issues.md)
on the project this vulnerability came from and pre-fill it with some useful
information taken from the vulnerability report. Once the issue is created, you
will be redirected to it so you can edit, assign, or comment on it.
This creates a [confidential issue](../project/issues/confidential_issues.md) in the project the
vulnerability came from, and prepopulates 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, you'll see that
the vulnerability will now have an associated issue next to the name.
Upon returning to the group security dashboard, the vulnerability now has an associated issue next
to the name.
![Linked issue in the group security dashboard](img/issue.png)
......@@ -126,7 +117,7 @@ automatically generates. The following scanners are supported:
Some vulnerabilities can be fixed by applying a patch that is automatically
generated by GitLab. To apply the fix:
1. Click on the vulnerability.
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`.
......@@ -138,13 +129,13 @@ generated by GitLab. To apply the fix:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9.
In certain cases, GitLab will allow you to create a merge request that will
automatically remediate the vulnerability. Any vulnerability that has a
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
request created to automatically solve the issue.
If this action is available there will be a **Create merge request** button in the vulnerability modal.
Clicking on this button will create a merge request to apply the solution onto the source branch.
If this action is available, the vulnerability modal contains a **Create merge request** button.
Click this button to create a merge request to apply the solution onto the source branch.
![Create merge request from vulnerability](img/create_issue_with_list_hover.png)
......@@ -155,30 +146,29 @@ Clicking on this button will create a merge request to apply the solution onto t
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:
- a security vulnerability
- a software license compliance violation
- A security vulnerability
- A software license compliance violation
This threshold is defined as `high`, `critical`, or `unknown`
severity. When any vulnerabilities are present within a merge request, an
approval will be required from the `Vulnerability-Check` approver group.
This threshold is defined as `high`, `critical`, or `unknown` severity. When any vulnerabilities are
present within a merge request, an approval is required from the `Vulnerability-Check` approver
group.
### Enabling Security Approvals within a project
To enable Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium)
must be created with the case-sensitive name `Vulnerability-Check`. This approval
group must be set with an "Approvals required" count greater than zero.
must be created with the case-sensitive name `Vulnerability-Check`. This approval group must be set
with the number of approvals required greater than zero.
Once this group has been added to your project, the approval rule will be enabled
for all Merge Requests.
Once this group is added to your project, the approval rule is enabled for all merge requests.
Any code changes made will cause the count of approvals required to reset.
Any code changes cause the approvals required to reset.
An approval will be required when a security report:
An approval is required when a security report:
- Contains a new vulnerability of `high`, `critical`, or `unknown` severity.
- Is not generated during pipeline execution.
An approval will be optional when a security report:
An approval is optional when a security report:
- Contains no new vulnerabilities.
- Contains only new vulnerabilities of `low` or `medium` severity.
......@@ -186,22 +176,22 @@ An approval will be optional when a security report:
### Enabling License Approvals within a project
To enable License Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium)
must be created with the case-sensitive name `License-Check`. This approval
group must be set with an "Approvals required" count greater than zero.
must be created with the case-sensitive name `License-Check`. This approval group must be set
with the number of approvals required greater than zero.
Once this group has been added to your project, the approval rule will be enabled
for all Merge Requests. To configure how this rule behaves, you can choose which
licenses to `approve` or `blacklist` in the
[project policies for License Compliance](license_compliance/index.md#project-policies-for-license-compliance) section.
Once this group is added to your project, the approval rule is enabled for all Merge Requests. To
configure how this rule behaves, you can choose which licenses to `approve` or `blacklist` in the
[project policies for License Compliance](license_compliance/index.md#project-policies-for-license-compliance)
section.
Any code changes made will cause the count of approvals required to reset.
Any code changes cause the approvals required to reset.
An approval will be required when a license report:
An approval is required when a license report:
- Contains a dependency that includes a software license that is `blacklisted`.
- Is not generated during pipeline execution.
An approval will be optional when a license report:
An approval is optional when a license report:
- Contains no software license violations.
- Contains only new licenses that are `approved` or unknown.
......@@ -211,7 +201,7 @@ An approval will be optional when a license report:
### Getting error message `sast job: stage parameter should be [some stage name here]`
When including a security job template like [`SAST`](sast/index.md#configuration),
the following error can be raised, depending on your GitLab CI/CD configuration:
the following error may occur, depending on your GitLab CI/CD configuration:
```plaintext
Found errors in your .gitlab-ci.yml:
......@@ -219,8 +209,7 @@ Found errors in your .gitlab-ci.yml:
* sast job: stage parameter should be unit-tests
```
This error appears when the stage (nammed `test`) of the included job isn't declared
in `.gitlab-ci.yml`.
This error appears when the included job's stage (named `test`) isn't declared in `.gitlab-ci.yml`.
To fix this issue, you can either:
- Add a `test` stage in your `.gitlab-ci.yml`.
......@@ -235,5 +224,4 @@ To fix this issue, you can either:
```
[Learn more on overriding the SAST template](sast/index.md#overriding-the-sast-template).
All the security scanning tools define their stage, so this error can occur with
all of them.
All the security scanning tools define their stage, so this error can occur with all of them.
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7