Skip to content

G
gitlab-ce
Commit fa5d641b authored by Evan Read's avatar Evan Read
Browse files
Options

Merge branch 'docs-aqualls-sast-review' into 'master' 

Docs: tone and style issues on SAST page

See merge request gitlab-org/gitlab!31011
parents dbbdd07d 09a812eb
Show whitespace changes
Inline Side-by-side
Showing with 55 additions and 48 deletions
.markdownlint.json
View file @ fa5d641b
......@@ -59,6 +59,7 @@
"GitLab Shell",
"GitLab Workhorse",
"GitLab",
"Gitleaks",
"Gmail",
"Google",
"Grafana",
......@@ -114,6 +115,7 @@
"Shibboleth",
"Slack",
"SMTP",
"SpotBugs",
"SSH",
"Tiller",
"TOML",
......
doc/.vale/gitlab/spelling-exceptions.txt
View file @ fa5d641b
......@@ -101,6 +101,7 @@ failovers
failsafe
favicon
firewalled
Flawfinder
Flowdock
Fluentd
Forgerock
......@@ -112,9 +113,11 @@ Gitea
GitHub
GitLab
gitlabsos
Gitleaks
Gitter
Gmail
Google
Gosec
Gradle
Grafana
gravatar
......@@ -160,6 +163,7 @@ Kibana
Knative
Kramdown
Kubernetes
Kubesec
Laravel
LDAP
Libravatar
......@@ -305,9 +309,11 @@ serializing
Slack
Slony
SMTP
Sobelow
Sourcegraph
spidering
Splunk
SpotBugs
SSH
storable
strace
......
doc/user/application_security/sast/index.md
View file @ fa5d641b
......@@ -13,7 +13,7 @@ to learn how to protect your organization.
## Overview
If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known
If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known
vulnerabilities using Static Application Security Testing (SAST).
You can take advantage of SAST by doing one of the following:
......@@ -37,7 +37,7 @@ The results are sorted by the priority of the vulnerability:
1. Everything else
NOTE: **Note:**
A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard will not show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure.
A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard won't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard won't show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure.
## Use cases
......@@ -55,12 +55,12 @@ executor running in privileged mode. If you're using the shared Runners on GitLa
this is enabled by default.
Privileged mode is not necessary if you've [disabled Docker in Docker
for SAST](#disabling-docker-in-docker-for-sast)
for SAST](#disabling-docker-in-docker-for-sast).
CAUTION: **Caution:** Our SAST jobs currently expect a Linux container type. Windows containers are not yet supported.
CAUTION: **Caution:**
If you use your own Runners, make sure that the Docker version you have installed
If you use your own Runners, make sure the Docker version installed
is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details.
## Supported languages and frameworks
......@@ -71,7 +71,7 @@ The following table shows which languages, package managers and frameworks are s
|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------|
| .NET | [Security Code Scan](https://security-code-scan.github.io) | 11.0 |
| Any | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11.9 |
| Apex (Salesforce) | [pmd](https://pmd.github.io/pmd/index.html) | 12.1 |
| Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 |
| C/C++ | [Flawfinder](https://dwheeler.com/flawfinder/) | 10.7 |
| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10 |
| Go | [Gosec](https://github.com/securego/gosec) | 10.7 |
......@@ -85,7 +85,7 @@ The following table shows which languages, package managers and frameworks are s
| React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 |
| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 |
| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) |
| TypeScript | [TSLint config security](https://github.com/webschik/tslint-config-security/) | 11.9 |
| TypeScript | [`tslint-config-security`](https://github.com/webschik/tslint-config-security/) | 11.9 |
NOTE: **Note:**
The Java analyzers can also be used for variants like the
......@@ -104,7 +104,7 @@ provided by [Auto DevOps](../../../topics/autodevops/index.md).
For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/README.md#includetemplate)
the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml)
that is provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you
provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you
can copy and use the job as defined that template.
Add the following to your `.gitlab-ci.yml` file:
......@@ -122,14 +122,13 @@ The results will be saved as a
that you can later download and analyze. Due to implementation limitations, we
always take the latest SAST artifact available. 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.
is used to detect the languages or frameworks used, and in turn runs the matching scan tools.
### Customizing the SAST settings
The SAST settings can be changed through [environment variables](#available-variables)
by using the
[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
In the following example, we include the SAST template and at the same time we
set the `SAST_GOSEC_LEVEL` variable to `2`:
......@@ -142,7 +141,7 @@ variables:
```
Because the template is [evaluated before](../../../ci/yaml/README.md#include)
the pipeline configuration, the last mention of the variable will take precedence.
the pipeline configuration, the last mention of the variable takes precedence.
### Overriding the SAST template
......@@ -173,10 +172,10 @@ it via [custom environment variables](#custom-environment-variables).
#### Using a variable to pass username and password to a private Maven repository
If you have a private Maven repository which requires login credentials,
If your private Maven repository requires login credentials,
you can use the `MAVEN_CLI_OPTS` environment variable.
Read more on [how to use private Maven repos](../index.md#using-private-maven-repos).
Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos).
### Disabling Docker in Docker for SAST
......@@ -198,11 +197,11 @@ to start relevant analyzers depending on the detected repository language(s) ins
[orchestrator](https://gitlab.com/gitlab-org/security-products/dependency-scanning/). However, there
are some differences in the way repository languages are detected between DIND and non-DIND. You can
observe these differences by checking both Linguist and the common library. For instance, Linguist
looks for `*.java` files to spin up the [spotbugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs)
looks for `*.java` files to spin up the [SpotBugs](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs)
image, while orchestrator only looks for the existence of `pom.xml`, `build.xml`, `gradlew`,
`grailsw`, or `mvnw`. GitLab uses Linguist to detect new file types in the default branch. This
means that when introducing files or dependencies for a new language or package manager, the
corresponding scans won't be triggered in the MR and will only run on the default branch once the
`grailsw`, or `mvnw`. GitLab uses Linguist to detect new file types in the default branch.
When introducing files or dependencies for a new language or package manager, the
corresponding scans won't be triggered in the MR, and will only run on the default branch once the
MR is merged. This will be addressed by [#211702](https://gitlab.com/gitlab-org/gitlab/-/issues/211702).
NOTE: **Note:**
......@@ -210,13 +209,13 @@ With the current language detection logic, any new languages or frameworks intro
context of a merge request don't trigger a corresponding scan. These scans only occur once the code
is committed to the default branch.
#### Enabling kubesec analyzer
#### Enabling Kubesec analyzer
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12752) in GitLab Ultimate 12.6.
When [Docker in Docker is disabled](#disabling-docker-in-docker-for-sast),
you will need to set `SCAN_KUBERNETES_MANIFESTS` to `"true"` to enable the
kubesec analyzer. In `.gitlab-ci.yml`, define:
Kubesec analyzer. In `.gitlab-ci.yml`, define:
```yaml
include:
......@@ -310,10 +309,10 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre
| `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. |
| `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. |
| `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. |
| `SAST_GOSEC_LEVEL` | 0 | Ignore gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. |
| `SAST_GITLEAKS_COMMIT_FROM` | - | The commit a gitleaks scan starts at. |
| `SAST_GITLEAKS_COMMIT_TO` | - | The commit a gitleaks scan ends at. |
| `SAST_GITLEAKS_HISTORIC_SCAN` | false | Flag to enable a historic gitleaks scan. |
| `SAST_GOSEC_LEVEL` | 0 | Ignore Gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. |
| `SAST_GITLEAKS_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. |
| `SAST_GITLEAKS_COMMIT_TO` | - | The commit a Gitleaks scan ends at. |
| `SAST_GITLEAKS_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. |
#### Docker-in-Docker orchestrator
......@@ -323,9 +322,9 @@ The following variables configure the Docker-in-Docker orchestrator.
|------------------------------------------|---------------|-------------|
| `SAST_ANALYZER_IMAGES` | | Comma-separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). Not available when [Docker-in-Docker is disabled](#disabling-docker-in-docker-for-sast). |
| `SAST_PULL_ANALYZER_IMAGES` | 1 | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). Not available when [Docker-in-Docker is disabled](#disabling-docker-in-docker-for-sast). |
| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". |
| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". |
| `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m".|
| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. |
| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. |
| `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`.|
NOTE: **Note:**
Timeout variables are not applicable for setups with [disabled Docker In Docker](index.md#disabling-docker-in-docker-for-sast).
......@@ -336,18 +335,18 @@ Some analyzers can be customized with environment variables.
| Environment variable | Analyzer | Description |
|-----------------------------|----------|-------------|
| `SCAN_KUBERNETES_MANIFESTS` | kubesec | Set to `"true"` to scan Kubernetes manifests when [Docker in Docker](#disabling-docker-in-docker-for-sast) is disabled. |
| `ANT_HOME` | spotbugs | The `ANT_HOME` environment variable. |
| `ANT_PATH` | spotbugs | Path to the `ant` executable. |
| `GRADLE_PATH` | spotbugs | Path to the `gradle` executable. |
| `JAVA_OPTS` | spotbugs | Additional arguments for the `java` executable. |
| `JAVA_PATH` | spotbugs | Path to the `java` executable. |
| `SAST_JAVA_VERSION` | spotbugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. |
| `MAVEN_CLI_OPTS` | spotbugs | Additional arguments for the `mvn` or `mvnw` executable. |
| `MAVEN_PATH` | spotbugs | Path to the `mvn` executable. |
| `MAVEN_REPO_PATH` | spotbugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). |
| `SBT_PATH` | spotbugs | Path to the `sbt` executable. |
| `FAIL_NEVER` | spotbugs | Set to `1` to ignore compilation failure. |
| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests when [Docker in Docker](#disabling-docker-in-docker-for-sast) is disabled. |
| `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. |
| `ANT_PATH` | SpotBugs | Path to the `ant` executable. |
| `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. |
| `JAVA_OPTS` | SpotBugs | Additional arguments for the `java` executable. |
| `JAVA_PATH` | SpotBugs | Path to the `java` executable. |
| `SAST_JAVA_VERSION` | SpotBugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. |
| `MAVEN_CLI_OPTS` | SpotBugs | Additional arguments for the `mvn` or `mvnw` executable. |
| `MAVEN_PATH` | SpotBugs | Path to the `mvn` executable. |
| `MAVEN_REPO_PATH` | SpotBugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). |
| `SBT_PATH` | SpotBugs | Path to the `sbt` executable. |
| `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. |
#### Custom environment variables
......@@ -454,8 +453,8 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
| `version` | Report syntax version used to generate this JSON. |
| `vulnerabilities` | Array of vulnerability objects. |
| `vulnerabilities[].id` | Unique identifier of the vulnerability. |
| `vulnerabilities[].category` | Where this vulnerability belongs (SAST, Dependency Scanning etc.). For SAST, it will always be `sast`. |
| `vulnerabilities[].name` | Name of the vulnerability, this must not include the occurrence's specific information. Optional. |
| `vulnerabilities[].category` | Where this vulnerability belongs (such as SAST, Dependency Scanning). For SAST, it will always be `sast`. |
| `vulnerabilities[].name` | Name of the vulnerability. Must not include the occurrence's specific information. Optional. |
| `vulnerabilities[].message` | A short text that describes the vulnerability, it may include the occurrence's specific information. Optional. |
| `vulnerabilities[].description` | A long text that describes the vulnerability. Optional. |
| `vulnerabilities[].cve` | (**DEPRECATED - use `vulnerabilities[].id` instead**) A fingerprint string value that represents a concrete occurrence of the vulnerability. It's used to determine whether two vulnerability occurrences are same or different. May not be 100% accurate. **This is NOT a [CVE](https://cve.mitre.org/)**. |
......@@ -471,8 +470,8 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
| `vulnerabilities[].location.end_line` | The last line of the code affected by the vulnerability. Optional. |
| `vulnerabilities[].location.class` | If specified, provides the name of the class where the vulnerability is located. Optional. |
| `vulnerabilities[].location.method` | If specified, provides the name of the method where the vulnerability is located. Optional. |
| `vulnerabilities[].identifiers` | An ordered array of references that identify a vulnerability on internal or external DBs. |
| `vulnerabilities[].identifiers[].type` | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (e.g., `bandit_test_id` for [Bandit analyzer](https://wiki.openstack.org/wiki/Security/Projects/Bandit)). |
| `vulnerabilities[].identifiers` | An ordered array of references that identify a vulnerability on internal or external databases. |
| `vulnerabilities[].identifiers[].type` | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (like `bandit_test_id` for [Bandit analyzer](https://wiki.openstack.org/wiki/Security/Projects/Bandit)). |
| `vulnerabilities[].identifiers[].name` | Name of the identifier for display purposes. |
| `vulnerabilities[].identifiers[].value` | Value of the identifier for matching purposes. |
| `vulnerabilities[].identifiers[].url` | URL to identifier's documentation. Optional. |
......@@ -480,8 +479,8 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
## Secret detection
GitLab is also able to detect secrets and credentials that have been unintentionally pushed to the
repository (for example, an API key that allows write access to third-party deployment
environments).
repository, such as an API key that allows write access to third-party deployment
environments.
This check is performed by a specific analyzer during the `sast` job. It runs regardless of the programming
language of your app, and you don't need to change anything to your
......@@ -492,7 +491,7 @@ GitLab currently includes [Gitleaks](https://github.com/zricethezav/gitleaks) an
NOTE: **Note:**
The secrets analyzer will ignore "Password in URL" vulnerabilities if the password begins
with a dollar sign (`$`) as this likely indicates the password being used is an environment
variable. For example, `https://username:$password@example.com/path/to/repo` will not be
variable. For example, `https://username:$password@example.com/path/to/repo` won't be
detected, whereas `https://username:password@example.com/path/to/repo` would be detected.
## Security Dashboard
......@@ -515,13 +514,13 @@ For more information about the vulnerabilities database update, check the
For self-managed GitLab instances in an environment with limited, restricted, or intermittent access
to external resources through the internet, some adjustments are required for the SAST job to
successfully run. For more information, see [Offline environments](../offline_deployments/index.md).
run successfully. For more information, see [Offline environments](../offline_deployments/index.md).
### Requirements for offline SAST
To use SAST in an offline environment, you need:
- [Disable Docker-In-Docker](#disabling-docker-in-docker-for-sast)
- To [disable Docker-In-Docker](#disabling-docker-in-docker-for-sast).
- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements).
- Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images.
......@@ -560,7 +559,7 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/tslint:2
The process for importing Docker images into a local offline Docker registry depends on
**your network security policy**. Please consult your IT staff to find an accepted and approved
process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
with new definitions, so consider if you are able to make periodic updates yourself.
with new definitions, so consider if you're able to make periodic updates yourself.
For details on saving and transporting Docker images as a file, see Docker's documentation on
[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/),
......@@ -588,6 +587,6 @@ security reports without requiring internet access.
### Error response from daemon: error processing tar file: docker-tar: relocation error
This error occurs when the Docker version used to run the SAST job is `19.03.0`.
You are advised to update to Docker `19.03.1` or greater. Older versions are not
Consider updating to Docker `19.03.1` or greater. Older versions are not
affected. Read more in
[this issue](https://gitlab.com/gitlab-org/gitlab/issues/13830#note_211354992 "Current SAST container fails").
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7