summaryrefslogtreecommitdiff
path: root/doc/user/application_security/sast/index.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/application_security/sast/index.md')
-rw-r--r--doc/user/application_security/sast/index.md57
1 files changed, 31 insertions, 26 deletions
diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md
index fd05ecad8f2..de2f9af82c7 100644
--- a/doc/user/application_security/sast/index.md
+++ b/doc/user/application_security/sast/index.md
@@ -2,13 +2,11 @@
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/#assignments
-type: reference, howto
---
# Static Application Security Testing (SAST) **(FREE)**
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in GitLab 10.3.
-> - All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3.
+> All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3.
NOTE:
The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/)
@@ -51,6 +49,8 @@ the analyzer outputs an [exit code](../../../development/integrations/secure.md#
## Requirements
+SAST runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required.
+
To run SAST jobs, by default, you need GitLab Runner with the
[`docker`](https://docs.gitlab.com/runner/executors/docker.html) or
[`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor.
@@ -168,10 +168,9 @@ To configure SAST for a project you can:
### Configure SAST manually
-For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/index.md#includetemplate)
+To enable SAST you must [include](../../../ci/yaml/index.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)
-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.
+provided as a part of your GitLab installation.
Add the following to your `.gitlab-ci.yml` file:
@@ -269,7 +268,7 @@ versions are pulled, there are certain cases where it can be beneficial to pin
an analyzer to a specific release. To do so, override the `SAST_ANALYZER_IMAGE_TAG` CI/CD variable
in the job template directly.
-In the example below, we pin to a specific patch version of the `spotbugs` analyzer and minor version of the `semgrep` analyzer:
+In the example below, we pin to a minor version of the `semgrep` analyzer and a specific patch version of the `brakeman` analyzer:
```yaml
include:
@@ -277,11 +276,11 @@ include:
semgrep-sast:
variables:
- SAST_ANALYZER_IMAGE_TAG: "2.12"
+ SAST_ANALYZER_IMAGE_TAG: "2.16"
-spotbugs-sast:
+brakeman-sast:
variables:
- SAST_ANALYZER_IMAGE_TAG: "2.28.1"
+ SAST_ANALYZER_IMAGE_TAG: "2.21.1"
```
### Customize rulesets **(ULTIMATE)**
@@ -311,9 +310,9 @@ To disable analyzer rules:
1. Set the `disabled` flag to `true` in the context of a `ruleset` section
-1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has:
+1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has:
-- a `type` field, to name the predefined rule identifier that the targeted analyzer uses.
+- a `type` field, to name the predefined rule identifier that the targeted analyzer uses.
- a `value` field, to name the rule to be disabled.
@@ -346,7 +345,7 @@ and `sobelow` by matching the `type` and `value` of identifiers:
#### Synthesize a custom configuration
-To create a custom configuration, you can use passthrough chains.
+To create a custom configuration, you can use passthrough chains.
A passthrough is a single step in a passthrough chain. The passthrough is evaluated
in a sequence to incrementally build a configuration. The configuration is then
@@ -360,8 +359,8 @@ parameters:
| `description` | Description about the analyzer configuration section. |
| `targetdir` | The `targetdir` parameter defines the directory where the final configuration is located. If `targetdir` is empty, the analyzer uses a random directory. The maximum size of `targetdir` is 100MB. |
| `validate` | If set to `true`, the target files for passthroughs (`raw`, `file` and `url`) are validated. The validation works for `yaml`, `xml`, `json` and `toml` files. The proper validator is identified based on the extension of the target file. By default, `validate` is set to `false`. |
-| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. |
-| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. |
+| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. |
+| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. |
A configuration section can include one or more passthrough sections. The maximum number of passthrough sections is 20.
There are several types of passthroughs:
@@ -374,12 +373,12 @@ There are several types of passthroughs:
| `url` | Fetch the analyzer configuration through HTTP. |
If multiple passthrough sections are defined in a passthrough chain, their
-position in the chain defines the order in which they are evaluated.
+position in the chain defines the order in which they are evaluated.
-- Passthroughs listed later in the chain sequence have a higher precedence.
+- Passthroughs listed later in the chain sequence have a higher precedence.
- Passthroughs with a higher precedence overwrite (default) and append data
yielded by previous passthroughs. This is useful for cases where you need to
- use or modify an existing configuration.
+ use or modify an existing configuration.
Configure a passthrough these parameters:
@@ -454,7 +453,7 @@ file `gosec-config.json`:
##### Passthrough chain for semgrep
In the below example, we generate a custom configuration under the `/sgrules`
-target directory with a total `timeout` of 60 seconds.
+target directory with a total `timeout` of 60 seconds.
Several passthrouh types generate a configuration for the target analyzer:
@@ -463,17 +462,17 @@ Several passthrouh types generate a configuration for the target analyzer:
`97f7686` from the `sast-rules` Git repostory. From the `sast-rules` Git
repository, only data from the `go` subdirectory is considered.
- The `sast-rules` entry has a higher precedence because it appears later in
- the configuration.
+ the configuration.
- If there is a filename collision between files in both repositories, files
from the `sast` repository overwrite files from the `myrules` repository,
as `sast-rules` has higher precedence.
- The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The
- full path is `/sgrules/insecure.yml`.
+ full path is `/sgrules/insecure.yml`.
- The `url` entry fetches a configuration made available through a URL and
- stores it in the `/sgrules/gosec.yml` file.
+ stores it in the `/sgrules/gosec.yml` file.
Afterwards, semgrep is invoked with the final configuration located under
-`/sgrules`.
+`/sgrules`.
```toml
[semgrep]
@@ -537,17 +536,17 @@ It does not explicitly store credentials in the configuration file. To reduce th
##### Configure the append mode for passthroughs
To append data to previous passthroughs, use the `append` mode for the
-passthrough types `file`, `url`, and `raw`.
+passthrough types `file`, `url`, and `raw`.
Passthroughs in `override` mode overwrite files
created when preceding passthroughs in the chain find a naming
collision. If `mode` is set to `append`, a passthrough appends data to the
-files created by its predecessors instead of overwriting.
+files created by its predecessors instead of overwriting.
In the below semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are:
- `insecure`
-- `secret`
+- `secret`
These rules add a search pattern to the analyzer and extends semgrep capabilities.
@@ -1057,6 +1056,12 @@ For Maven builds, add the following to your `pom.xml` file:
</properties>
```
+### SpotBugs Error: `Project couldn't be built`
+
+If your job is failing at the build step with the message "Project couldn't be built", it's most likely because your job is asking SpotBugs to build with a tool that isn't part of its default tools. For a list of the SpotBugs default tools, see [SpotBugs' asdf dependencies](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/raw/master/config/.tool-versions).
+
+The solution is to use [pre-compilation](#pre-compilation). Pre-compilation ensures the images required by SpotBugs are available in the job's container.
+
### Flawfinder encoding error
This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/index.md#before_script) feature.