Commit 141e356d authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Refactor the Dependency Scanning docs

Notably:

- Merge the use cases with the opening paragraph of DS
- Add link to the auto-remediation section in the main index page
- Add auto remediation to the title of solutions for better SEO
- Move the JSON reports section below the other more important sections
- Remove Container Scanning from the list of supported scanners in
  solutions
- Fix some "introduced in" sentences so that they can be properly parsed
parent 23198926
......@@ -4,8 +4,11 @@ type: reference, howto
# Dependency Scanning **(ULTIMATE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105)
in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7.
Dependency Scanning helps to automatically find security vulnerabilities in your dependencies
while you are developing and testing your applications, for example when your
application is using an external (open source) library which is known to be vulnerable.
## Overview
......@@ -18,7 +21,7 @@ in your existing `.gitlab-ci.yml` file or by implicitly using
that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
GitLab checks the Dependency Scanning report, compares the found vulnerabilities
between the source and target branches, and shows the information right on the
between the source and target branches, and shows the information on the
merge request.
![Dependency Scanning Widget](img/dependency_scanning.png)
......@@ -32,12 +35,6 @@ The results are sorted by the severity of the vulnerability:
1. Unknown
1. Everything else
## Use cases
It helps to automatically find security vulnerabilities in your dependencies
while you are developing and testing your applications. For example when your
application is using an external (open source) library which is known to be vulnerable.
## Requirements
To run a Dependency Scanning job, you need GitLab Runner with the
......@@ -162,10 +159,39 @@ using environment variables.
| `PIP_INDEX_URL` | Base URL of Python Package Index (default `https://pypi.org/simple`). | |
| `PIP_EXTRA_INDEX_URL` | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma separated. | |
## Interacting with the vulnerabilities
Once a vulnerability is found, you can interact with it. Read more on how to
[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities).
## Solutions for vulnerabilities (auto-remediation)
Some vulnerabilities can be fixed by applying the solution that GitLab
automatically generates.
Read more about the [solutions for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation).
## Security Dashboard
The Security Dashboard is a good place to get an overview of all the security
vulnerabilities in your groups, projects and pipelines. Read more about the
[Security Dashboard](../security_dashboard/index.md).
## Vulnerabilities database update
For more information about the vulnerabilities database update, check the
[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database).
## Dependency List
An additional benefit of Dependency Scanning is the ability to view your
project's dependencies and their known vulnerabilities. Read more about
the [Dependency List](../dependency_list/index.md).
## Reports JSON format
CAUTION: **Caution:**
The JSON report artifacts are not a public API of Dependency Scanning and their format may change in future.
The JSON report artifacts are not a public API of Dependency Scanning and their format may change in the future.
The Dependency Scanning tool emits a JSON report file. Here is an example of the report structure with all important parts of
it highlighted:
......@@ -315,28 +341,6 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
| `remediations[].summary` | Overview of how the vulnerabilities have been fixed. |
| `remediations[].diff` | base64-encoded remediation code diff, compatible with [`git apply`](https://git-scm.com/docs/git-format-patch#_discussion). |
## Security Dashboard
The Security Dashboard is a good place to get an overview of all the security
vulnerabilities in your groups, projects and pipelines. Read more about the
[Security Dashboard](../security_dashboard/index.md).
## Interacting with the vulnerabilities
Once a vulnerability is found, you can interact with it. Read more on how to
[interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities).
## Vulnerabilities database update
For more information about the vulnerabilities database update, check the
[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database).
## Dependency List **(ULTIMATE)**
An additional benefit of Dependency Scanning is the ability to view your
project's dependencies and their known vulnerabilities. Read more about
the [Dependency List](../dependency_list/index.md).
## Versioning and release process
Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md).
......
......@@ -71,8 +71,7 @@ entry, a detailed information will pop up with different possible options:
- [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.
- [Solution](#solutions-for-vulnerabilities): For some vulnerabilities
([Dependency Scanning](dependency_scanning/index.md) and [Container Scanning](container_scanning/index.md))
- [Solution](#solutions-for-vulnerabilities-auto-remediation): For some vulnerabilities,
a solution is provided for how to fix the vulnerability.
![Interacting with security reports](img/interactive_reports.png)
......@@ -109,17 +108,16 @@ the vulnerability will now have an associated issue next to the name.
![Linked issue in the group security dashboard](img/issue.png)
### Solutions for vulnerabilities
### Solutions for vulnerabilities (auto-remediation)
> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.7.
CAUTION: **Warning:**
Automatic Patch creation is only available for a subset of
[Dependency Scanning](dependency_scanning/index.md). At the moment only Node.JS
projects managed with yarn are supported.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/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.
automatically generates. The following scanners are supported:
- [Dependency Scanning](dependency_scanning/index.md):
Automatic Patch creation is only available for Node.JS projects managed with
`yarn`.
#### Manually applying the suggested patch
......@@ -136,13 +134,12 @@ generated by GitLab. To apply the fix:
#### Creating a merge request from a vulnerability
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9224) in
> [GitLab Ultimate](https://about.gitlab.com/pricing) 11.9.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/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
[solution](#solutions-for-vulnerabilities) can have a merge request created to
automatically solve the issue.
[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.
......
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