Merge branch 'docs-repo-merge-22-user-app-security' into 'master'

Docs: Merge EE doc/user/application_security to CE

See merge request gitlab-org/gitlab-ce!27945

doc/user/application_security/container_scanning/index.md

+# Container Scanning **[ULTIMATE]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672)
+in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4.
+
+## Overview
+
+If you are using [GitLab CI/CD](../../../ci/README.md), you can check your Docker
+images (or more precisely the containers) for known vulnerabilities by using
+[Clair](https://github.com/coreos/clair) and [clair-scanner](https://github.com/arminc/clair-scanner),
+two open source tools for Vulnerability Static Analysis for containers.
+
+You can take advantage of Container Scanning by either [including the CI job](#including-the-provided-template) in
+your existing `.gitlab-ci.yml` file or by implicitly using
+[Auto Container Scanning](../../../topics/autodevops/index.md#auto-container-scanning)
+that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
+
+GitLab checks the Container Scanning report, compares the found vulnerabilities
+between the source and target branches, and shows the information right on the
+merge request.
+
+![Container Scanning Widget](img/container_scanning.png)
+
+## Use cases
+
+If you distribute your application with Docker, then there's a great chance
+that your image is based on other Docker images that may in turn contain some
+known vulnerabilities that could be exploited.
+
+Having an extra job in your pipeline that checks for those vulnerabilities,
+and the fact that they are displayed inside a merge request, makes it very easy
+to perform audits for your Docker-based apps.
+
+## Requirements
+
+To enable Container Scanning in your pipeline, you need:
+
+- A GitLab Runner with the
+  [`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or
+  [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners)
+  executor running in privileged mode. If you're using the shared Runners on GitLab.com,
+  this is enabled by default.
+- To [build and push](../../../ci/docker/using_docker_build.md#container-registry-examples)
+  your Docker image to your project's [Container Registry](../../project/container_registry.md).
+  The name of the Docker image should match the following scheme:
+
+  ```
+  $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA
+  ```
+
+  The variables above can be found in the
+  [predefined environment variables](../../../ci/variables/predefined_variables.md)
+  document.
+
+## Configuring Container Scanning
+
+To enable Container Scanning in your project, define a job in your
+`.gitlab-ci.yml` file that generates the
+[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate).
+
+This can be done in two ways:
+
+- For GitLab 11.9 and later, including the provided
+  `Container-Scanning.gitlab-ci.yml` template (recommended).
+- Manually specifying the job definition. Not recommended unless using GitLab
+  11.8 and earlier.
+
+### Including the provided template
+
+NOTE: **Note:**
+The CI/CD Container Scanning template is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later).
+
+A CI/CD [Container Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml)
+with the default Container Scanning job definition is provided as a part of your GitLab
+installation that you can [include](../../../ci/yaml/README.md#includetemplate)
+in your `.gitlab-ci.yml` file.
+
+To enable Container Scanning using the provided template, add the following to
+your `.gitlab-ci.yml` file:
+
+```yaml
+include:
+  template: Container-Scanning.gitlab-ci.yml
+```
+
+The included template will:
+
+- Create a `container_scanning` job in your CI/CD pipeline.
+- Pull the already built Docker image from your project's
+  [Container Registry](../../project/container_registry.md) (see [requirements](#requirements))
+  and scan it for possible vulnerabilities.
+
+The report will be saved as a
+[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate)
+that you can later download and analyze.
+Due to implementation limitations, we always take the latest Container Scanning
+artifact available. Behind the scenes, the
+[GitLab Container Scanning analyzer](https://gitlab.com/gitlab-org/security-products/container-scanning)
+is used and runs the scans.
+
+If you want to whitelist some specific vulnerabilities, you can do so by defining
+them in a YAML file named `clair-whitelist.yml`. Read more in the
+[Clair documentation](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file).
+
+### Manual job definition for GitLab 11.5 and later
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions.
+However, if you're using GitLab 11.9+, it's recommended to use
+[the provided Container Scanning template](#including-the-provided-template).
+
+For GitLab 11.5 and GitLab Runner 11.5 and later, the following `container_scanning`
+job can be added:
+
+```yaml
+container_scanning:
+  image: docker:stable
+  variables:
+    DOCKER_DRIVER: overlay2
+    ## Define two new variables based on GitLab's CI/CD predefined variables
+    ## https://docs.gitlab.com/ee/ci/variables/#predefined-environment-variables
+    CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG
+    CI_APPLICATION_TAG: $CI_COMMIT_SHA
+  allow_failure: true
+  services:
+    - docker:stable-dind
+  script:
+    - docker run -d --name db arminc/clair-db:latest
+    - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:v2.0.6
+    - apk add -U wget ca-certificates
+    - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG}
+    - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64
+    - mv clair-scanner_linux_amd64 clair-scanner
+    - chmod +x clair-scanner
+    - touch clair-whitelist.yml
+    - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done
+    - retries=0
+    - echo "Waiting for clair daemon to start"
+    - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done
+    - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true
+  artifacts:
+    reports:
+      container_scanning: gl-container-scanning-report.json
+```
+
+### Manual job definition for GitLab 11.4 and earlier (deprecated)
+
+CAUTION: **Deprecated:**
+Before GitLab 11.5, the Container Scanning job and artifact had to be named specifically
+to automatically extract report data and show it in the merge request widget.
+While these old job definitions are still maintained, they have been deprecated
+and may be removed in the next major release, GitLab 12.0. You are strongly
+advised to update your current `.gitlab-ci.yml` configuration to reflect that change.
+
+For GitLab 11.4 and earlier, the Container Scanning job should look like:
+
+```yaml
+container_scanning:
+  image: docker:stable
+  variables:
+    DOCKER_DRIVER: overlay2
+    ## Define two new variables based on GitLab's CI/CD predefined variables
+    ## https://docs.gitlab.com/ee/ci/variables/#predefined-environment-variables
+    CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG
+    CI_APPLICATION_TAG: $CI_COMMIT_SHA
+  allow_failure: true
+  services:
+    - docker:stable-dind
+  script:
+    - docker run -d --name db arminc/clair-db:latest
+    - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:v2.0.6
+    - apk add -U wget ca-certificates
+    - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG}
+    - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64
+    - mv clair-scanner_linux_amd64 clair-scanner
+    - chmod +x clair-scanner
+    - touch clair-whitelist.yml
+    - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done
+    - retries=0
+    - echo "Waiting for clair daemon to start"
+    - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done
+    - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true
+  artifacts:
+    paths: [gl-container-scanning-report.json]
+```
+
+Alternatively, the job name could be `sast:container`
+and the artifact name could be `gl-sast-container-report.json`.
+These names have been deprecated with GitLab 11.0
+and may be removed in the next major release, GitLab 12.0.
+
+## Security Dashboard
+
+The Security Dashboard is a good place to get an overview of all the security
+vulnerabilities in your groups and projects. 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).

doc/user/application_security/dast/index.md

+# Dynamic Application Security Testing (DAST) **[ULTIMATE]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4348)
+in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4.
+
+Running [static checks](../sast/index.md) on your code is the first step to detect
+vulnerabilities that can put the security of your code at risk. Yet, once
+deployed, your application is exposed to a new category of possible attacks,
+such as cross-site scripting or broken authentication flaws. This is where
+Dynamic Application Security Testing (DAST) comes into place.
+
+## Overview
+
+If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web application(s)
+for known vulnerabilities using Dynamic Application Security Testing (DAST).
+
+You can take advantage of DAST by either [including the CI job](#configuring-dast) in
+your existing `.gitlab-ci.yml` file or by implicitly using
+[Auto DAST](../../../topics/autodevops/index.md#auto-dast-ultimate)
+that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
+
+GitLab checks the DAST report, compares the found vulnerabilities between the source and target
+branches, and shows the information right on the merge request.
+
+![DAST Widget](img/dast_all.png)
+
+By clicking on one of the detected linked vulnerabilities, you will be able to
+see the details and the URL(s) affected.
+
+![DAST Widget Clicked](img/dast_single.png)
+
+[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_Application_Security_Testing)
+is using the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy)
+to perform an analysis on your running web application.
+
+By default, DAST executes [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan) and will perform passive scanning only. It will not actively attack your application.
+
+However, DAST can be [configured](#full-scan)
+to also perform a so-called "active scan". That is, attack your application and produce a more extensive security report.
+It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md).
+
+## Use cases
+
+It helps you automatically find security vulnerabilities in your running web
+applications while you are developing and testing your applications.
+
+## Requirements
+
+To run a DAST job, you need GitLab Runner with the
+[`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or
+[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners)
+executor running in privileged mode. If you're using the shared Runners on GitLab.com,
+this is enabled by default.
+
+## Configuring DAST
+
+To enable DAST in your project, define a job in your `.gitlab-ci.yml` file that generates the
+[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate).
+
+This can be done in two ways:
+
+- For GitLab 11.9 and later, including the provided DAST `.gitlab-ci.yml` template (recommended).
+- Manually specifying the job definition. Not recommended unless using GitLab
+  11.8 and earlier.
+
+### Including the provided template
+
+NOTE: **Note:**
+The CI/CD DAST template is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later).
+
+A CI/CD [DAST template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml)
+with the default DAST job definition is provided as a part of your GitLab
+installation which you can [include](../../../ci/yaml/README.md#includetemplate)
+in your `.gitlab-ci.yml` file.
+
+To enable DAST using the provided template, add the following to your `.gitlab-ci.yml`
+file:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+variables:
+  DAST_WEBSITE: https://example.com
+```
+
+The included template will create a `dast` job in your CI/CD pipeline and scan
+your project's source code for possible vulnerabilities.
+
+The report will be saved as a
+[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate)
+that you can later download and analyze. Due to implementation limitations we
+always take the latest DAST artifact available. Behind the scenes, the
+[GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast)
+is used to run the tests on the specified URL and scan it for possible vulnerabilities.
+
+There are two ways to define the URL to be scanned by DAST:
+
+- Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables).
+- Add it in an `environment_url.txt` file at the root of your project.
+
+#### Authenticated scan
+
+It's also possible to authenticate the user before performing the DAST checks:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+variables:
+  DAST_WEBSITE: https://example.com
+  DAST_AUTH_URL: https://example.com/sign-in
+  DAST_USERNAME: john.doe@example.com
+  DAST_PASSWORD: john-doe-password
+  DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form
+  DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form
+  DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between
+```
+
+The report will be saved as a
+[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate)
+that you can later download and analyze.
+Due to implementation limitations, we always take the latest DAST artifact available.
+
+#### Full scan
+
+DAST can be configured to perform [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan), which
+includes both passive and active scanning against the same target website:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+variables:
+  DAST_FULL_SCAN_ENABLED: "true"
+```
+
+#### Customizing the DAST settings
+
+The SAST settings can be changed through environment variables by using the
+[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
+These variables are documented in the [DAST README](https://gitlab.com/gitlab-org/security-products/dast#settings).
+
+For example:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+variables:
+  DAST_WEBSITE: https://example.com
+  DAST_TARGET_AVAILABILITY_TIMEOUT: 120
+```
+
+Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline
+configuration, the last mention of the variable will take precedence.
+
+#### Overriding the DAST template
+
+If you want to override the job definition (for example, change properties like
+`variables` or `dependencies`), you need to declare a `dast` job after the
+template inclusion and specify any additional keys under it. For example:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+dast:
+  stage: dast # IMPORTANT: don't forget to add this
+  variables:
+    DAST_WEBSITE: https://example.com
+    CI_DEBUG_TRACE: "true"
+```
+
+As the DAST job belongs to a separate `dast` stage that runs after all
+[default stages](../../../ci/yaml/README.md#stages),
+don't forget to add `stage: dast` when you override the template job definition.
+
+### Manual job definition for GitLab 11.5 and later
+
+For GitLab 11.5 and GitLab Runner 11.5 and later, the following `dast`
+job can be added:
+
+```yaml
+dast:
+  image: registry.gitlab.com/gitlab-org/security-products/zaproxy
+  variables:
+    website: "https://example.com"
+  allow_failure: true
+  script:
+    - mkdir /zap/wrk/
+    - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true
+    - cp /zap/wrk/gl-dast-report.json .
+  artifacts:
+    reports:
+      dast: gl-dast-report.json
+```
+
+Where the `website` variable holds the URL to run the tests against.
+
+For an authenticated scan, use the following definition:
+
+```yaml
+dast:
+  image: registry.gitlab.com/gitlab-org/security-products/zaproxy
+  variables:
+    website: "https://example.com"
+    login_url: "https://example.com/sign-in"
+    username: "john.doe@example.com"
+    password: "john-doe-password"
+  allow_failure: true
+  script:
+    - mkdir /zap/wrk/
+    - /zap/zap-baseline.py -J gl-dast-report.json -t $website
+        --auth-url $login_url
+        --auth-username $username
+        --auth-password $password || true
+    - cp /zap/wrk/gl-dast-report.json .
+  artifacts:
+    reports:
+      dast: gl-dast-report.json
+```
+
+See the [zaproxy documentation](https://gitlab.com/gitlab-org/security-products/zaproxy)
+to learn more about the authentication settings.
+
+### Manual job definition for GitLab 11.4 and earlier (deprecated)
+
+CAUTION: **Caution:**
+Before GitLab 11.5, DAST job and artifact had to be named specifically
+to automatically extract report data and show it in the merge request widget.
+While these old job definitions are still maintained they have been deprecated
+and may be removed in next major release, GitLab 12.0. You are strongly advised
+to update your current `.gitlab-ci.yml` configuration to reflect that change.
+
+For GitLab 11.4 and earlier, the job should look like:
+
+```yaml
+dast:
+  image: registry.gitlab.com/gitlab-org/security-products/zaproxy
+  variables:
+    website: "https://example.com"
+  allow_failure: true
+  script:
+    - mkdir /zap/wrk/
+    - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true
+    - cp /zap/wrk/gl-dast-report.json .
+  artifacts:
+    paths: [gl-dast-report.json]
+```
+
+## Security Dashboard
+
+The Security Dashboard is a good place to get an overview of all the security
+vulnerabilities in your groups and projects. 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).

doc/user/application_security/dependency_scanning/index.md

+# Dependency Scanning **[ULTIMATE]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105)
+in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7.
+
+## Overview
+
+If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your dependencies for known
+vulnerabilities using Dependency Scanning.
+
+You can take advantage of Dependency Scanning by either [including the CI job](#including-the-provided-template)
+in your existing `.gitlab-ci.yml` file or by implicitly using
+[Auto Dependency Scanning](../../../topics/autodevops/index.md#auto-dependency-scanning-ultimate)
+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
+merge request.
+
+![Dependency Scanning Widget](img/dependency_scanning.png)
+
+The results are sorted by the priority of the vulnerability:
+
+1. High
+1. Medium
+1. Low
+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
+[`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or
+[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners)
+executor running in privileged mode. If you're using the shared Runners on GitLab.com,
+this is enabled by default.
+
+## Supported languages and package 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/general), [Retire.js](https://retirejs.github.io/retire.js)         |
+| Python ([pip](https://pip.pypa.io/en/stable/)) (only `requirements.txt` supported)  | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general)                                                            |
+| Ruby ([gem](https://rubygems.org/))                                         | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [bundler-audit](https://github.com/rubysec/bundler-audit) |
+| Java ([Maven](https://maven.apache.org/))                                   | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general)                                                            |
+| PHP ([Composer](https://getcomposer.org/))                                  | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general)                                                            |
+
+Some scanners require to send a list of project dependencies to GitLab's central
+servers to check for vulnerabilities. To learn more about this or to disable it,
+refer to the [GitLab Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).
+
+## Configuring Dependency Scanning
+
+To enable Dependency Scanning in your project, define a job in your `.gitlab-ci.yml`
+file that generates the
+[Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate).
+
+This can be done in two ways:
+
+- For GitLab 11.9 and later, including the provided Dependency Scanning
+  `.gitlab-ci.yml` template (recommended).
+- Manually specifying the job definition. Not recommended unless using GitLab
+  11.8 and earlier.
+
+### Including the provided template
+
+NOTE: **Note:**
+The CI/CD Dependency Scanning template is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later).
+
+A CI/CD [Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml)
+with the default Dependency Scanning job definition is provided as a part of your GitLab
+installation which you can [include](../../../ci/yaml/README.md#includetemplate)
+in your `.gitlab-ci.yml` file.
+
+To enable Dependency Scanning using the provided template, add the following to
+your `.gitlab-ci.yml` file:
+
+```yaml
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
+```
+
+The included template will create a `dependency_scanning` job in your CI/CD
+pipeline and scan your project's source code for possible vulnerabilities.
+
+The report will be saved as a
+[Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate)
+that you can later download and analyze. Due to implementation limitations, we
+always take the latest Dependency Scanning artifact available.
+
+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 tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks).
+
+#### Customizing the Dependency Scanning settings
+
+The Dependency Scanning settings can be changed through environment variables by using the
+[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
+These variables are documented in the
+[Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
+
+For example:
+
+```yaml
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
+
+variables:
+  DEP_SCAN_DISABLE_REMOTE_CHECKS: true
+```
+
+Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline
+configuration, the last mention of the variable will take precedence.
+
+#### Overriding the Dependency Scanning template
+
+If you want to override the job definition (for example, change properties like
+`variables` or `dependencies`), you need to declare a `dependency_scanning` job
+after the template inclusion and specify any additional keys under it. For example:
+
+```yaml
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
+
+dependency_scanning:
+  variables:
+    CI_DEBUG_TRACE: "true"
+```
+
+### Manual job definition for GitLab 11.5 and later
+
+For GitLab 11.5 and GitLab Runner 11.5 and later, the following `dependency_scanning`
+job can be added:
+
+```yaml
+dependency_scanning:
+  image: docker:stable
+  variables:
+    DOCKER_DRIVER: overlay2
+  allow_failure: true
+  services:
+    - docker:stable-dind
+  script:
+    - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
+    - |
+      docker run \
+      --env DS_ANALYZER_IMAGES \
+      --env DS_ANALYZER_IMAGE_PREFIX \
+      --env DS_ANALYZER_IMAGE_TAG \
+      --env DS_DEFAULT_ANALYZERS \
+      --env DEP_SCAN_DISABLE_REMOTE_CHECKS \
+      --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \
+      --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \
+      --env DS_RUN_ANALYZER_TIMEOUT \
+      --volume "$PWD:/code" \
+      --volume /var/run/docker.sock:/var/run/docker.sock \
+      "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code
+  dependencies: []
+  artifacts:
+    reports:
+      dependency_scanning: gl-dependency-scanning-report.json
+```
+
+You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings)
+via `docker run --env` to customize your job execution.
+
+### Manual job definition for GitLab 11.4 and earlier (deprecated)
+
+CAUTION: **Caution:**
+Before GitLab 11.5, the Dependency Scanning job and artifact had to be named specifically
+to automatically extract the report data and show it in the merge request widget.
+While these old job definitions are still maintained, they have been deprecated
+and may be removed in the next major release, GitLab 12.0. You are strongly advised
+to update your current `.gitlab-ci.yml` configuration to reflect that change.
+
+For GitLab 11.4 and earlier, the job should look like:
+
+```yaml
+dependency_scanning:
+  image: docker:stable
+  variables:
+    DOCKER_DRIVER: overlay2
+  allow_failure: true
+  services:
+    - docker:stable-dind
+  script:
+    - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
+    - |
+      docker run \
+      --env DS_ANALYZER_IMAGES \
+      --env DS_ANALYZER_IMAGE_PREFIX \
+      --env DS_ANALYZER_IMAGE_TAG \
+      --env DS_DEFAULT_ANALYZERS \
+      --env DEP_SCAN_DISABLE_REMOTE_CHECKS \
+      --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \
+      --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \
+      --env DS_RUN_ANALYZER_TIMEOUT \
+      --volume "$PWD:/code" \
+      --volume /var/run/docker.sock:/var/run/docker.sock \
+      "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code
+  artifacts:
+    paths: [gl-dependency-scanning-report.json]
+```
+
+## Security Dashboard
+
+The Security Dashboard is a good place to get an overview of all the security
+vulnerabilities in your groups and projects. 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).

doc/user/application_security/index.md

+# GitLab Secure **[ULTIMATE]**
+
+Check your application for security vulnerabilities that may lead to unauthorized access,
+data leaks, and denial of services. 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.
+
+## Security scanning tools
+
+GitLab can scan and report any vulnerabilities found in your project.
+
+| Secure scanning tools                                                        | Description                                                            |
+|:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------|
+| [Container Scanning](container_scanning/index.md) **[ULTIMATE]**             | Scan Docker containers for known vulnerabilities.                      |
+| [Dependency Scanning](dependency_scanning/index.md) **[ULTIMATE]**           | Analyze your dependencies for known vulnerabilities.                   |
+| [Dynamic Application Security Testing (DAST)](dast/index.md) **[ULTIMATE]**  | Analyze running web applications for known vulnerabilities.            |
+| [License Management](license_management/index.md) **[ULTIMATE]**             | Search your project's dependencies for their licenses.                 |
+| [Security Dashboard](security_dashboard/index.md) **[ULTIMATE]**             | View vulnerabilities in all your projects and groups.                  |
+| [Static Application Security Testing (SAST)](sast/index.md) **[ULTIMATE]**   | Analyze source code for known vulnerabilities.                         |
+
+## Interacting with the vulnerabilities
+
+> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.8.
+
+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 <s>strikethrough</s> 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.
+- [Solution](#solutions-for-vulnerabilities): For some vulnerabilities
+  ([Dependency Scanning](dependency_scanning/index.md) and [Container Scanning](container_scanning/index.md))
+  a solution is provided for how to fix the vulnerability.
+
+![Interacting with security reports](img/interactive_reports.png)
+
+### Dismissing a vulnerability
+
+You can dismiss vulnerabilities by clicking the **Dismiss vulnerability** button.
+This will dismiss the vulnerability and re-render it to reflect its dismissed state.
+If you wish to undo this dismissal, you can click the **Undo dismiss** button.
+
+### 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.
+
+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.
+
+Upon returning to the group security dashboard, you'll see that
+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
+
+> 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.
+
+Some vulnerabilities can be fixed by applying the solution that GitLab
+automatically generates.
+
+#### Manually applying the suggested patch
+
+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. Download and review the patch file `remediation.patch`.
+2. Ensure your local project has the same commit checked out that was used to generate the patch.
+3. Run `git apply remediation.patch`.
+4. Verify and commit the changes to your branch.
+
+![Apply patch for dependency scanning](img/vulnerability_solution.png)
+
+#### 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.
+
+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.
+
+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.
+
+![Create merge request from vulnerability](img/create_issue_with_list_hover.png)

doc/user/application_security/security_dashboard/index.md

+# GitLab Security Dashboard **[ULTIMATE]**
+
+The Security Dashboard is a good place to get an overview of all the security
+vulnerabilities in your groups and projects.
+
+You can also drill down into a vulnerability and get extra information, see which
+project it comes from, the file it's in, and various metadata to help you analyze
+the risk. You can also action these vulnerabilities by creating an issue for them,
+or by dismissing them.
+
+To benefit from the Security Dashboard you must first configure one of the
+[security reports](../index.md).
+
+## Supported reports
+
+The Security Dashboard supports the following reports:
+
+- [Container Scanning](../container_scanning/index.md)
+- [DAST](../dast/index.md)
+- [Dependency Scanning](../dependency_scanning/index.md)
+- [SAST](../sast/index.md)
+
+## Requirements
+
+To use the project or group security dashboard:
+
+1. At least one project inside a group must be configured with at least one of
+   the [supported reports](#supported-reports).
+2. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports).
+3. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used.
+   If you're using the shared Runners on GitLab.com, this is already the case.
+
+## Project Security Dashboard
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.1.
+
+At the project level, the Security Dashboard displays the latest security reports
+for your project. Use it to find and fix vulnerabilities affecting the
+[default branch](../../project/repository/branches/index.md#default-branch).
+
+![Project Security Dashboard](img/project_security_dashboard.png)
+
+## Group Security Dashboard
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6709) in
+  [GitLab Ultimate](https://about.gitlab.com/pricing) 11.5.
+
+The group Security Dashboard gives an overview of the vulnerabilities of all the
+projects in a group and its subgroups.
+
+First, navigate to the Security Dashboard found under your group's
+**Overview > Security Dashboard**.
+
+Once you're on the dashboard, at the top you should see a series of filters for:
+
+- Severity
+- Report type
+- Project
+
+![dashboard with action buttons and metrics](img/dashboard.png)
+
+Selecting one or more filters will filter the results in this page.
+The first section is an overview of all the vulnerabilities, grouped by severity.
+Underneath this overview is a timeline chart that shows how many open
+vulnerabilities your projects had at various points in time. You can filter among 30, 60, and
+90 days, with the default being 90. Hover over the chart to get more details about
+the open vulnerabilities at a specific time.
+
+Finally, there is a list of all the vulnerabilities in the group, sorted by severity.
+In that list, you can see the severity of the vulnerability, its name, its
+confidence (likelihood of the vulnerability to be a positive one), and the project
+it's from.
+
+If you hover over a row, there will appear some actions you can take:
+
+- "More info"
+- "Create issue"
+- "Dismiss vulnerability"
+
+Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities).
+
+## Keeping the dashboards up to date
+
+The Security Dashboard displays information from the results of the most recent
+security scan on the [default branch](../../project/repository/branches/index.md#default-branch),
+which means that security scans are performed every time the branch is updated.
+
+If the default branch is updated infrequently, scans are run infrequently and the
+information on the Security Dashboard can become outdated as new vulnerabilities
+are discovered.
+
+To ensure the information on the Security Dashboard is regularly updated,
+[configure a scheduled pipeline](../../project/pipelines/schedules.md) to run a
+daily security scan. This will update the information displayed on the Security
+Dashboard regardless of how often the default branch is updated.
+
+That way, reports are created even if no code change happens.
+
+## Security scans using Auto DevOps
+
+When using [Auto DevOps](../../../topics/autodevops/index.md), use
+[special environment variables](../../../topics/autodevops/index.md#environment-variables)
+to configure daily security scans.