Merge branch '8661-update-dependency-scanning-ci-docs' into 'master'

Update Security products docs with vendored templates info

See merge request gitlab-org/gitlab-ee!9875

doc/ci/examples/container_scanning.md

-# Container Scanning with GitLab CI/CD
-
-CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-It also requires the GitLab Runner 11.5 or later.
-For earlier versions, use the [previous job definitions](#previous-job-definitions).
+# Container Scanning with GitLab CI/CD **[ULTIMATE]**
 
 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.
 
-First, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+These examples show how to run Container Scanning on your Docker image by using GitLab CI/CD.
+
+CAUTION: **Caution:**
+Starting with GitLab 11.5, Container Scanning feature is licensed under the name `container_scanning`.
+While the old name `sast_container` is still maintained, it has been deprecated with GitLab 11.5 and
+may be removed in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml`
+configuration to reflect that change if you are using the `$GITLAB_FEATURES` environment variable.
+
+## Prerequisites
+
+To run a Container Scanning job, you need:
+
+- a GitLab Runner with
+[docker-in-docker executor](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
+- to [build and push](../../ci/docker/using_docker_build.md#container-registry-examples) your Docker image
+using the [Container Registry](https://docs.gitlab.com/ee/user/project/container_registry.html) running within your GitLab installation.
+
+## Configuring with templates
+
+Since GitLab 11.9, a CI/CD template with the default Container Scanning job definition is provided as a part of your GitLab installation.
+This section describes how to use it and customize its execution.
+
+### Using job definition template
+
+CAUTION: **Caution:**
+The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition).
+
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for Container Scanning:
+
+```yaml
+include:
+  template: Container-Scanning.gitlab-ci.yml
+```
+
+If you want to whitelist some specific vulnerabilities, you can do so by defining
+them in a [YAML file](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file),
+in our case its named `clair-whitelist.yml`.
+
+### Scanning results
+
+The above example will create a `container_scanning` job in your CI/CD pipeline, pull
+the image from the [Container Registry](../../user/project/container_registry.md)
+(whose name is defined from the two `CI_APPLICATION_` variables) and scan it
+for possible vulnerabilities. The report will be saved as a
+[Container Scanning report artifact](../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.
+
+TIP: **Tip:**
+For [GitLab Ultimate][ee] users, this information will
+be automatically extracted and shown right in the merge request widget.
+[Learn more on Container Scanning in merge requests](../../user/project/merge_requests/container_scanning.html).
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
-generates the expected report:
+## Manual job definition
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
+[the job definition template](#using-job-definition-template) since 11.9)_.
+It also requires the GitLab Runner 11.5 or later.
+For earlier versions, use the [previous job definitions](#previous-job-definitions).
+
+If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
 
 ```yaml
 container_scanning:
@@ -47,29 +100,6 @@ container_scanning:
       container_scanning: gl-container-scanning-report.json
 ```
 
-The above example will create a `container_scanning` job in your CI/CD pipeline, pull
-the image from the [Container Registry](../../user/project/container_registry.md)
-(whose name is defined from the two `CI_APPLICATION_` variables) and scan it
-for possible vulnerabilities. The report will be saved as a
-[Container Scanning report artifact](../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.
-
-If you want to whitelist some specific vulnerabilities, you can do so by defining
-them in a [YAML file](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file),
-in our case its named `clair-whitelist.yml`.
-
-TIP: **Tip:**
-For [GitLab Ultimate][ee] users, this information will
-be automatically extracted and shown right in the merge request widget.
-[Learn more on Container Scanning in merge requests](../../user/project/merge_requests/container_scanning.html).
-
-CAUTION: **Caution:**
-Starting with GitLab 11.5, Container Scanning feature is licensed under the name `container_scanning`.
-While the old name `sast_container` is still maintained, it has been deprecated with GitLab 11.5 and
-may be removed in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml`
-configuration to reflect that change if you are using the `$GITLAB_FEATURES` environment variable.
-
 ## Previous job definitions
 
 CAUTION: **Caution:**
@@ -111,7 +141,7 @@ container_scanning:
     paths: [gl-container-scanning-report.json]
 ```
 
-Alternatively the job name could be `sast:container`
+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 next major release, GitLab 12.0.

doc/ci/examples/dast.md

 # Dynamic Application Security Testing with GitLab CI/CD
 
-CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-It also requires the GitLab Runner 11.5 or later.
-For earlier versions, use the [previous job definitions](#previous-job-definitions).
-
-[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_program_analysis)
+[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.
 Since it is based on [ZAP Baseline](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan)
@@ -14,13 +9,114 @@ it will not actively attack your application.
 
 It can be very useful combined with [Review Apps](../review_apps/index.md).
 
-## Example
+These examples show how to run DAST on your running web application by using GitLab CI/CD.
+
+## Prerequisites
 
-First, you need GitLab Runner with
+To run a DAST job, you need GitLab Runner with
 [docker executor](https://docs.gitlab.com/runner/executors/docker.html).
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
-generates the expected report:
+## Configuring with templates
+
+Since GitLab 11.9, a CI/CD template with the default DAST job definition is provided as a part of your GitLab installation.
+This section describes how to use it and customize its execution.
+
+### Using job definition template
+
+CAUTION: **Caution:**
+The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition).
+
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for DAST:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+```
+
+The above example will create a `dast` job in your CI/CD pipeline which will run
+the tests on the URL defined in the `DAST_WEBSITE` variable (change it to use your
+own) and scan it for possible vulnerabilities.
+
+It's also possible to authenticate the user before performing DAST checks:
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+  
+variables:
+  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
+```
+
+### Scanning results
+
+The report will be saved as a
+[DAST report artifact](../yaml/README.md#artifactsreportsdast-ultimate)
+that you can later download and analyze.
+Due to implementation limitations we always take the latest DAST artifact available.
+
+TIP: **Tip:**
+For [GitLab Ultimate][ee] users, this information will
+be automatically extracted and shown right in the merge request widget.
+[Learn more on DAST in merge requests](../../user/project/merge_requests/dast.md).
+
+### Customizing the template
+
+You can customize DAST job execution in various ways of different granularity.
+
+#### Scanning tool settings
+
+DAST tool settings can be changed through environment variables. These variables are documented in the:
+                                                                             
+- Job definition [template](#using-job-definition-template).
+- DAST [README](https://gitlab.com/gitlab-org/security-products/dast#settings).
+
+The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
+parameter in the project's pipeline configuration file (`.gitlab-ci.yml`):
+
+```yaml
+include:
+  template: DAST.gitlab-ci.yml
+
+variables:
+  DAST_TARGET_AVAILABILITY_TIMEOUT: 120
+```
+
+Because template is evaluated [before](../yaml/README.md#include) the pipeline configuration,
+the last mention of the variable will take precedence.
+
+#### Overriding job definition
+
+If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
+its definition 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:
+    CI_DEBUG_TRACE: "true"
+``` 
+
+CAUTION: **Caution:**
+As DAST job belongs to a separate `"dast"` stage that runs after all [default stages](../yaml/README.md#stages),
+don't forget to add `stage: dast` entry when you override the template job definition. 
+
+## Manual job definition
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
+[the job definition template](#using-job-definition-template) since 11.9)_.
+It also requires the GitLab Runner 11.5 or later.
+For earlier versions, use the [previous job definitions](#previous-job-definitions).
+
+If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
 
 ```yaml
 dast:
@@ -37,14 +133,9 @@ dast:
       dast: gl-dast-report.json
 ```
 
-The above example will create a `dast` job in your CI/CD pipeline which will run
-the tests on the URL defined in the `website` variable (change it to use your
-own) and scan it for possible vulnerabilities. The report will be saved as a
-[DAST report artifact](../yaml/README.md#artifactsreportsdast-ultimate)
-that you can later download and analyze.
-Due to implementation limitations we always take the latest DAST artifact available.
+where the `website` variable is supposed to hold the URL to run the tests against.
 
-It's also possible to authenticate the user before performing DAST checks:
+For an authenticated scan, use the following definition:
 
 ```yaml
 dast:
@@ -66,14 +157,10 @@ dast:
     reports:
       dast: gl-dast-report.json
 ```
+
 See [zaproxy documentation](https://gitlab.com/gitlab-org/security-products/zaproxy)
 to learn more about authentication settings.
 
-TIP: **Tip:**
-For [GitLab Ultimate][ee] users, this information will
-be automatically extracted and shown right in the merge request widget.
-[Learn more on DAST in merge requests](../../user/project/merge_requests/dast.md).
-
 ## Previous job definitions
 
 CAUTION: **Caution:**
@@ -97,6 +184,6 @@ dast:
     - cp /zap/wrk/gl-dast-report.json .
   artifacts:
     paths: [gl-dast-report.json]
-```
+``` 
 
 [ee]: https://about.gitlab.com/pricing/

doc/ci/examples/dependency_scanning.md

 # Dependency Scanning with GitLab CI/CD **[ULTIMATE]**
 
-CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-It also requires the GitLab Runner 11.5 or later.
-For earlier versions, use the [previous job definitions](#previous-job-definitions).
+These examples show how to run Dependency Scanning on your project's dependencies by using GitLab CI/CD.
+
+## Prerequisites
 
-This example shows how to run Dependency Scanning on your
-project's dependencies by using GitLab CI/CD.
+To run a Dependency Scanning job, you need GitLab Runner with
+[docker-in-docker executor](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
 
+## Configuring with templates
 
-First, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+Since GitLab 11.9, a CI/CD template with the default Dependency Scanning job definition is provided as a part of your GitLab installation.
+This section describes how to use it and customize its execution.
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
-generates the expected report:
+### Using job definition template
+
+CAUTION: **Caution:**
+The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition).
+
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for Dependency Scanning:
 
 ```yaml
-dependency_scanning:
-  image: docker:stable
-  variables:
-    DOCKER_DRIVER: overlay2
-  allow_failure: true
-  services:
-    - docker:stable-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:
-    reports:
-      dependency_scanning: gl-dependency-scanning-report.json
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
 ```
 
+### Scanning results
+
 The above example will create a `dependency_scanning` job in your CI/CD pipeline
 and scan your dependencies for possible vulnerabilities. The report will be saved as a
 [Dependency Scanning report artifact](../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate)
@@ -54,16 +46,94 @@ is used to detect the languages/package managers and in turn runs the matching s
 
 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).
+disable it, check the [GitLab Dependency Scanning documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks)
+and the [customization guide](#job-execution-customization).
 
 TIP: **Tip:**
 For [GitLab Ultimate][ee] users, this information will
 be automatically extracted and shown right in the merge request widget.
 [Learn more on Dependency Scanning in merge requests](../../user/project/merge_requests/dependency_scanning.md).
 
-## Supported languages and package managers
+### Customizing the template
 
-See [the full list of supported languages and package managers](../../user/project/merge_requests/dependency_scanning.md#supported-languages-and-dependency-managers).
+You can customize Dependency Scanning job execution in various ways of different granularity.
+
+#### Scanning tool settings
+
+Dependency Scanning tool settings can be changed through environment variables. These variables are documented in the:
+                                                                             
+- Job definition [template](#using-job-definition-template).
+- Dependency Scanning [README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
+
+The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
+parameter in the project's pipeline configuration file (`.gitlab-ci.yml`):
+
+```yaml
+include:
+  template: Dependency-Scanning.gitlab-ci.yml
+
+variables:
+  DEP_SCAN_DISABLE_REMOTE_CHECKS: true
+```
+
+Because template is evaluated [before](../yaml/README.md#include) the pipeline configuration,
+the last mention of the variable will take precedence.
+
+#### Overriding job definition
+
+If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
+its definition 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
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
+[the job definition template](#using-job-definition-template) since 11.9)_.
+It also requires the GitLab Runner 11.5 or later.
+For earlier versions, use the [previous job definitions](#previous-job-definitions).
+
+If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
+
+```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.
 
 ## Previous job definitions
 
@@ -85,14 +155,26 @@ dependency_scanning:
   services:
     - docker:stable-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
+    - 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]
 ```
 
+## 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-dependency-managers).
+
 [ee]: https://about.gitlab.com/pricing/

doc/ci/examples/license_management.md

 # Dependencies license management with GitLab CI/CD **[ULTIMATE]**
 
-CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-It also requires the GitLab Runner 11.5 or later.
-For earlier versions, use the [previous job definitions](#previous-job-definitions).
+These examples show how to run License Management scanning on your project's dependencies by using GitLab CI/CD.
+
+## Prerequisites
+
+To run a License Management scanning job, you need GitLab Runner with
+[docker executor](https://docs.gitlab.com/runner/executors/docker.html).
 
-This example shows how to run the License Management tool on your
-project's dependencies by using GitLab CI/CD.
+## Configuring with templates
 
-First, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+Since GitLab 11.9, a CI/CD template with the default License Management scanning job definition is provided as a part of your GitLab installation.
+This section describes how to use it and customize its execution.
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
-generates the expected report:
+### Using job definition template
+
+CAUTION: **Caution:**
+The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition).
+
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for License Management:
 
 ```yaml
-license_management:
-  image:
-    name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable"
-    entrypoint: [""]
-  stage: test
-  allow_failure: true
-  script:
-    - /run.sh analyze .
-  artifacts:
-    reports:
-      license_management: gl-license-management-report.json
+include:
+  template: License-Management.gitlab-ci.yml
 ```
 
+### Scanning results
+
 The above example will create a `license_management` job in your CI/CD pipeline
 and scan your dependencies to find their licenses. The report will be saved as a
 [License Management report artifact](../../ci/yaml/README.md#artifactsreportslicense_management-ultimate)
 that you can later download and analyze.
 Due to implementation limitations we always take the latest License Management artifact available.
 
-## Install custom project dependencies
+TIP: **Tip:**
+For [GitLab Ultimate][ee] users, this information will
+be automatically extracted and shown right in the merge request widget.
+[Learn more on License Management in merge requests](../../user/project/merge_requests/license_management.md).
+
+### Customizing the template
+
+#### Install custom project dependencies
 
 > Introduced in GitLab Ultimate 11.4.
 
@@ -50,14 +56,45 @@ of your application (ex: for a project with a `Gemfile`, the setup step will be
 
 Example:
 
+```yaml
+include:
+  template: License-Management.gitlab-ci.yml
+  
+variables:
+  LICENSE_MANAGEMENT_SETUP_CMD: ./my-custom-install-script.sh
+```
+
+In this example, `my-custom-install-script.sh` is a shell script at the root of the project.
+
+#### Overriding job definition
+
+If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
+its definition after the template inclusion and specify any additional keys under it. For example:
+
+```yaml
+include:
+  template: License-Management.gitlab-ci.yml
+
+license_management:
+  stage: my-custom-stage
+```
+
+## Manual job definition
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
+[the job definition template](#using-job-definition-template) since 11.9)_.
+It also requires the GitLab Runner 11.5 or later.
+For earlier versions, use the [previous job definitions](#previous-job-definitions).
+
+If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
+
 ```yaml
 license_management:
   image:
     name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable"
     entrypoint: [""]
   stage: test
-  variables:
-    SETUP_CMD: ./my-custom-install-script.sh
   allow_failure: true
   script:
     - /run.sh analyze .
@@ -66,12 +103,23 @@ license_management:
       license_management: gl-license-management-report.json
 ```
 
-In this example, `my-custom-install-script.sh` is a shell script at the root of the project.
+Install custom project dependencies via `SETUP_CMD` variable:
 
-TIP: **Tip:**
-For [GitLab Ultimate][ee] users, this information will
-be automatically extracted and shown right in the merge request widget.
-[Learn more on License Management in merge requests](../../user/project/merge_requests/license_management.md).
+```yaml
+license_management:
+  image:
+    name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable"
+    entrypoint: [""]
+  stage: test
+  variables:
+    SETUP_CMD: ./my-custom-install-script.sh
+  allow_failure: true
+  script:
+    - /run.sh analyze .
+  artifacts:
+    reports:
+      license_management: gl-license-management-report.json
+```
 
 ## Previous job definitions
 

doc/ci/examples/sast.md

 # Static Application Security Testing with GitLab CI/CD **[ULTIMATE]**
 
-CAUTION: **Caution:**
-The job definition shown below is supported on GitLab 11.5 and later versions.
-It also requires the GitLab Runner 11.5 or later.
-For earlier versions, use the [previous job definitions](#previous-job-definitions).
-
-This example shows how to run
-[Static Application Security Testing (SAST)](https://en.wikipedia.org/wiki/Static_program_analysis)
+These examples show how to run [Static Application Security Testing (SAST)](https://en.wikipedia.org/wiki/Static_program_analysis)
 on your project's source code by using GitLab CI/CD.
 
-First, you need GitLab Runner with
-[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor).
+## Prerequisites
+
+To run a SAST job, you need GitLab Runner with
+[docker-in-docker executor](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
+
+## Configuring with templates
+
+Since GitLab 11.9, a CI/CD template with the default SAST job definition is provided as a part of your GitLab installation.
+This section describes how to use it and customize its execution.
+
+### Using job definition template
 
-Once you set up the Runner, add a new job to `.gitlab-ci.yml` that
-generates the expected report:
+CAUTION: **Caution:**
+The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
+For earlier versions, use the [manual job definition](#manual-job-definition).
+
+Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for SAST:
 
 ```yaml
-sast:
-  image: docker:stable
-  variables:
-    DOCKER_DRIVER: overlay2
-  allow_failure: true
-  services:
-    - docker:stable-dind
-  script:
-    - 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:
-    reports:
-      sast: gl-sast-report.json
+include:
+  template: SAST.gitlab-ci.yml
 ```
 
+### Scanning results
+
 The above example will create a `sast` job in your CI/CD pipeline
-and scan your dependencies for possible vulnerabilities. The report will be saved as a
+and scan your project's source code for possible vulnerabilities. The report will be saved as a
 [SAST report artifact](../../ci/yaml/README.md#artifactsreportssast-ultimate)
 that you can later download and analyze.
 Due to implementation limitations we always take the latest SAST artifact available.
@@ -58,9 +51,89 @@ For [GitLab Ultimate][ee] users, this information will
 be automatically extracted and shown right in the merge request widget.
 [Learn more on SAST in merge requests](../../user/project/merge_requests/sast.md).
 
-## Supported languages and frameworks
+### Customizing the template
+
+You can customize SAST job execution in various ways of different granularity.
+
+#### Scanning tool settings
+
+SAST tool settings can be changed through environment variables. These variables are documented in the:
+                                                                             
+- Job definition [template](#using-job-definition-template).
+- SAST [README](https://gitlab.com/gitlab-org/security-products/sast#settings).
+
+The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
+parameter in the project's pipeline configuration file (`.gitlab-ci.yml`):
+
+```yaml
+include:
+  template: SAST.gitlab-ci.yml
+
+variables:
+  SAST_GOSEC_LEVEL: 2
+```
+
+Because template is evaluated [before](../yaml/README.md#include) the pipeline configuration,
+the last mention of the variable will take precedence.
+
+#### Overriding job definition
+
+If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
+its definition after the template inclusion and specify any additional keys under it. For example:
+
+```yaml
+include:
+  template: SAST.gitlab-ci.yml
+
+sast:
+  variables:
+    CI_DEBUG_TRACE: "true"
+``` 
+
+## Manual job definition
+
+CAUTION: **Caution:**
+The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use 
+[the job definition template](#using-job-definition-template) since 11.9)_.
+It also requires the GitLab Runner 11.5 or later.
+For earlier versions, use the [previous job definitions](#previous-job-definitions).
+
+If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
+
+```yaml
+sast:
+  stage: test
+  image: docker:stable
+  variables:
+    DOCKER_DRIVER: overlay2
+  allow_failure: true
+  services:
+    - docker:stable-dind
+  script:
+    - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')}
+    - |
+      docker run \
+        --env SAST_ANALYZER_IMAGES \
+        --env SAST_ANALYZER_IMAGE_PREFIX \
+        --env SAST_ANALYZER_IMAGE_TAG \
+        --env SAST_DEFAULT_ANALYZERS \
+        --env SAST_BRAKEMAN_LEVEL \
+        --env SAST_GOSEC_LEVEL \
+        --env SAST_FLAWFINDER_LEVEL \
+        --env SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \
+        --env SAST_PULL_ANALYZER_IMAGE_TIMEOUT \
+        --env SAST_RUN_ANALYZER_TIMEOUT \
+        --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
+  dependencies: []
+  artifacts:
+    reports:
+      sast: gl-sast-report.json
+```
 
-See [the full list of supported languages and frameworks](../../user/project/merge_requests/sast.md#supported-languages-and-frameworks).
+You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/sast#settings)
+via `docker run --env` to customize your job execution.
 
 ## Previous job definitions
 
@@ -82,12 +155,12 @@ sast:
   services:
     - docker:stable-dind
   script:
-    - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
+    - export SAST_VERSION=${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
+        "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code
   artifacts:
     paths: [gl-sast-report.json]
 ```