From 141e356de1b9351c532695aae7447e79cfe01872 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 10 Sep 2019 10:06:45 +0000 Subject: [PATCH] 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 --- .../dependency_scanning/index.md | 68 ++++++++++--------- doc/user/application_security/index.md | 25 +++---- 2 files changed, 47 insertions(+), 46 deletions(-) diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index d7b2572c717..166a71b6fbe 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -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). diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 69529d7420b..f25d792cb90 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.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.