Merge branch 'docs/sast-refactor' into 'master'

Refactor the SAST docs

Closes #4954

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

doc/ci/examples/README.md

@@ -43,7 +43,7 @@ There's also a collection of repositories with [example projects](https://gitlab
 
 ### Static Application Security Testing (SAST)
 
-- **(Ultimate)** [Scan your code for vulnerabilities](https://docs.gitlab.com/ee/ci/examples/sast.html)
+- **(Ultimate)** [Scan your code for vulnerabilities](sast.md)
 - [Scan your Docker images for vulnerabilities](sast_docker.md)
 
 ### Dynamic Application Security Testing (DAST)

doc/ci/examples/sast.md

@@ -9,10 +9,12 @@ This example shows how to run
 on your project's source code 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 `sast`:
+You can then add a new job to `.gitlab-ci.yml`, called `sast`:
 
 ```yaml
+before_script:
+  - *functions
+
 sast:
   image: docker:latest
   variables:
@@ -26,8 +28,8 @@ sast:
   artifacts:
     paths: [gl-sast-report.json]
 
-.auto_devops: &auto_devops |
-  # Auto DevOps variables and functions
+.functions: &functions |
+  # Variables and functions
 
   function setup_docker() {
     if ! docker info &>/dev/null; then
@@ -43,30 +45,23 @@ sast:
         # Extract "MAJOR.MINOR" from CI_SERVER_VERSION and generate "MAJOR-MINOR-stable"
         SAST_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')
 
-        docker run --volume "$PWD:/code" \
+        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
         ;;
       *)
-        echo "GitLab EE is required"
+        echo "GitLab Enterprise Edition is required"
         ;;
     esac
   }
-
-before_script:
-  - *auto_devop
 ```
 
-Please check the [Auto-DevOps template](https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml) for full reference.
-
-Behind the scenes, the [GitLab SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast)
-is used to detect the languages/frameworks 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 please
-check [GitLab SAST documentation](https://gitlab.com/gitlab-org/security-products/sast#remote-checks).
-
 The above example will create a `sast` job in your CI pipeline and will allow
-you to download and analyze the report artifact in JSON format.
+you to download and analyze the report artifact in JSON format. 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:
 
@@ -76,6 +71,13 @@ The results are sorted by the priority of the vulnerability:
 1. Unknown
 1. Everything else
 
+Behind the scenes, the [GitLab SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast)
+is used to detect the languages/frameworks 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 SAST tool documentation](https://gitlab.com/gitlab-org/security-products/sast#remote-checks).
+
 TIP: **Tip:**
 Starting with [GitLab Ultimate][ee] 10.3, this information will
 be automatically extracted and shown right in the merge request widget. To do

doc/topics/autodevops/index.md

@@ -441,6 +441,8 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac
 | `POSTGRES_PASSWORD` | The PostgreSQL password; defaults to `testing-password`. Set it to use a custom password. |
 | `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).|
 
 TIP: **Tip:**
 Set up the replica variables using a

doc/user/project/merge_requests/dast.md

@@ -36,11 +36,9 @@ prerequisites:
 
 - the specified job **must** be named `dast`
 - the resulting report **must** be named `gl-dast-report.json` and uploaded as an
-  artifact. This JSON file needs to be the only artifact file for the job. If
-  you try to also include other files, it will break the vulnerability display
-  in the merge request.
+  artifact
 
-The `sast` job will perform an analysis on the running web application, the
+The `dast` 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.
 

doc/user/project/merge_requests/sast.md

@@ -11,9 +11,7 @@ by implicitly using [Auto SAST](../../../topics/autodevops/index.md#auto-sast)
 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:
-
-![SAST Widget](img/sast.png)
+request widget area.
 
 ## Use cases
 
@@ -25,7 +23,7 @@ request widget area:
 
 ## Supported languages and frameworks
 
-The following languages and frameworks are supported:
+The following languages and frameworks are supported.
 
 | Language (package managers) / framework | Scan tool |
 | ---------------------- | --------- |
@@ -36,19 +34,26 @@ The following languages and frameworks are supported:
 | Java ([Maven](http://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 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).
+
 ## How it works
 
-In order for the report to show in the merge request, you need to specify a
-`sast` job (exact name) that will analyze the code and upload the resulting
-`gl-sast-report.json` file as an artifact. GitLab will then check this file and
-show the information inside the merge request.
+First of all, you need to define a job named `sast` in your `.gitlab-ci.yml`
+file. [Check how the `sast` 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 `sast`
+- the resulting report **must** be named `gl-sast-report.json` and uploaded as
+  an artifact
 
-This JSON file needs to be the only artifact file for the job. If you try
-to also include other files, it will break the vulnerability display in the
-merge request.
+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.
 
-For more information on how the `sast` job should look like, check the
-[example on analyzing a project's code for vulnerabilities][cc-docs].
+![SAST Widget](img/gemnasium.png)
 
 [ee-3775]: https://gitlab.com/gitlab-org/gitlab-ee/issues/3775
 [ee]: https://about.gitlab.com/products/

doc/user/project/merge_requests/sast_docker.md

@@ -11,7 +11,7 @@ a Vulnerability Static Analysis tool for containers.
 Going a step further, GitLab can show the vulnerability list right in the merge
 request widget area.
 
-![SAST Widget](img/sast-image.png)
+![SAST Docker Widget](img/sast_docker.png)
 
 ## Use cases
 
@@ -30,10 +30,6 @@ In order for the report to show in the merge request, you need to specify a
 resulting `gl-sast-container-report.json` file as an artifact (exact filename).
 GitLab will then check this file and show the information inside the merge request.
 
-This JSON file needs to be the only artifact file for the job. If you try
-to also include other files, it will break the vulnerability display in the
-merge request.
-
 For more information on how the `sast:container` job should look like, check the
 example on [analyzing a Docker image for vulnerabilities][cc-docs].