diff options
Diffstat (limited to 'doc/user/application_security')
38 files changed, 495 insertions, 237 deletions
diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index f0fcd0c4419..229a8572206 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -14,17 +14,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w The security configuration page displays the configuration state of each of the security features and can be accessed through a project's sidebar nav. - + The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md) to determine the configuration state of each feature. If a job with the expected security report artifact exists in the pipeline, the feature is considered configured. -NOTE: **Note:** if the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), +NOTE: **Note:** +If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), all security features will be configured by default. ## Limitations -It is not possible to enable or disable a feature using the configuration page. -However, instructions on how to enable or disable a feature can be found through -the links next to each feature on that page. +It is not yet possible to enable or disable most features using the +configuration page. However, instructions on how to enable or disable a feature +can be found through the links next to each feature on that page. + +If a project does not have an existing CI configuration, then the SAST feature +can be enabled by clicking on the "Enable with Merge Request" button under the +"Manage" column. Future work will expand this to editing _existing_ CI +configurations, and to other security features. diff --git a/doc/user/application_security/container_scanning/img/container_scanning_v13_0.png b/doc/user/application_security/container_scanning/img/container_scanning_v13_0.png Binary files differdeleted file mode 100644 index 7a079a65072..00000000000 --- a/doc/user/application_security/container_scanning/img/container_scanning_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/container_scanning/img/container_scanning_v13_2.png b/doc/user/application_security/container_scanning/img/container_scanning_v13_2.png Binary files differnew file mode 100644 index 00000000000..254ea1dcf5d --- /dev/null +++ b/doc/user/application_security/container_scanning/img/container_scanning_v13_2.png diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 0ffe83cdfc9..7bc8b62825c 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -32,7 +32,7 @@ You can enable container scanning by doing one of the following: GitLab compares the found vulnerabilities between the source and target branches, and shows the information directly in the merge request. - + <!-- NOTE: The container scanning tool references the following heading in the code, so if you make a change to this heading, make sure to update the documentation URLs used in the @@ -58,10 +58,10 @@ To enable Container Scanning in your pipeline, you need the following: ```yaml build: - image: docker:19.03.11 + image: docker:19.03.12 stage: build services: - - docker:19.03.11-dind + - docker:19.03.12-dind variables: IMAGE_TAG: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA script: @@ -114,7 +114,7 @@ build: image: docker:stable stage: build services: - - docker:19.03.11-dind + - docker:19.03.12-dind variables: IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA script: @@ -141,7 +141,7 @@ enables verbose output from Clair by setting the `CLAIR_OUTPUT` environment vari ```yaml include: - template: Container-Scanning.gitlab-ci.yml + - template: Container-Scanning.gitlab-ci.yml variables: CLAIR_OUTPUT: High @@ -174,6 +174,7 @@ using environment variables. | `CLAIR_DB_IMAGE_TAG` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | `latest` | | `DOCKERFILE_PATH` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner will look for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | `Dockerfile` | | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs that you want to trust. | "" | +| `SECURE_LOG_LEVEL` | The log levels available are: `fatal`, `error`, `warn`, `info`, `debug` | `info` | ### Overriding the Container Scanning template @@ -183,7 +184,7 @@ specify any additional keys. For example: ```yaml include: - template: Container-Scanning.gitlab-ci.yml + - template: Container-Scanning.gitlab-ci.yml container_scanning: variables: @@ -195,15 +196,15 @@ GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/REA When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. -### Vulnerability whitelisting +### Vulnerability allowlisting -To whitelist specific vulnerabilities, follow these steps: +To allowlist specific vulnerabilities, follow these steps: 1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions in [overriding the Container Scanning template](#overriding-the-container-scanning-template). -1. Define the whitelisted vulnerabilities in a YAML file named `clair-whitelist.yml`. This must use - the format described in the [whitelist example file](https://github.com/arminc/clair-scanner/blob/v12/example-whitelist.yaml). -1. Add the `clair-whitelist.yml` file to your project's Git repository. +1. Define the allowlisted vulnerabilities in a YAML file named `vulnerability-allowlist.yml`. This must use + the format described in the [allowlist example file](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/raw/master/testdata/vulnerability-allowlist.yml). +1. Add the `vulnerability-allowlist.yml` file to your project's Git repository. ### Running Container Scanning in an offline environment @@ -282,7 +283,7 @@ stages: build_latest_vulnerabilities: stage: build services: - - docker:19.03.11-dind + - docker:19.03.12-dind script: - docker pull arminc/clair-db:latest - docker tag arminc/clair-db:latest $CI_REGISTRY/namespace/clair-vulnerabilities-db diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md new file mode 100644 index 00000000000..85da7d85506 --- /dev/null +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -0,0 +1,117 @@ +--- +stage: Secure +group: Fuzz Testing +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 +type: reference, howto +--- + +# Coverage Guided Fuzz Testing **(ULTIMATE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3226) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2 as an [Alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). + +GitLab allows you to add coverage-guided fuzz testing to your pipelines. This helps you discover +bugs and potential security issues that other QA processes may miss. Coverage-guided fuzzing sends +random inputs to an instrumented version of your application in an effort to cause unexpected +behavior, such as a crash. Such behavior indicates a bug that you should address. + +We recommend that you use fuzz testing in addition to the other security scanners in [GitLab Secure](../index.md) +and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md), +you can run your coverage guided fuzz tests as part your CI/CD workflow. You can take advantage of +Coverage Guided Fuzzing by including the CI job in your existing `.gitlab-ci.yml` file. + +## Supported fuzzing engines and languages + +GitLab supports these languages through the fuzzing engine listed for each. We currently provide a Docker image for apps written in Go, but you can test the other languages below by providing a Docker image with the fuzz engine to run your app. + +| Language | Fuzzing Engine | Example | +|----------|---------------------------------------------------------------------------|---------| +| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | | +| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | | +| Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | | + +## Configuration + +To enable fuzzing, you must +[include](../../../ci/yaml/README.md#includetemplate) +the [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml) +provided as part of your GitLab installation. + +To do so, add the following to your `.gitlab-ci.yml` file: + +```yaml +include: + - template: Coverage-Fuzzing.gitlab-ci.yml +``` + +The included template makes available the [hidden job](../../../ci/yaml/README.md#hide-jobs) +`.fuzz_base`, which you must [extend](../../../ci/yaml/README.md#extends) for each of your fuzz +targets. Each fuzz target **must** have a separate job. For example, the +[go-fuzzing-example project](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) +contains one job that extends `.fuzz_base` for its single fuzz target. + +The `my_fuzz_target` job (the separate job for your fuzz target) does the following: + +- Extends `.fuzz_base`. +- Compiles the fuzz target with [go-fuzz](https://github.com/dvyukov/go-fuzz). +- Runs the target with the `gitlab-cov-fuzz` command, which is available to each job that extends + `.fuzz_base`. +- Runs on a fuzz stage that usually comes after a test stage. + +The `gitlab-cov-fuzz` is a command-line tool that runs the instrumented application. It parses and +analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](#glossary) +and crash events from previous pipelines automatically. This helps your fuzz targets build on the progress of +previous fuzzing jobs. The parsed crash events and data are written to +`gl-coverage-fuzzing-report.json`. + +### Artifacts + +Each fuzzing step outputs these artifacts: + +- `gl-coverage-fuzzing-report.json`: This file's format may change in future releases. +- `artifacts.zip`: This file contains two directories: + - `corpus`: Holds all test cases generated by the current and all previous jobs. + - `crashes`: Holds all crash events the current job encountered as well as those not fixed in + previous jobs. + +### Types of Fuzzing Jobs + +There are two types of jobs: + +- Fuzzing: Standard fuzzing session. You can configure a long session through a user defined + timeout. +- Regression: Run the fuzz targets through the accumulated test cases generated by previous fuzzing + sessions plus fixed crashes from previous sessions. This is usually very quick. + +Here's our current suggestion for configuring your fuzz target's timeout: + +- Set `COVERAGE_FUZZING_BRANCH` to the branch where you want to run long-running (async) fuzzing + jobs. This is `master` by default. +- Use regression or short-running fuzzing jobs for other branches or merge requests. + +This suggestion helps find new bugs on the development branch and catch old bugs in merge requests +(like unit tests). + +You can configure this by passing `--regression=false/true` to `gitlab-cov-fuzz` as the [Go example](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example/-/blob/master/.gitlab-ci.yml) +shows. Also note that `gitlab-cov-fuzz` is a wrapper, so you can pass those arguments to configure +any option available in the underlying fuzzing engine. + +### Available variables + +| Environment variable | Description | +|---------------------------|--------------------------------------------------------------------| +| `COVERAGE_FUZZING_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | + +### Additional Configuration + +The `gitlab-cov-fuzz` command passes all arguments it receives to the underlying fuzzing engine. You +can therefore use all the options available in that fuzzing engine. For more information on these +options, see the underlying fuzzing engine's documentation. + +### Glossary + +- Seed corpus: The set of test cases given as initial input to the fuzz target. This usually speeds + up the fuzz target substantially. This can be either manually created test cases or auto-generated + with the fuzz target itself from previous runs. +- Corpus: The set of meaningful test cases that are generated while the fuzzer is running. Each + meaningful test case produces new coverage in the tested program. It's advised to re-use the + corpus and pass it to subsequent runs. diff --git a/doc/user/application_security/dast/img/dast_all_v13_0.png b/doc/user/application_security/dast/img/dast_all_v13_0.png Binary files differdeleted file mode 100644 index 7b67fc44fae..00000000000 --- a/doc/user/application_security/dast/img/dast_all_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png b/doc/user/application_security/dast/img/dast_on_demand_v13_2.png Binary files differnew file mode 100644 index 00000000000..8a733c27be1 --- /dev/null +++ b/doc/user/application_security/dast/img/dast_on_demand_v13_2.png diff --git a/doc/user/application_security/dast/img/dast_v13_2.png b/doc/user/application_security/dast/img/dast_v13_2.png Binary files differnew file mode 100644 index 00000000000..bbf7944eb40 --- /dev/null +++ b/doc/user/application_security/dast/img/dast_v13_2.png diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 256daae46d7..d68928d858b 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -9,9 +9,9 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -NOTE: **4 of the top 6 attacks were application based.** -Download our whitepaper, -["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) +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. Running [static checks](../sast/index.md) on your code is the first step to detect @@ -36,7 +36,7 @@ NOTE: **Note:** This comparison logic uses only the latest pipeline executed for the target branch's base commit. Running the pipeline on any other commit has no effect on the merge request. - + By clicking on one of the detected linked vulnerabilities, you can see the details and the URL(s) affected. @@ -44,10 +44,10 @@ see the details and the URL(s) affected.  [Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_Application_Security_Testing) -uses the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy) +uses the popular open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) to perform an analysis on your running web application. -By default, DAST executes [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan) +By default, DAST executes [ZAP Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) and performs passive scanning only. It won't actively attack your application. However, DAST can be [configured](#full-scan) to also perform an *active scan*: attack your application and produce a more extensive security report. @@ -143,6 +143,22 @@ The only changes to the site should be from the DAST scanner. Be aware that any changes that users, scheduled tasks, database changes, code changes, other pipelines, or other scanners make to the site during a scan could lead to inaccurate results. +### Hide sensitive information + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. + +HTTP request and response headers may contain sensitive information, including cookies and +authorization credentials. By default, the following headers are masked: + +- `Authorization`. +- `Proxy-Authorization`. +- `Set-Cookie` (values only). +- `Cookie` (values only). + +Using the [`DAST_MASK_HTTP_HEADERS` variable](#available-variables), you can list the +headers whose values you want masked. For details on how to mask headers, see +[Customizing the DAST settings](#customizing-the-dast-settings). + ### Authentication It's also possible to authenticate the user before performing the DAST checks. @@ -398,6 +414,10 @@ variables: ### Customizing the DAST settings +CAUTION: **Deprecation:** +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. + The DAST settings can be changed through environment variables by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. These variables are documented in [available variables](#available-variables). @@ -410,68 +430,43 @@ include: variables: DAST_WEBSITE: https://example.com - DAST_TARGET_AVAILABILITY_TIMEOUT: 120 + DAST_SPIDER_MINS: 120 ``` Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable will take precedence. -### Overriding the DAST template - -CAUTION: **Deprecation:** -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. - -If you want to override the job definition (for example, change properties like -`variables` or `dependencies`), you need to declare a `dast` job after the -template inclusion and specify any additional keys under it. For example: - -```yaml -include: - - template: DAST.gitlab-ci.yml - -dast: - stage: dast # IMPORTANT: don't forget to add this - variables: - DAST_WEBSITE: https://example.com - CI_DEBUG_TRACE: "true" -``` - -As the DAST job belongs to a separate `dast` stage that runs after all -[default stages](../../../ci/yaml/README.md#stages), -don't forget to add `stage: dast` when you override the template job definition. - ### Available variables DAST can be [configured](#customizing-the-dast-settings) using environment variables. -| Environment variable | Required | Description | +| Environment variable | Type | Description | |-----------------------------| -----------|--------------------------------------------------------------------------------| -| `SECURE_ANALYZERS_PREFIX` | no | Set the Docker registry base address from which to download the analyzer. | -| `DAST_WEBSITE` | no| The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` | no | The API specification to import. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_AUTH_URL` | no | The authentication URL of the website to scan. Not supported for API scans. | -| `DAST_USERNAME` | no | The username to authenticate to in the website. | -| `DAST_PASSWORD` | no | The password to authenticate to in the website. | -| `DAST_USERNAME_FIELD` | no | The name of username field at the sign-in HTML form. | -| `DAST_PASSWORD_FIELD` | no | The name of password field at the sign-in HTML form. | -| `DAST_AUTH_EXCLUDE_URLS` | no | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. Not supported for API scans. | -| `DAST_TARGET_AVAILABILITY_TIMEOUT` | no | Time limit in seconds to wait for target availability. Scan is attempted nevertheless if it runs out. Integer. Defaults to `60`. | -| `DAST_FULL_SCAN_ENABLED` | no | Switches the tool to execute [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | -| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | no | Requires [domain validation](#domain-validation) when running DAST full scans. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. Not supported for API scans. | -| `DAST_AUTO_UPDATE_ADDONS` | no | By default the versions of ZAP add-ons are pinned to those provided with the DAST image. Set to `true` to allow ZAP to download the latest versions. | -| `DAST_API_HOST_OVERRIDE` | no | Used to override domains defined in API specification files. | -| `DAST_EXCLUDE_RULES` | no | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from the scan report. Currently, excluded rules will get executed but the alerts from them will be suppressed. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. | -| `DAST_REQUEST_HEADERS` | no | Set to a comma-separated list of request header names and values. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_DEBUG` | no | Enable debug message output. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | -| `DAST_SPIDER_MINS` | no | The maximum duration of the spider scan in minutes. Set to zero for unlimited. Defaults to one minute, or unlimited when the scan is a full scan. | -| `DAST_HTML_REPORT` | no | The file name of the HTML report written at the end of a scan. | -| `DAST_MARKDOWN_REPORT` | no | The file name of the Markdown report written at the end of a scan. | -| `DAST_XML_REPORT` | no | The file name of the XML report written at the end of a scan. | -| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | no | Include alpha passive and active scan rules. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | -| `DAST_USE_AJAX_SPIDER` | no | Use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | -| `DAST_ZAP_CLI_OPTIONS` | no | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | -| `DAST_ZAP_LOG_CONFIGURATION` | no | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG` | +| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | +| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` will be submitted with the login form to create an authenticated scan. Not supported for API scans. | +| `DAST_USERNAME` | string | The username to authenticate to in the website. | +| `DAST_PASSWORD` | string | The password to authenticate to in the website. | +| `DAST_USERNAME_FIELD` | string | The name of username field at the sign-in HTML form. | +| `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | +| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (introduced in GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | +| `DAST_AUTH_EXCLUDE_URLS` | URLs | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. Not supported for API scans. | +| `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | +| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | +| `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | +| `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Example: `example.com:8080` | +| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were supressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers will be added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | +| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false` | +| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. | +| `DAST_HTML_REPORT` | string | The file name of the HTML report written at the end of a scan. | +| `DAST_MARKDOWN_REPORT` | string | The file name of the Markdown report written at the end of a scan. | +| `DAST_XML_REPORT` | string | The file name of the XML report written at the end of a scan. | +| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false` | +| `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false` | +| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | +| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | ### DAST command-line options @@ -532,19 +527,20 @@ A DAST job has two executing processes: Debug mode of the scripts can be enabled by using the `DAST_DEBUG` environment variable. This can help when troubleshooting the job, and will output statements indicating what percentage of the scan is complete. -For details on using variables, see [Overriding the DAST template](#overriding-the-dast-template). +For details on using variables, see [Overriding the DAST template](#customizing-the-dast-settings). Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` environment variable. The following table outlines examples of values that can be set and the effect that they have on the output that is logged. Multiple values can be specified, separated by semicolons. -| Log configuration value | Effect | -|-------------------------------------------------- | ----------------------------------------------------------------- | -| `log4j.rootLogger=DEBUG` | Enable all debug logging statements. | -| `log4j.logger.org.apache.commons.httpclient=DEBUG` | Log every HTTP request and response made by the ZAP server. | -| `log4j.logger.com.crawljax=DEBUG` | Enable Ajax Crawler debug logging statements. | -| `log4j.logger.org.parosproxy.paros=DEBUG` | Enable ZAP server proxy debug logging statements. | -| `log4j.logger.org.zaproxy.zap=DEBUG` | Enable debug logging statements of the general ZAP server code. | +| Log configuration value | Effect | +|-------------------------------------------------- | ----------------------------------------------------------------- | +| `log4j.rootLogger=DEBUG` | Enable all debug logging statements. | +| `log4j.logger.org.apache.commons.httpclient=DEBUG` | Log every HTTP request and response made by the ZAP server. | +| `log4j.logger.org.zaproxy.zap.spider.SpiderController=DEBUG` | Log URLs found during the spider scan of the target. | +| `log4j.logger.com.crawljax=DEBUG` | Enable Ajax Crawler debug logging statements. | +| `log4j.logger.org.parosproxy.paros=DEBUG` | Enable ZAP server proxy debug logging statements. | +| `log4j.logger.org.zaproxy.zap=DEBUG` | Enable debug logging statements of the general ZAP server code. | ## Running DAST in an offline environment @@ -604,6 +600,44 @@ security reports without requiring internet access. Alternatively, you can use the variable `SECURE_ANALYZERS_PREFIX` to override the base registry address of the `dast` image. +## On-Demand Scans + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. +> - It's deployed behind a feature flag, disabled by default. +> - It's disabled on GitLab.com. +> - It's able to be enabled or disabled per-project. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-on-demand-scans). + +Passive DAST scans may be run on demand against a target website, outside the DevOps lifecycle. These scans will +always be associated with the default or `master` branch of your project and the results can be seen in the project dashboard. + + + +### Enable or disable On-Demand Scans + +On-Demand Scans is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it for your instance. On-Demand Scans can be enabled or disabled per-project + +To enable it: + +```ruby +# Instance-wide +Feature.enable(:security_on_demand_scans_feature_flag) +# or by project +Feature.enable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) +``` + +To disable it: + +```ruby +# Instance-wide +Feature.disable(:security_on_demand_scans_feature_flag) +# or by project +Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) +``` + ## Reports The DAST tool outputs a report file in JSON format by default. However, this tool can also generate reports in @@ -683,18 +717,6 @@ Once a vulnerability is found, you can interact with it. Read more on how to For more information about the vulnerabilities database update, check the [maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> - ## Optimizing DAST By default, DAST will download all artifacts defined by previous jobs in the pipeline. If @@ -734,3 +756,15 @@ variables: Here, DAST is being allocated 3072 MB. Change the number after `-Xmx` to the required memory amount. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 474f9339d0b..ca2b212ffc3 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -1,3 +1,10 @@ +--- +type: reference, howto +stage: Secure +group: Composition 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 +--- + # Dependency Scanning Analyzers **(ULTIMATE)** Dependency Scanning relies on underlying third party tools that are wrapped into diff --git a/doc/user/application_security/dependency_scanning/img/dependency_scanning_v13_0.png b/doc/user/application_security/dependency_scanning/img/dependency_scanning_v13_0.png Binary files differdeleted file mode 100644 index 9f3990df957..00000000000 --- a/doc/user/application_security/dependency_scanning/img/dependency_scanning_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/dependency_scanning/img/dependency_scanning_v13_2.png b/doc/user/application_security/dependency_scanning/img/dependency_scanning_v13_2.png Binary files differnew file mode 100644 index 00000000000..28c4eb85b7c --- /dev/null +++ b/doc/user/application_security/dependency_scanning/img/dependency_scanning_v13_2.png diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 84ec0ec976d..57b4fae3230 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -27,7 +27,7 @@ GitLab checks the Dependency Scanning report, compares the found vulnerabilities between the source and target branches, and shows the information on the merge request. - + The results are sorted by the severity of the vulnerability: @@ -61,7 +61,7 @@ The following languages and dependency managers are supported: | Language (package managers) | Supported files | Scan tool(s) | |----------------------------- | --------------- | ------------ | | Java ([Gradle](https://gradle.org/), [Maven](https://maven.apache.org/)) | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js) | +| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/)) | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | | Go ([Golang](https://golang.org/)) | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | PHP ([Composer](https://getcomposer.org/)) | `composer.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | Python ([setuptools](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/)) | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | @@ -72,7 +72,7 @@ Plans are underway for supporting the following languages, dependency managers, | Language (package managers) | Supported files | Scan tool(s) | Issue | |----------------------------- | --------------- | ------------ | ----- | -| Python ([Poetry](https://poetry.eustace.io/)) | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/issues/7006) | +| Python ([Poetry](https://python-poetry.org/)) | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | | Python ([Pipenv](https://pipenv.pypa.io/en/latest/)) | `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#11756](https://gitlab.com/gitlab-org/gitlab/-/issues/11756) | ## Contribute your scanner @@ -151,11 +151,11 @@ The following variables allow configuration of global dependency scanning settin | Environment variable | Description | | --------------------------------------- |------------ | | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | -| `DS_ANALYZER_IMAGE_PREFIX` | **DEPRECATED:** Use `SECURE_ANALYZERS_PREFIX` instead. | | `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | | `DS_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker). This variable is `true` by default. | | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. | | `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"` | +| `SECURE_LOG_LEVEL` | Default log level is `info`, you can set it to any of the following strings: `fatal`, `error`, `warn`, `info`, `debug`. | #### Configuring Docker-in-Docker orchestrator @@ -186,6 +186,7 @@ The following variables are used for configuring specific analyzers (used for a | `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | | `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | | `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1)| +| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle will use the Java version specified by this value. | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that will be passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repos). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that will be passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer will pass to `sbt`. | @@ -428,14 +429,14 @@ For details on saving and transporting Docker images as a file, see Docker's doc ### Set Dependency Scanning CI job variables to use local Dependency Scanning analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must replace -`DS_ANALYZER_IMAGE_PREFIX` to refer to your local Docker container registry: +`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: ```yaml include: - template: Dependency-Scanning.gitlab-ci.yml variables: - DS_ANALYZER_IMAGE_PREFIX: "docker-registry.example.com/analyzers" + SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers" GEMNASIUM_DB_REMOTE_URL: "gitlab.example.com/gemnasium-db.git" GIT_SSL_NO_VERIFY: "true" ``` diff --git a/doc/user/application_security/img/security_configuration_page_v13_1.png b/doc/user/application_security/img/security_configuration_page_v13_1.png Binary files differdeleted file mode 100644 index 176c64a9e87..00000000000 --- a/doc/user/application_security/img/security_configuration_page_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/img/security_configuration_page_v13_2.png b/doc/user/application_security/img/security_configuration_page_v13_2.png Binary files differnew file mode 100644 index 00000000000..016328948cc --- /dev/null +++ b/doc/user/application_security/img/security_configuration_page_v13_2.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 49580f494a2..3aca4c59423 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -116,6 +116,44 @@ information with several options:  +### View details of a DAST vulnerability + +Vulnerabilities detected by DAST occur in the live web application. Rectification of these types of +vulnerabilities requires specific information. DAST provides the information required to +investigate and rectify the underlying cause. + +To view details of DAST vulnerabilities: + +1. To see all vulnerabilities detected: + + - In a project, go to the project's **{shield}** **Security & Compliance** page. + - Only in a merge request, go the merge request's **Security** tab. + +1. Click on the vulnerability's description. The following details are provided: + + | Field | Description | +|:-----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Description | Description of the vulnerability. | +| Project | Namespace and project in which the vulnerability was detected. | +| Method | HTTP method used to detect the vulnerability. | +| URL | URL at which the vulnerability was detected. | +| Request Headers | Headers of the request. | +| Response Status | Response status received from the application. | +| Response Headers | Headers of the response received from the application. | +| Evidence | Evidence of the data found that verified the vulnerability. Often a snippet of the request or response, this can be used to help verify that the finding is a vulnerability. | +| Identifiers | Identifiers of the vulnerability. | +| Severity | Severity of the vulnerability. | +| Scanner Type | Type of vulnerability report. | +| Links | Links to further details of the detected vulnerability. | +| Solution | Details of a recommended solution to the vulnerability (optional). | + +#### Hide sensitive information in headers + +HTTP request and response headers may contain sensitive information, including cookies and +authorization credentials. By default, content of specific headers are masked in DAST vulnerability +reports. You can specify the list of all headers to be masked. For details, see +[Hide sensitive information](dast/index.md#hide-sensitive-information). + ### Dismissing a vulnerability To dismiss a vulnerability, you must set its status to Dismissed. Follow these steps to do so: @@ -258,14 +296,16 @@ An approval is optional when a security report: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. -To enable License Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium) -must be created with the case-sensitive name `License-Check`. This approval group must be set -with the number of approvals required greater than zero. +`License-Check` is an approval rule you can enable to allow an individual or group to approve a +merge request that contains a `denied` license. + +You can enable `License-Check` one of two ways: -Once this group is added to your project, the approval rule is enabled for all Merge Requests. To -configure how this rule behaves, you can choose which licenses to `allow` or `deny` in the -[project policies for License Compliance](../compliance/license_compliance/index.md#project-policies-for-license-compliance) -section. +- Create a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium) + with the case-sensitive name `License-Check`. +- Create an approval group in the [project policies section for License Compliance](../compliance/license_compliance/index.md#policies). + You must set this approval group's number of approvals required to greater than zero. Once you + enable this group in your project, the approval rule is enabled for all merge requests. Any code changes cause the approvals required to reset. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 0aa20bf4373..214044ad783 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -32,7 +32,6 @@ SAST supports the following official analyzers: - [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) (Security Code Scan (.NET)) - [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix)) - [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)) -- [`tslint`](https://gitlab.com/gitlab-org/security-products/analyzers/tslint) (TSLint (TypeScript)) The analyzers are published as Docker images that SAST will use to launch dedicated containers for each analysis. @@ -145,24 +144,24 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) ## Analyzers Data -| Property \ Tool | Apex | Bandit | Brakeman | ESLint security | Find Sec Bugs | Flawfinder | Gosec | Kubesec Scanner | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Sobelow | TSLint Security | -| --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :----------------: | :-------------: | -| Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | ✓ | -| Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Description | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | -| File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Start line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | ✓ | -| End line | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | -| Start column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | -| End column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | -| External ID (e.g. CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| URLs | ✓ | 𐄂 | ✓ | 𐄂 | ⚠ | 𐄂 | ⚠ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | 𐄂 | -| Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Affected item (e.g. class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | 𐄂 | -| Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | +| Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | NodeJsScan | PHP CS Security Audit | Security code Scan (.NET) | Sobelow | +| --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :----------------: | +| Severity | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | +| Title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Description | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | +| File | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Start line | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | +| End line | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Start column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | +| End column | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| External ID (e.g. CVE) | 𐄂 | 𐄂 | ⚠ | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| URLs | ✓ | 𐄂 | ✓ | 𐄂 | ⚠ | 𐄂 | ⚠ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Internal doc/explanation | ✓ | ⚠ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | +| Solution | ✓ | 𐄂 | 𐄂 | 𐄂 | ⚠ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Affected item (e.g. class or package) | ✓ | 𐄂 | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Confidence | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | +| Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | +| Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | - ✓ => we have that data - ⚠ => we have that data but it's partially reliable, or we need to extract it from unstructured content diff --git a/doc/user/application_security/sast/img/sast_v13_0.png b/doc/user/application_security/sast/img/sast_v13_0.png Binary files differdeleted file mode 100644 index b4aea6ea466..00000000000 --- a/doc/user/application_security/sast/img/sast_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/sast/img/sast_v13_2.png b/doc/user/application_security/sast/img/sast_v13_2.png Binary files differnew file mode 100644 index 00000000000..5697ed9beb0 --- /dev/null +++ b/doc/user/application_security/sast/img/sast_v13_2.png diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index a5497e3d38c..70d4b513cf9 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -9,9 +9,9 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. -NOTE: **4 of the top 6 attacks were application based.** -Download our whitepaper, -["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) +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. ## Overview @@ -28,7 +28,7 @@ You can take advantage of SAST by doing one of the following: GitLab checks the SAST report, compares the found vulnerabilities between the source and target branches, and shows the information right on the merge request. - + The results are sorted by the priority of the vulnerability: @@ -58,7 +58,8 @@ If you're using the shared Runners on GitLab.com, this is enabled by default. Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [enabled Docker-in-Docker for SAST](#enabling-docker-in-docker). -CAUTION: **Caution:** Our SAST jobs currently expect a Linux container type. Windows containers are not yet supported. +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 the Docker version installed @@ -70,31 +71,54 @@ The following table shows which languages, package managers and frameworks are s | Language (package managers) / framework | Scan tool | Introduced in GitLab Version | |-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------| -| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | -| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.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 | -| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | -| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10 | -| Go | [Gosec](https://github.com/securego/gosec) | 10.7 | -| Groovy ([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.3 (Gradle) & 11.9 (Ant, Maven, SBT) | -| Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | +| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | +| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.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 | +| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | +| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10 | +| Go | [Gosec](https://github.com/securego/gosec) | 10.7 | +| Groovy ([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.3 (Gradle) & 11.9 (Ant, Maven, SBT) | +| Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | | Java ([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 | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | -| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | +| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8, moved to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2 | | Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6 | | Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1 | | PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | | Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | | React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | -| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | +| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3, moved to [GitLab Core](https://about.gitlab.com/pricing/) in 13.1 | | 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 | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, merged with ESLint in 13.2 | NOTE: **Note:** The Java analyzers can also be used for variants like the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), [Grails](https://grails.org/) and the [Maven wrapper](https://github.com/takari/maven-wrapper). +### Making SAST analyzers available to all GitLab tiers + +All open source (OSS) analyzers are in the process of being reviewed and potentially moved to the GitLab Core tier. Progress can be +tracked in the corresponding +[epic](https://gitlab.com/groups/gitlab-org/-/epics/2098). + +Please note that support for [Docker-in-Docker](#enabling-docker-in-docker) +will not be extended to the GitLab Core tier. + +#### Summary of features per tier + +Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), +as shown in the following table: + +| Capability | In Core | In Ultimate | +|:--------------------------------------------------------------------------|:--------------------|:-------------------| +| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | +| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](#security-dashboard) | **{dotted-circle}** | **{check-circle}** | + ## Contribute your scanner The [Security Scanner Integration](../../../development/integrations/secure.md) documentation explains how to integrate other security scanners into GitLab. @@ -222,7 +246,7 @@ 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` flag can be provided to the +If all dependencies are present, the `COMPILE=false` variable can be provided to the analyzer and compilation will be skipped: ```yaml @@ -247,10 +271,9 @@ build: spotbugs-sast: dependencies: - build - script: - - /analyzer run -compile=false variables: MAVEN_REPO_PATH: ./.m2/repository + COMPILE: false artifacts: reports: sast: gl-sast-report.json @@ -266,6 +289,16 @@ See [Analyzer settings](#analyzer-settings) for the complete list of available o SAST can be [configured](#customizing-the-sast-settings) using environment variables. +#### Logging Level + +You can control the verbosity of logs by setting the `SECURE_LOG_LEVEL` env var. The default is set to `info`, you can set it to any of the following levels: + +- `fatal` +- `error` +- `warn` +- `info` +- `debug` + #### Custom Certificate Authority To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle @@ -278,7 +311,6 @@ The following are Docker image-related variables. | Environment variable | Description | |------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | -| `SAST_ANALYZER_IMAGE_PREFIX` | **DEPRECATED**: Use `SECURE_ANALYZERS_PREFIX` instead. | | `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | | `SAST_DEFAULT_ANALYZERS` | Override the names of default images. Read more about [customizing analyzers](analyzers.md). | | `SAST_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker). This variable is `true` by default. | @@ -287,17 +319,18 @@ The following are Docker image-related variables. Some analyzers make it possible to filter out vulnerabilities under a given threshold. -| Environment variable | Default value | Description | -|-------------------------|---------------|-------------| +| 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. | -| `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/*'` | -| `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_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_DISABLE_BABEL` | `false` | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. | +| `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. | #### Docker-in-Docker orchestrator @@ -315,11 +348,12 @@ The following variables configure the Docker-in-Docker orchestrator, and therefo Some analyzers can be customized with environment variables. -| Environment variable | Analyzer | Description | -|-----------------------------|----------|-------------| +| 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` will use 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_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. | | `ANT_PATH` | SpotBugs | Path to the `ant` executable. | | `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. | @@ -333,6 +367,7 @@ Some analyzers can be customized with environment variables. | `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | | `SAST_GOSEC_CONFIG` | Gosec | Path to configuration for Gosec (optional). | | `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | +| `SEARCH_MAX_DEPTH` | any | Maximum number of directories traversed when searching for source code files. Default: `4`. | #### Custom environment variables @@ -494,7 +529,6 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:2 registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2 registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2 registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/tslint:2 ``` The process for importing Docker images into a local offline Docker registry depends on @@ -509,7 +543,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc ### Set SAST CI job variables to use local SAST analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must replace -`SAST_ANALYZER_IMAGE_PREFIX` to refer to your local Docker container registry: +`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: ```yaml include: diff --git a/doc/user/application_security/secret_detection/img/secret-detection-merge-request-ui.png b/doc/user/application_security/secret_detection/img/secret-detection-merge-request-ui.png Binary files differdeleted file mode 100644 index 17893610f10..00000000000 --- a/doc/user/application_security/secret_detection/img/secret-detection-merge-request-ui.png +++ /dev/null diff --git a/doc/user/application_security/secret_detection/img/secret_detection_v13_2.png b/doc/user/application_security/secret_detection/img/secret_detection_v13_2.png Binary files differnew file mode 100644 index 00000000000..4aa7dd83c8d --- /dev/null +++ b/doc/user/application_security/secret_detection/img/secret_detection_v13_2.png diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 85933c31a34..ea635212c5d 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -25,7 +25,7 @@ GitLab displays identified secrets as part of the SAST reports visibly in a few - Pipelines' **Security** tab - Report in the merge request widget - + ## Use cases @@ -39,7 +39,8 @@ To run Secret Detection 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:** Our Secret Detection jobs currently expect a Linux container type. Windows containers are not yet supported. +CAUTION: **Caution:** +Our Secret Detection jobs currently expect a Linux container type. Windows containers are not yet supported. CAUTION: **Caution:** If you use your own Runners, make sure the Docker version installed @@ -118,15 +119,15 @@ declare a job with the same name as the SAST job to override. Place this new job inclusion and specify any additional keys under it. In the following example, we include the Secret Detection template and at the same time we -override the `secret-scan` job with the `SECRET_DETECTION_HISTORIC_SCAN` variable to `true`: +override the `secret_detection` job with the `SECRET_DETECTION_HISTORIC_SCAN` variable to `true`: ```yaml include: - template: Secret-Detection.gitlab-ci.yml -secrets-scan: +secret_detection: variables: - SECRET_DETECTION_HISTORIC_SCAN: true + SECRET_DETECTION_HISTORIC_SCAN: "true" ``` Because the template is [evaluated before](../../../ci/yaml/README.md#include) @@ -146,6 +147,16 @@ Secret Detection can be customized by defining available variables: | `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | +### Logging Level + +You can control the verbosity of logs by setting the `SECURE_LOG_LEVEL` env var. The default is set to `info`, you can set it to any of the following levels: + +- `fatal` +- `error` +- `warn` +- `info` +- `debug` + ## Full History Secret Scan GitLab 12.11 introduced support for scanning the full history of a repository. This new functionality diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png Binary files differindex 0dfe7b637cd..d98fb71ae37 100644 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_0.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_0.png Binary files differdeleted file mode 100644 index 4c7b5cc724f..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_2_noNav.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_2_noNav.png Binary files differnew file mode 100644 index 00000000000..d6cfc2de980 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_2_noNav.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_0.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_0.png Binary files differdeleted file mode 100644 index a500f186c2b..00000000000 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_0.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_2_sm.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_2_sm.png Binary files differnew file mode 100644 index 00000000000..75b5ad1d885 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v13_2_sm.png diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v12_6.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v12_6.png Binary files differdeleted file mode 100644 index 670c90d10a3..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v12_6.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_2.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_2.png Binary files differnew file mode 100644 index 00000000000..591a08f4d7a --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v13_2.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_2.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_2.png Binary files differnew file mode 100644 index 00000000000..7cab7b0a61f --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_2.png diff --git a/doc/user/application_security/security_dashboard/img/standalone_vulnerability_page_v13_1.png b/doc/user/application_security/security_dashboard/img/standalone_vulnerability_page_v13_1.png Binary files differnew file mode 100644 index 00000000000..9cf95b197fe --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/standalone_vulnerability_page_v13_1.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_1.png b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_1.png Binary files differnew file mode 100644 index 00000000000..2b792727a99 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_1.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 60798b9c921..9a13d143d1f 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -1,5 +1,8 @@ --- type: reference, howto +stage: Secure +group: Threat Insights +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 --- # GitLab Security Dashboard **(ULTIMATE)** @@ -9,7 +12,7 @@ vulnerabilities in your groups, projects and pipelines. You can also drill down into a vulnerability and get extra information, see which project it comes from, the file it's in, and various metadata to help you analyze -the risk. You can also action these vulnerabilities by creating an issue for them, +the risk. You can also take actions on vulnerabilities by creating an issue for them, or by dismissing them. To benefit from the Security Dashboard you must first configure one of the @@ -42,7 +45,7 @@ At the pipeline level, the Security section displays the vulnerabilities present Visit the page for any pipeline which has run any of the [supported reports](#supported-reports). Click the **Security** tab to view the Security findings. - + 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. @@ -51,56 +54,52 @@ A pipeline consists of multiple jobs, including SAST and DAST scanning. If any j > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. -At the project level, the Security Dashboard displays the latest security reports for your project. -Use it to find and fix vulnerabilities. +At the project level, the Security Dashboard displays the vulnerabilities merged into your project's +[default branch](../../project/repository/branches/index.md#default-branch). Access it by navigating +to **Security & Compliance > Security Dashboard**. - +The Security Dashboard first displays the total number of vulnerabilities by severity (for example, +Critical, High, Medium, Low). Below this, a table displays each vulnerability's status, severity, +and description. Clicking a vulnerability takes you to its [Vulnerability Details](../vulnerabilities) +page to view more information about that vulnerability. -### Export vulnerabilities +You can filter the vulnerabilities by: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197494) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. +- Status +- Severity +- Report type -You can export all your project's vulnerabilities as CSV by clicking on the export button located at top right of the Project Security Dashboard. This will initiate the process, and once complete, the CSV report will be downloaded. The report will contain all vulnerabilities in the project as filters won't apply. +You can also dismiss vulnerabilities in the table: -NOTE: **Note:** -It may take several minutes for the download to start if your project consists -of thousands of vulnerabilities. Do not close the page until the download finishes. +1. Select the checkbox for each vulnerability you want to dismiss. +1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. - + ## Group Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. -The group Security Dashboard gives an overview of the vulnerabilities of all the -projects in a group and its subgroups. +The group Security Dashboard gives an overview of the vulnerabilities in the default branches of the +projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** +for your group. -First, navigate to the Security Dashboard found under your group's -**Security** tab. +NOTE: **Note:** +The Security Dashboard only shows projects with [security reports](#supported-reports) enabled in a +group. + + -Once you're on the dashboard, at the top you should see a series of filters for: +You can filter which vulnerabilities the Security Dashboard displays by: - Status - Severity - Report type +- Project -NOTE: **Note:** -The dashboard only shows projects with [security reports](#supported-reports) enabled in a group. - - - -Selecting one or more filters will filter the results in this page. - -The main section is a list of all the vulnerabilities in the group, sorted by severity. -In that list, you can see the severity of the vulnerability, its name, its -confidence (likelihood of the vulnerability to be a positive one), and the project -it's from. - -If you hover over a row, the following actions appear: - -- More info -- Create issue -- Dismiss vulnerability +A table lists the vulnerabilities, sorted by severity. The table shows each vulnerability's status, +severity, and description. Clicking a vulnerability takes you to its [Vulnerability Details](../vulnerabilities) +page to view more information about that vulnerability. Next to the list is a timeline chart that shows how many open vulnerabilities your projects had at various points in time. You can filter among 30, 60, and @@ -120,28 +119,14 @@ vulnerabilities are not included either. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). -### Export vulnerabilities - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213013) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. - -You can export all your vulnerabilities as CSV by clicking the **{upload}** **Export** button -located at the top right of the **Group Security Dashboard**. After the report builds, the CSV -report downloads to your local machine. The report contains all vulnerabilities for the projects -defined in the **Group Security Dashboard**, as filters don't apply to the export function. - -NOTE: **Note:** -It may take several minutes for the download to start if your project contains thousands of -vulnerabilities. Don't close the page until the download finishes. - - - ## Instance Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6953) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8. -At the instance level, the Security Dashboard displays the vulnerabilities -present in all of the projects that you have added to it. It includes all -of the features of the [group security dashboard](#group-security-dashboard). +At the instance level, the Security Dashboard displays the vulnerabilities present in the default +branches of all the projects you configure to display on the dashboard. It includes all the +[group Security Dashboard's](#group-security-dashboard) +features. You can access the Instance Security Dashboard from the menu bar at the top of the page. Under **More**, select **Security**. @@ -156,27 +141,25 @@ To add projects to the dashboard: 1. Search for and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. -Once added, the dashboard will display the vulnerabilities found in your chosen -projects. +Once added, the Security Dashboard displays the vulnerabilities found in your chosen projects' +default branches. - + -### Export vulnerabilities +## Export vulnerabilities -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -You can export all your vulnerabilities as CSV by clicking the **{upload}** **Export** -button located at top right of the **Instance Security Dashboard**. After the report +You can export all your vulnerabilities in CSV format by clicking the **{upload}** **Export** +button located at top right of the **Security Dashboard**. After the report is built, the CSV report downloads to your local machine. The report contains all -vulnerabilities for the projects defined in the **Instance Security Dashboard**, +vulnerabilities for the projects defined in the **Security Dashboard**, as filters don't apply to the export function. NOTE: **Note:** It may take several minutes for the download to start if your project contains thousands of vulnerabilities. Do not close the page until the download finishes. - - ## Keeping the dashboards up to date The Security Dashboard displays information from the results of the most recent @@ -194,12 +177,34 @@ Dashboard regardless of how often the default branch is updated. That way, reports are created even if no code change happens. +CAUTION: **Warning:** +Running Dependency Scanning from a scheduled pipeline might result in false negatives if your +project doesn't have a lock file and isn't configured for Continuous Delivery. A lock file is a file +that lists all transient dependencies and keeps track of their exact versions. The false negative +can occur because the dependency version resolved during the scan might differ from the ones +resolved when your project was built and released, in a previous pipeline. Java projects can't have +lock files. Python projects can have lock files, but GitLab Secure tools don't support them. + ## Security scans using Auto DevOps When using [Auto DevOps](../../../topics/autodevops/index.md), use [special environment variables](../../../topics/autodevops/customize.md#environment-variables) to configure daily security scans. +## Vulnerability list + +Each dashboard's vulnerability list contains vulnerabilities from the latest scans that were merged +into the default branch. +Click any vulnerability in the table to see more information on that vulnerability. To create an +issue associated with the vulnerability, click the **Create Issue** button. + + + +Once you create the issue, the vulnerability list contains a link to the issue and an icon whose +color indicates the issue's status (green for open issues, blue for closed issues). + + + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 434048896fe..a6738677454 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -58,12 +58,15 @@ prerequisites: If you're using custom Helm values for Cilium, you must enable Hubble with flow metrics for each namespace by adding the following lines to -your [Hubble values](../../clusters/applications.md#install-cilium-using-gitlab-cicd): +your [Cilium values](../../clusters/applications.md#install-cilium-using-gitlab-cicd): ```yaml -metrics: - enabled: - - 'flow:sourceContext=namespace;destinationContext=namespace' +global: + hubble: + enabled: true + metrics: + enabled: + - 'flow:sourceContext=namespace;destinationContext=namespace' ``` The **Container Network Policy** section displays the following information diff --git a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v12_10.png b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v12_10.png Binary files differdeleted file mode 100644 index 0fdb8d1e201..00000000000 --- a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v12_10.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v13_1.png b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v13_1.png Binary files differnew file mode 100644 index 00000000000..e0e0fdb6f6e --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v13_1.png diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index b3128e49980..d5cce6434d8 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Secure -group: Vulnerability Research +group: Threat Insights 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 --- @@ -9,10 +9,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -Each security vulnerability in the [Vulnerability List](../dependency_list/index.md) has its own standalone +Each security vulnerability in the [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has its own standalone page. - + On the standalone vulnerability page, you can interact with the vulnerability in several different ways: @@ -30,7 +30,7 @@ several different ways: You can switch the status of a vulnerability using the **Status** dropdown to one of the following values: -| State | Description | +| Status | Description | |-----------|-------------------------------------------------------------------| | Detected | The default state for a newly discovered vulnerability | | Confirmed | A user has seen this vulnerability and confirmed it to be real | |
