Add documentation for Dependency Scanning feature and improve other security...

Add documentation for Dependency Scanning feature and improve other security products docs. Refs #5105

doc/ci/examples/README.md

@@ -49,6 +49,10 @@ There's also a collection of repositories with [example projects](https://gitlab
 
 **(Ultimate)** [Scan your code for vulnerabilities](sast.md)
 
+## Dependency Scanning
+
+**(Ultimate)** [Scan your dependencies for vulnerabilities](dependency_scanning.md)
+
 ## Container Scanning
 
 [Scan your Docker images for vulnerabilities](container_scanning.md)

doc/ci/examples/dependency_scanning.md

+# Dependency Scanning with GitLab CI/CD
+
+NOTE: **Note:**
+In order to use this tool, a [GitLab Ultimate][ee] license
+is needed.
+
+This example shows how to run Dependency Scanning on your
+project's dependencies by using GitLab CI/CD.
+
+First, you need GitLab Runner with [docker-in-docker executor](https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#use-docker-in-docker-executor).
+You can then add a new job to `.gitlab-ci.yml`, called `dependency_scanning`:
+
+```yaml
+dependency_scanning:
+  image: docker:latest
+  variables:
+    DOCKER_DRIVER: overlay2
+  allow_failure: true
+  services:
+    - docker:dind
+  script:
+    - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
+    - docker run
+        --env DEP_SCAN_DISABLE_REMOTE_CHECKS="${DEP_SCAN_DISABLE_REMOTE_CHECKS:-false}" \
+        --volume "$PWD:/code" \
+        --volume /var/run/docker.sock:/var/run/docker.sock \
+        "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$SP_VERSION" /code
+  artifacts:
+    paths: [gl-dependency-scanning-report.json]
+```
+
+The above example will create a `dependency_scanning` job in the `test` stage and will create the required report artifact. Check the
+[Auto-DevOps template](https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml)
+for a full reference.
+
+The results are sorted by the priority of the vulnerability:
+
+1. High
+1. Medium
+1. Low
+1. Unknown
+1. Everything else
+
+Behind the scenes, the [GitLab Dependency Scanning Docker image](https://gitlab.com/gitlab-org/security-products/dependency-scanning)
+is used to detect the languages/package managers and in turn runs the matching scan tools.
+
+Some security scanners require to send a list of project dependencies to GitLab
+central servers to check for vulnerabilities. To learn more about this or to
+disable it, check the [GitLab Dependency Scanning documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).
+
+TIP: **Tip:**
+Starting with [GitLab Ultimate][ee] 10.7, this information will
+be automatically extracted and shown right in the merge request widget. To do
+so, the CI job must be named `dependency_scanning` and the artifact path must be
+`gl-dependency-scanning-report.json`. Make sure your pipeline has a stage nammed `test`,
+or specify another existing stage inside the `dependency_scanning` job.
+[Learn more on dependency scanning results shown in merge requests](../../user/project/merge_requests/dependency_scanning.md).
+
+## Supported languages and package managers
+
+See [the full list of supported languages and package managers](../../user/project/merge_requests/dependency_scanning.md#supported-languages-and-frameworks).
+
+[ee]: https://about.gitlab.com/products/

doc/ci/examples/sast.md

@@ -20,13 +20,12 @@ sast:
   services:
     - docker:dind
   script:
-    - export SAST_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
-    - docker run 
-        --env SAST_CONFIDENCE_LEVEL="${SAST_CONFIDENCE_LEVEL:-3}" 
-        --env SAST_DISABLE_REMOTE_CHECKS="${SAST_DISABLE_REMOTE_CHECKS:-false}" 
-        --volume "$PWD:/code" 
-        --volume /var/run/docker.sock:/var/run/docker.sock 
-        "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code
+    - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
+    - docker run
+        --env SAST_CONFIDENCE_LEVEL="${SAST_CONFIDENCE_LEVEL:-3}"
+        --volume "$PWD:/code"
+        --volume /var/run/docker.sock:/var/run/docker.sock
+        "registry.gitlab.com/gitlab-org/security-products/sast:$SP_VERSION" /app/bin/run /code
   artifacts:
     paths: [gl-sast-report.json]
 ```

doc/topics/autodevops/index.md

@@ -20,6 +20,7 @@ project in an easy and automatic way:
 1. [Auto Test](#auto-test)
 1. [Auto Code Quality](#auto-code-quality)
 1. [Auto SAST (Static Application Security Testing)](#auto-sast)
+1. [Auto Dependency Scanning](#auto-dependency-scanning)
 1. [Auto Container Scanning](#auto-container-scanning)
 1. [Auto Review Apps](#auto-review-apps)
 1. [Auto DAST (Dynamic Application Security Testing)](#auto-dast)
@@ -217,6 +218,19 @@ check out.
 In GitLab Ultimate, any security warnings are also
 [shown in the merge request widget](../../user/project/merge_requests/sast.md).
 
+### Auto Dependency Scanning
+
+> Introduced in [GitLab Ultimate][ee] 10.7.
+
+Dependency Scanning uses the
+[Dependency Scanning Docker image](https://gitlab.com/gitlab-org/security-products/dependency-scanning)
+to run analysis on the project dependencies and checks for potential security issues. Once the
+report is created, it's uploaded as an artifact which you can later download and
+check out.
+
+In GitLab Ultimate, any security warnings are also
+[shown in the merge request widget](../../user/project/merge_requests/dependency_scanning.md).
+
 ### Auto Container Scanning
 
 > Introduced in GitLab 10.4.
@@ -454,7 +468,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac
 | `POSTGRES_DB`       | The PostgreSQL database name; defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-variables-environment-variables). Set it to use a custom database name. |
 | `BUILDPACK_URL`  | The buildpack's full URL. It can point to either Git repositories or a tarball URL. For Git repositories, it is possible to point to a specific `ref`, for example `https://github.com/heroku/heroku-buildpack-ruby.git#v142`|
 | `SAST_CONFIDENCE_LEVEL`  | The minimum confidence level of security issues you want to be reported; `1` for Low, `2` for Medium, `3` for High; defaults to `3`.|
-| `SAST_DISABLE_REMOTE_CHECKS`  | Whether remote SAST checks are disabled; defaults to `"false"`. Set to `"true"` to disable SAST checks that send data to GitLab central servers. [Read more about remote checks](https://gitlab.com/gitlab-org/security-products/sast#remote-checks).|
+| `DEP_SCAN_DISABLE_REMOTE_CHECKS` | Whether remote Dependency Scanning checks are disabled; defaults to `"false"`. Set to `"true"` to disable checks that send data to GitLab central servers. [Read more about remote checks](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).|
 
 TIP: **Tip:**
 Set up the replica variables using a

doc/user/project/merge_requests/dependency_scanning.md

+# Dependency Scanning
+
+> [Introduced][ee-5105] in [GitLab Ultimate][ee] 10.7.
+
+## Overview
+
+If you are using [GitLab CI/CD][ci], you can analyze your dependencies for known
+vulnerabilities using Dependency Scanning, either by
+including the CI job in your [existing `.gitlab-ci.yml` file][cc-docs] or
+by implicitly using [Auto Dependency Scanning](../../../topics/autodevops/index.md#auto-dependency-scanning)
+that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
+
+Going a step further, GitLab can show the vulnerability list right in the merge
+request widget area.
+
+## Use cases
+
+It helps you automatically find security vulnerabilities in your dependencies
+while you are developing and testing your applications. E.g. your application
+is using an external (open source) library which is known to be vulnerable.
+
+## Supported languages and dependency managers
+
+The following languages and dependency managers are supported.
+
+| Language (package managers)                                                 | Scan tool                                                                                                                         |
+|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js)         |
+| Python ([pip](https://pip.pypa.io/en/stable/))                              | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium)                                                            |
+| Ruby ([gem](https://rubygems.org/))                                         | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) |
+| Java ([Maven](https://maven.apache.org/))                                   | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium)                                                            |
+| PHP ([Composer](https://getcomposer.org/))                                  | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium)                                                            |
+
+Some scanners require to send a list of project dependencies to GitLab central servers to check for vulnerabilities. To learn more about this or to disable it please
+check [GitLab Dependency Scanning documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).
+
+## How it works
+
+First of all, you need to define a job named `dependency_scanning` in your
+`.gitlab-ci.yml` file. [Check how the `dependency_scanning` job should look like][cc-docs].
+
+In order for the report to show in the merge request, there are two
+prerequisites:
+
+- the specified job **must** be named `dependency_scanning`
+- the resulting report **must** be named `gl-dependency-scanning-report.json`
+  and uploaded as an artifact
+
+The `dependency_scanning` job will perform an analysis on the application
+dependencies, the resulting JSON file will be uploaded as an artifact, and
+GitLab will then check this file and show the information inside the merge
+request.
+
+![Dependency Scanning Widget](img/dependency_scanning.png)
+
+[ee-4682]: https://gitlab.com/gitlab-org/gitlab-ee/issues/4682
+[ee-5105]: https://gitlab.com/gitlab-org/gitlab-ee/issues/5105
+[ee]: https://about.gitlab.com/products/
+[ci]: ../../../ci/README.md
+[cc-docs]: ../../../ci/examples/dependency_scanning.md

doc/user/project/merge_requests/index.md

@@ -35,7 +35,11 @@ With **[GitLab Enterprise Edition][ee]**, you can also:
 - View the deployment process across projects with [Multi-Project Pipeline Graphs](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html#multi-project-pipeline-graphs) (available only in GitLab Premium)
 - Request [approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers (available in GitLab Starter)
 - [Squash and merge](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html) for a cleaner commit history (available in GitLab Starter)
-- Analyze the impact of your changes with [Code Quality reports](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html) (available in GitLab Starter)
+- Analyze the impact of your changes with [Code Quality](#code-quality) (available in GitLab Starter)
+- Analyze your source code for vulnerabilities with [Static Application Security Testing](#static-application-security-testing) (available in GitLab Ultimate)
+- Analyze your dependencies for vulnerabilities with [Dependency Scanning](#dependency-scanning) (available in GitLab Ultimate)
+- Analyze your Docker images for vulnerabilities with [Container Scanning](#container-scanning) (available in GitLab Ultimate)
+- Analyze your running web applications for vulnerabilities with [Dynamic Application Security Testing](#dynamic-application-security-testing) (available in GitLab Ultimate)
 - Determine the performance impact of changes with [Browser Performance Testing](#browser-performance-testing) (available in GitLab Premium)
 
 ## Use cases
@@ -44,7 +48,7 @@ A. Consider you are a software developer working in a team:
 
 1. You checkout a new branch, and submit your changes through a merge request
 1. You gather feedback from your team
-1. You work on the implementation optimizing code with [Code Quality reports](#code-quality-reports)
+1. You work on the implementation optimizing code with [Code Quality](#code-quality)
 1. You build and test your changes with GitLab CI/CD
 1. You request the [approval](#merge-request-approvals) from your manager
 1. Your manager pushes a commit with his final review, [approves the merge request](#merge-request-approvals), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds)
@@ -207,7 +211,7 @@ list of approvers that will need to approve every merge request in a project.
 
 [Read more about merge request approvals.](merge_request_approvals.md)
 
-## Code Quality reports
+## Code Quality
 
 > Introduced in [GitLab Starter][products] 9.3.
 
@@ -228,6 +232,17 @@ merge request widget area.
 
 [Read more about Static Application Security Testing reports.](sast.md)
 
+## Dependency Scanning
+
+> Introduced in [GitLab Ultimate][products] 10.7.
+
+If you are using [GitLab CI/CD][ci], you can analyze your dependencies for known
+vulnerabilities using Dependency Scanning.
+Going a step further, GitLab can show the vulnerability report right in the
+merge request widget area.
+
+[Read more about Dependency Scanning reports.](dependency_scanning.md)
+
 ## Container Scanning
 
 > Introduced in [GitLab Ultimate][products] 10.4.

doc/user/project/merge_requests/sast.md

@@ -25,17 +25,12 @@ request widget area.
 
 The following languages and frameworks are supported.
 
-| Language (package managers) / framework | Scan tool |
-| ---------------------- | --------- |
-| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js)
-| Python ([pip](https://pip.pypa.io/en/stable/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bandit](https://github.com/openstack/bandit) |
-| Ruby ([gem](https://rubygems.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) |
-| Ruby on Rails | [brakeman](https://brakemanscanner.org) |
-| Java ([Maven](https://maven.apache.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [find-sec-bugs](https://find-sec-bugs.github.io/) |
-| PHP ([Composer](https://getcomposer.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
-
-Some security scanners require to send a list of project dependencies to GitLab central servers to check for vulnerabilities. To learn more about this or to disable it please
-check [GitLab SAST documentation](https://gitlab.com/gitlab-org/security-products/sast#remote-checks).
+| Language / framework | Scan tool                                          |
+|----------------------|----------------------------------------------------|
+| C/C++                | [Flawfinder](https://www.dwheeler.com/flawfinder/) |
+| Python               | [bandit](https://github.com/openstack/bandit)      |
+| Ruby on Rails        | [brakeman](https://brakemanscanner.org)            |
+| Java                 | [find-sec-bugs](https://find-sec-bugs.github.io/)  |
 
 ## How it works
 
@@ -53,7 +48,7 @@ The `sast` job will perform an analysis on the running web application, the
 resulting JSON file will be uploaded as an artifact, and GitLab will then check
 this file and show the information inside the merge request.
 
-![SAST Widget](img/gemnasium.png)
+![SAST Widget](img/sast.png)
 
 ## Security report under pipelines