diff options
Diffstat (limited to 'doc/user/application_security/sast/index.md')
| -rw-r--r-- | doc/user/application_security/sast/index.md | 70 |
1 files changed, 52 insertions, 18 deletions
diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 49e194a9319..fb3bc256e11 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,15 +1,16 @@ --- stage: Secure group: Static Analysis -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- # Static Application Security Testing (SAST) -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. +> - All open source (OSS) analyzers were moved to GitLab Core in GitLab 13.3. -NOTE: **Note:** +NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your organization. @@ -50,16 +51,16 @@ To run SAST jobs, by default, you need GitLab Runner with the [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared runners on GitLab.com, this is enabled by default. -CAUTION: **Caution:** +WARNING: Our SAST jobs require a Linux container type. Windows containers are not yet supported. -CAUTION: **Caution:** +WARNING: 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 -GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we will automatically run the appropriate SAST analyzers. +GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we automatically run the appropriate SAST analyzers. You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). @@ -93,6 +94,31 @@ Note that the Java analyzers can also be used for variants like the [Grails](https://grails.org/), and the [Maven wrapper](https://github.com/takari/maven-wrapper). +### Multi-project support + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4895) in GitLab 13.7. + +GitLab SAST can scan repositories that contain multiple projects. All projects must be in the same +language. + +The following analyzers have multi-project support: + +- Bandit +- ESLint +- Gosec +- Kubesec +- NodeJsScan +- MobSF +- PMD +- Security Code Scan +- SpotBugs +- Sobelow + +#### Enable multi-project support for Security Code Scan + +Multi-project support in the Security Code Scan requires a Solution (`.sln`) file in the root of +the repository. For details on the Solution format, see the Microsoft reference [Solution (.sln) file](https://docs.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file?view=vs-2019). + ### Making SAST analyzers available to all GitLab tiers All open source (OSS) analyzers have been moved to the GitLab Core tier as of GitLab 13.3. @@ -188,7 +214,7 @@ the pipeline configuration, the last mention of the variable takes precedence. ### Overriding SAST jobs -CAUTION: **Deprecation:** +WARNING: Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. @@ -330,13 +356,13 @@ variables: If your project requires custom build configurations, it can be preferable to avoid compilation during your SAST execution and instead pass all job artifacts from an -earlier stage within the pipeline. This is the current strategy when requiring +earlier stage in the pipeline. This is the current strategy when requiring a `before_script` execution to prepare your scan job. To pass your project's dependencies as artifacts, the dependencies must be included in the project's working directory and specified using the `artifacts:path` configuration. If all dependencies are present, the `COMPILE=false` variable can be provided to the -analyzer and compilation will be skipped: +analyzer and compilation is skipped: ```yaml image: maven:3.6-jdk-8-alpine @@ -379,7 +405,10 @@ SAST can be [configured](#customizing-the-sast-settings) using environment varia #### Logging level -To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. + +To control the verbosity of logs, set the `SECURE_LOG_LEVEL` environment variable. Messages of this +logging level or higher are output. From highest to lowest severity, the logging levels are: @@ -392,7 +421,7 @@ From highest to lowest severity, the logging levels are: #### Custom Certificate Authority To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle -of CA certs that you want to trust within the SAST environment. +of CA certs that you want to trust in the SAST environment. #### Docker images @@ -410,8 +439,8 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | Environment variable | Default value | Description | |-------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories will also match patterns. | -| `SEARCH_MAX_DEPTH` | 4 | Maximum number of directories traversed when searching for source code files. | +| `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. You might need to exclude temporary directories used by your build tool as these can generate false positives. | +| `SEARCH_MAX_DEPTH` | 4 | SAST searches the repository to detect the programming languages used, and selects the matching analyzers. Set the value of `SEARCH_MAX_DEPTH` to specify how many directory levels the search phase should span. After the analyzers have been selected, the _entire_ repository is analyzed. | | `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | | `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. | @@ -424,7 +453,7 @@ Some analyzers can be customized with environment variables. | Environment variable | Analyzer | Description | |---------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | -| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` will scan. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | +| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` scans. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | | `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | | `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | | `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. | @@ -451,15 +480,20 @@ all [custom environment variables](../../../ci/variables/README.md#custom-enviro to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. -CAUTION: **Caution:** +WARNING: Variables having names starting with these prefixes are **not** propagated to the SAST Docker container and/or analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. ### Experimental features -Receive early access to experimental features. +You can receive early access to experimental features. Experimental features might be added, +removed, or promoted to regular features at any time. + +Experimental features available are: + +- Enable scanning of iOS and Android apps using the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). -Currently, this will enable scanning of iOS and Android apps via the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). +#### Enable experimental features To enable experimental features, add the following to your `.gitlab-ci.yml` file: @@ -571,7 +605,7 @@ Once a vulnerability is found, you can interact with it. Read more on how to ## Vulnerabilities database -Vulnerabilities contained within the vulnerability database can be searched +Vulnerabilities contained in the vulnerability database can be searched and viewed at the [GitLab vulnerability advisory database](https://advisories.gitlab.com). ### Vulnerabilities database update |