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

Documentation for SAST results in MR widget

Closes #4125

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

doc/README.md

@@ -107,6 +107,7 @@ Manage your [repositories](user/project/repository/index.md) from the UI (user i
   - [Work In Progress Merge Requests](user/project/merge_requests/work_in_progress_merge_requests.md)
   - [Merge Request discussion resolution](user/discussions/index.md#moving-a-single-discussion-to-a-new-issue): Resolve discussions, move discussions in a merge request to an issue, only allow merge requests to be merged if all discussions are resolved.
   - **(EES/EEP)** [Merge Request approval](user/project/merge_requests/merge_request_approvals.md): Make sure every merge request is approved by one or more people before getting merged.
+  - **(EEU)** [Static Application Security Testing](user/project/merge_requests/sast.md): Scan your code for vulnerabilities and display the results in merge requests.
   - [Checkout merge requests locally](user/project/merge_requests/index.md#checkout-merge-requests-locally)
   - [Cherry-pick](user/project/merge_requests/cherry_pick_changes.md)
 - [Milestones](user/project/milestones/index.md): Organize issues and merge requests into a cohesive group, optionally setting a due date.

doc/ci/examples/README.md

@@ -58,6 +58,10 @@ Apart from those, here is an collection of tutorials and guides on setting up yo
 
 - [Analyze code quality with the Code Climate CLI](code_climate.md)
 
+### Static Application Security Testing (SAST)
+
+- [Scan your code for vulnerabilities](sast.md)
+
 ### Other
 
 - [Using `dpl` as deployment tool](deployment/README.md)

doc/ci/examples/sast.md

+# Static application security testing with GitLab CI/CD
+
+NOTE: **Note:**
+In order to use this tool, a [GitLab Enterprise Edition Ultimate][ee] license
+is needed.
+
+This example shows 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.
+
+All you need is a GitLab Runner with the Docker executor (the shared Runners on
+GitLab.com will work fine). You can then add a new job to `.gitlab-ci.yml`,
+called `sast`:
+
+```yaml
+sast:
+  image: registry.gitlab.com/gitlab-org/gl-sast:latest
+  script:
+    - /app/bin/run .
+  artifacts:
+    paths: [gl-sast-report.json]
+```
+
+Behind the scenes, the [gl-sast Docker image](https://gitlab.com/gitlab-org/gl-sast)
+is used to detect the language/framework and in turn runs the matching scan tool.
+
+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.
+
+The results are sorted by the priority of the vulnerability:
+
+1. High
+1. Medium
+1. Low
+1. Unknown
+1. Everything else
+
+TIP: **Tip:**
+Starting with GitLab Enterprise Edition Ultimate 10.3, this information will
+be automatically extracted and shown right in the merge request widget. To do
+so, the CI job must be named `sast` and the artifact path must be
+`gl-sast-report.json`.
+[Learn more on application security testing results shown in merge requests](../../user/project/merge_requests/sast.md).
+
+## Supported languages and frameworks
+
+The following languages and frameworks are supported.
+
+| Language / framework | Scan tool |
+| -------------------- | --------- |
+| JavaScript    | [Retire.js](https://retirejs.github.io/retire.js)
+| Python        | [bandit](https://github.com/openstack/bandit) |
+| Ruby          | [bundler-audit](https://github.com/rubysec/bundler-audit) |
+| Ruby on Rails | [brakeman](https://brakemanscanner.org) |
+
+[ee]: https://about.gitlab.com/gitlab-ee/

doc/topics/autodevops/index.md

@@ -19,6 +19,7 @@ project in an easy and automatic way:
 1. [Auto Build](#auto-build)
 1. [Auto Test](#auto-test)
 1. [Auto Code Quality](#auto-code-quality)
+1. [Auto SAST (Static Application Security Testing)](#auto-sast)
 1. [Auto Review Apps](#auto-review-apps)
 1. [Auto Deploy](#auto-deploy)
 1. [Auto Monitoring](#auto-monitoring)
@@ -198,6 +199,18 @@ out. In GitLab Enterprise Edition Starter, differences between the source and
 target branches are
 [shown in the merge request widget](../../user/project/merge_requests/code_quality_diff.md).
 
+### Auto SAST
+
+> Introduced in [GitLab Enterprise Edition Ultimate][ee] 10.3.
+
+Static Application Security Testing (SAST) uses the
+[gl-sast Docker image](https://gitlab.com/gitlab-org/gl-sast) to run static
+analysis on the current code 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.
+
+Any security warnings are also [shown in the merge request widget](../../user/project/merge_requests/sast.md).
+
 ### Auto Review Apps
 
 NOTE: **Note:**
@@ -536,3 +549,4 @@ curl --data "value=true" --header "PRIVATE-TOKEN: personal_access_token" https:/
 [postgresql]: https://www.postgresql.org/
 [Auto DevOps template]: https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml
 [GitLab Omnibus Helm Chart]: ../../install/kubernetes/gitlab_omnibus.md
+[ee]: https://about.gitlab.com/gitlab-ee/

doc/user/index.md

@@ -55,6 +55,7 @@ and [Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board.
 - [Lock files](https://docs.gitlab.com/ee/user/project/file_lock.html) to prevent conflicts
 - View of the current health and status of each CI environment running on Kubernetes with [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html)
 - Leverage your continuous delivery method with [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html)
+- Scan your code for vulnerabilities and [display them in merge requests](project/merge_requests/sast.md).
 
 You can also [integrate](project/integrations/project_services.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, JIRA, and a lot more.
 

doc/user/project/merge_requests/index.md

@@ -193,6 +193,17 @@ can show the Code Climate report right in the merge request widget area.
 
 [Read more about Code Quality reports.](code_quality_diff.md)
 
+## Static Application Security Testing
+
+> Introduced in [GitLab Enterprise Edition Ultimate][products] 10.3.
+
+If you are using [GitLab CI/CD][ci], you can analyze your source code for known
+vulnerabilities using Static Application Security Testing (SAST).
+Going a step further, GitLab can show the vulnerability report right in the
+merge request widget area.
+
+[Read more about Static Application Security Testing reports.](sast.md)
+
 ## Live preview with Review Apps
 
 If you configured [Review Apps](https://about.gitlab.com/features/review-apps/) for your project,

doc/user/project/merge_requests/sast.md

+# Static Application Security Testing (SAST)
+
+> [Introduced][ee-3775] in [GitLab Enterprise Edition Ultimate][ee] 10.3.
+
+## Overview
+
+If you are using [GitLab CI/CD][ci], you can analyze your source code for known
+vulnerabilities using Static Application Security Testing (SAST).
+
+Going a step further, GitLab can show the vulnerability list right in the merge
+request widget area:
+
+![SAST Widget](img/sast.png)
+
+## Use cases
+
+- Your application is using an external (open source) library, locked to a
+  specific version (e.g., via `Gemfile.lock`) and the version is known to be
+  vulnerable.
+- Your code has a potentially dangerous attribute in a class, or unsafe code
+  that can lead to unintended code execution.
+
+## 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.
+
+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` job should look like, check the
+example on [analyzing a project's code for vulnerabilities][cc-docs].
+
+[ee-3775]: https://gitlab.com/gitlab-org/gitlab-ee/issues/3775
+[ee]: https://about.gitlab.com/gitlab-ee/
+[ci]: ../../../ci/README.md
+[cc-docs]: ../../../ci/examples/sast.md