diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-10-21 07:08:36 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-10-21 07:08:36 +0000 |
| commit | 48aff82709769b098321c738f3444b9bdaa694c6 (patch) | |
| tree | e00c7c43e2d9b603a5a6af576b1685e400410dee /doc/user/application_security | |
| parent | 879f5329ee916a948223f8f43d77fba4da6cd028 (diff) | |
| download | gitlab-ce-48aff82709769b098321c738f3444b9bdaa694c6.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-5-stable-eev13.5.0-rc42
Diffstat (limited to 'doc/user/application_security')
33 files changed, 590 insertions, 315 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index ae22655e30b..145422f8736 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -8,8 +8,8 @@ type: reference, howto # Web API Fuzz Testing **(ULTIMATE)** You can add web API fuzzing to your [GitLab CI/CD](../../../ci/README.md) -pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. -API fuzzing performs fuzz testing of API operation parameters. +pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. +API fuzzing performs fuzz testing of API operation parameters. Fuzz testing sets operation parameters to unexpected values in an effort to cause unexpected behavior and errors in the API backend. We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s @@ -443,7 +443,7 @@ Example usage for setting a single header: ```json { "headers": { - "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" } } ``` @@ -453,7 +453,7 @@ Example usage for setting both a header and cookie: ```json { "headers": { - "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" + "Authorization": "Bearer dXNlcm5hbWU6cGFzc3dvcmQ=" }, "cookies": { "flags": "677" diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index a6ad701360e..ead34ca227e 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -19,8 +19,9 @@ then in the left sidebar go to **Security & Compliance > Configuration**. For each security control the page displays: -- **Status** - Status of the security control: enabled, not enabled, or available. -- **Manage** - A management option or a link to the documentation. +- **Security Control:** Name, description, and a documentation link. +- **Status:** The security control's status (enabled, not enabled, or available). +- **Manage:** A management option or a documentation link. ## Status @@ -29,12 +30,11 @@ The status of each security control is determined by the project's latest defaul If a job with the expected security report artifact exists in the pipeline, the feature's status is _enabled_. -For SAST, click **View history** to see the `.gitlab-ci.yml` file’s history. - -NOTE: **Note:** If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), all security features are configured by default. +For SAST, click **View history** to see the `.gitlab-ci.yml` file's history. + ## Manage You can configure the following security controls: diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 880e5a3875a..9e7f98dd4fc 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,8 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -## Overview - Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra job in your pipeline that scans for those vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based apps. @@ -19,7 +17,6 @@ By default, container scanning in GitLab is based on [Clair](https://github.com/ containers. [GitLab's Klar analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) scans the containers and serves as a wrapper for Clair. -NOTE: **Note:** To integrate security scanners other than Clair and Klar into GitLab, see [Security scanner integration](../../../development/integrations/secure.md). @@ -46,7 +43,7 @@ To enable container scanning in your pipeline, you need the following: or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. -- [Build and push](../../packages/container_registry/index.md#container-registry-examples-with-gitlab-cicd) +- [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) your Docker image to your project's container registry. The name of the Docker image should use the following [predefined environment variables](../../../ci/variables/predefined_variables.md): @@ -65,7 +62,7 @@ To enable container scanning in your pipeline, you need the following: variables: IMAGE_TAG: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - docker build -t $IMAGE_TAG . - docker push $IMAGE_TAG ``` @@ -119,7 +116,7 @@ build: IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA script: - docker info - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - docker build -t $IMAGE . - docker push $IMAGE @@ -219,14 +216,21 @@ To use container scanning in an offline environment, you need: - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - To configure a local Docker container registry with copies of the container scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/klar) images, found in the [container scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry). -NOTE: **Note:** -GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. +##### Support for Custom Certificate Authorities + +Support for custom certificate authorities was introduced in the following versions: + +| Analyzer | Version | +| -------- | ------- | +| `klar` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/releases/v2.3.0) | + #### Make GitLab container scanning analyzer images available inside your Docker registry For container scanning, import the following default images from `registry.gitlab.com` into your @@ -287,7 +291,7 @@ build_latest_vulnerabilities: script: - docker pull arminc/clair-db:latest - docker tag arminc/clair-db:latest $CI_REGISTRY/namespace/clair-vulnerabilities-db - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - docker push $CI_REGISTRY/namespace/clair-vulnerabilities-db ``` @@ -433,3 +437,7 @@ This is a result of a bug in Docker which is now [fixed](https://github.com/cont To prevent the error, ensure the Docker version that the runner is using is `18.09.03` or higher. For more information, see [issue #10241](https://gitlab.com/gitlab-org/gitlab/-/issues/10241 "Investigate why Container Scanning is not working with NFS mounts"). + +### Getting warning message `gl-container-scanning-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index dff71cb9445..9508407ccae 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -175,6 +175,52 @@ To use coverage fuzzing in an offline environment, follow these steps: `NEW_URL_GITLAB_COV_FUZ` is the URL of the private `gitlab-cov-fuzz` clone that you set up in the first step. +### Continuous fuzzing (long-running async fuzzing jobs) + +It's also possible to run the fuzzing jobs longer and without blocking your main pipeline. This +configuration uses the GitLab [parent-child pipelines](../../../ci/parent_child_pipelines.md). +The full example is available in the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing#running-go-fuzz-from-ci). +This example uses Go, but is applicable for any other supported languages. + +The suggested workflow in this scenario is to have long-running, async fuzzing jobs on a +main/development branch, and short, blocking sync fuzzing jobs on all other branches and MRs. This +is a good way to balance the needs of letting a developer's per-commit pipeline complete quickly, +and also giving the fuzzer a large amount of time to fully explore and test the app. + +Long-running fuzzing jobs are usually necessary for the coverage guided fuzzer to find deeper bugs +in your latest code base. THe following is an example of what `.gitlab-ci.yml` looks like in this +workflow (for the full example, see the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing)): + +```yaml + +sync_fuzzing: + variables: + COVFUZZ_ADDITIONAL_ARGS: '-max_total_time=300' + trigger: + include: .covfuzz-ci.yml + strategy: depend + rules: + - if: $CI_COMMIT_BRANCH != 'continuous_fuzzing' && $CI_PIPELINE_SOURCE != 'merge_request_event' + +async_fuzzing: + variables: + COVFUZZ_ADDITIONAL_ARGS: '-max_total_time=3600' + trigger: + include: .covfuzz-ci.yml + rules: + - if: $CI_COMMIT_BRANCH == 'continuous_fuzzing' && $CI_PIPELINE_SOURCE != 'merge_request_event' +``` + +This essentially creates two steps: + +1. `sync_fuzzing`: Runs all your fuzz targets for a short period of time in a blocking + configuration. This finds simple bugs and allows you to be confident that your MRs aren't + introducing new bugs or causing old bugs to reappear. +1. `async_fuzzing`: Runs on your branch and finds deep bugs in your code without blocking your + development cycle and MRs. + +The `covfuzz-ci.yml` is the same as that in the [original synchronous example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example#running-go-fuzz-from-ci). + ### Glossary - Seed corpus: The set of test cases given as initial input to the fuzz target. This usually speeds 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 differdeleted file mode 100644 index bbf7944eb40..00000000000 --- a/doc/user/application_security/dast/img/dast_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/dast/img/dast_v13_4.png b/doc/user/application_security/dast/img/dast_v13_4.png Binary files differnew file mode 100644 index 00000000000..d9c1d1b5c66 --- /dev/null +++ b/doc/user/application_security/dast/img/dast_v13_4.png diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 73a8e727389..fffaf4ad26b 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -9,17 +9,17 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -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 vulnerabilities that can put the security of your code at risk. Yet, once deployed, your application is exposed to a new category of possible attacks, such as cross-site scripting or broken authentication flaws. This is where Dynamic Application Security Testing (DAST) comes into place. +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 If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web applications @@ -32,11 +32,10 @@ provided by [Auto DevOps](../../../topics/autodevops/index.md). GitLab checks the DAST report, compares the found vulnerabilities between the source and target branches, and shows the information on the merge request. -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. +Note that 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. @@ -53,12 +52,11 @@ However, DAST can be [configured](#full-scan) to also perform an *active scan*: attack your application and produce a more extensive security report. It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md). -NOTE: **Note:** -A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any -job fails to finish for any reason, the security dashboard doesn't show DAST scanner -output. For example, if the DAST job finishes but the SAST job fails, the security -dashboard doesn't show DAST results. The analyzer outputs an -[exit code](../../../development/integrations/secure.md#exit-code) on failure. +Note that a pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job +fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For +example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST +results. On failure, the analyzer outputs an +[exit code](../../../development/integrations/secure.md#exit-code). ## Use cases @@ -206,8 +204,8 @@ variables: DAST_FULL_SCAN_ENABLED: "true" ``` -NOTE: **Note:** -If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). +If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some +tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). #### Domain validation @@ -398,11 +396,9 @@ variables: DAST_API_HOST_OVERRIDE: api-test.host.com ``` -NOTE: **Note:** -Using a host override is ONLY supported when importing the API -specification from a URL. It does not work and will be ignored when importing -the specification from a file. This is due to a limitation in the ZAP OpenAPI -extension. +Note that using a host override is ONLY supported when importing the API specification from a URL. +It doesn't work and is ignored when importing the specification from a file. This is due to a +limitation in the ZAP OpenAPI extension. #### Authentication using headers @@ -427,7 +423,8 @@ A URL scan allows you to specify which parts of a website are scanned by DAST. #### Define the URLs to scan -To specify the paths to be scanned, add a comma-separated list of the paths to the `DAST_PATHS` environment variable. Note that you can only scan paths of a single host. +To specify the paths to scan, add a comma-separated list of the paths to the `DAST_PATHS` +environment variable. Note that you can only scan paths of a single host. ```yaml include: @@ -437,8 +434,10 @@ variables: DAST_PATHS=/page1.html,/category1/page1.html,/page3.html ``` -NOTE: **Note:** -`DAST_AUTH_EXCLUDE_URLS` are ignored when `DAST_PATHS` is set. +When using `DAST_PATHS`, note the following: + +- The `DAST_PATHS` environment variable has a limit of about 130kb. If you have a list or paths + greater than this, you should create multiple DAST jobs and split the paths over each job. #### Full Scan @@ -590,8 +589,7 @@ To use DAST in an offline environment, you need: [container image](https://gitlab.com/gitlab-org/security-products/dast), found in the [DAST container registry](https://gitlab.com/gitlab-org/security-products/dast/container_registry). -NOTE: **Note:** -GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we @@ -672,11 +670,6 @@ To delete an existing site profile: ## Scanner profile > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222767) in GitLab 13.4. -> - [Deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - Enabled on GitLab.com. -> - Can be enabled or disabled per-project. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can [disable this feature](#enable-or-disable-dast-scanner-profiles). A scanner profile defines the scanner settings used to run an on-demand scan: @@ -684,6 +677,11 @@ A scanner profile defines the scanner settings used to run an on-demand scan: - **Spider timeout:** The maximum number of minutes allowed for the spider to traverse the site. - **Target timeout:** The maximum number of seconds DAST waits for the site to be available before starting the scan. +- **Scan mode:** A passive scan monitors all HTTP messages (requests and responses) sent to the target. An active scan attacks the target to find potential vulnerabilities. +- **AJAX spider:** Run the AJAX spider, in addition to the traditional spider, to crawl the target site. +- **Debug messages:** Include debug messages in the DAST console output. + +Scan mode, AJAX spider, Debug messages are [added in GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/225804) ### Create a scanner profile @@ -711,29 +709,6 @@ To delete a scanner profile: 1. Click **Manage** in the **DAST Profiles** row. 1. Click **{remove}** in the scanner profile's row. -### Enable or disable DAST scanner profiles - -The scanner profile feature is ready for production use. It's deployed behind a feature flag that -is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can opt to disable it. - -To disable it: - -```ruby -# Instance-wide -Feature.disable(:security_on_demand_scans_scanner_profiles) -# or by project -Feature.disable(:security_on_demand_scans_scanner_profiles, Project.find(<project id>)) -``` - -To enable it: - -```ruby -# Instance-wide -Feature.enable(:security_on_demand_scans_scanner_profiles) -# or by project -Feature.enable(:security_on_demand_scans_scanner_profiles, Project.find(<project ID>)) -``` - ## On-demand scans > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. @@ -756,7 +731,8 @@ An on-demand DAST scan: NOTE: **Note:** You must have permission to run an on-demand DAST scan against a protected branch. -The default branch is automatically protected. For more details, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). +The default branch is automatically protected. For more information, see +[Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). To run an on-demand DAST scan, you need: @@ -765,8 +741,8 @@ To run an on-demand DAST scan, you need: 1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. 1. Click **Create new DAST scan**. -1. In **Scanner settings**, select a scanner profile from the dropdown. -1. In **Site profiles**, select a site profile from the dropdown. +1. In **Scanner profile**, select a scanner profile from the dropdown. +1. In **Site profile**, select a site profile from the dropdown. 1. Click **Run scan**. The on-demand DAST scan runs and the project's dashboard shows the results. @@ -866,7 +842,7 @@ include: template: DAST.gitlab-ci.yml variables: - DAST_INCLUDE_ALPHA_VULNERABILITIES: true + DAST_INCLUDE_ALPHA_VULNERABILITIES: "true" ``` ## Interacting with the vulnerabilities @@ -923,6 +899,10 @@ Change the number after `-Xmx` to the required memory amount. If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). +### Getting warning message `gl-dast-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 5cce336d04c..b90bb37c60f 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -9,25 +9,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. -Dependency Scanning helps to find security vulnerabilities in your dependencies automatically -while you're developing and testing your applications, such as when your -application is using an external (open source) library that is known to be vulnerable. +GitLab's Dependency Scanning feature can automatically find security vulnerabilities in your +dependencies while you're developing and testing your applications. For example, dependency scanning +lets you know if your application uses an external (open source) library that is known to be +vulnerable. You can then take action to protect your application. ## Overview -If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your dependencies for known -vulnerabilities using Dependency Scanning. -All dependencies are scanned, including the transitive dependencies (also known as nested dependencies). -You can take advantage of Dependency Scanning by either [including the Dependency Scanning template](#configuration) -in your existing `.gitlab-ci.yml` file or by implicitly using -the [Auto Dependency Scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) +If you're using [GitLab CI/CD](../../../ci/README.md), you can use dependency scanning to analyze +your dependencies for known vulnerabilities. GitLab scans all dependencies, including transitive +dependencies (also known as nested dependencies). You can take advantage of dependency scanning by +either [including the dependency scanning template](#configuration) +in your existing `.gitlab-ci.yml` file, or by implicitly using +the [auto dependency scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning) provided by [Auto DevOps](../../../topics/autodevops/index.md). -GitLab checks the Dependency Scanning report, compares the found vulnerabilities +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: @@ -40,7 +41,7 @@ The results are sorted by the severity of the vulnerability: ## Requirements -To run Dependency Scanning jobs, by default, you need GitLab Runner with the +To run dependency scanning 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. If you're using the shared runners on GitLab.com, this is enabled by default. @@ -56,24 +57,25 @@ The current detection logic limits the maximum search depth to two levels. For e The following languages and dependency managers are supported: -| Language (package managers) | Supported files | Scan tool(s) | -|----------------------------- | --------------- | ------------ | -| C# .NET ([NuGet](https://www.nuget.org/) 4.9+) | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| C/C++ ([Conan](https://conan.io/)) | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| 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://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) | -| Ruby ([Bundler](https://bundler.io/)) | `Gemfile.lock`, `gems.locked` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | -| Scala ([sbt](https://www.scala-sbt.org/)) | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| Package Managers | Languages | Supported files | Scan tools | +| ------------------- | --------- | --------------- | ------------ | +| [Bundler](https://bundler.io/) | Ruby | `Gemfile.lock`, `gems.locked` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | +| [Composer](https://getcomposer.org/) | PHP | `composer.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [Conan](https://conan.io/) | C, C++ | [`conan.lock`](https://docs.conan.io/en/latest/versioning/lockfiles.html) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [Golang](https://golang.org/) | Go | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | Java | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/) | JavaScript | `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/) | +| [NuGet](https://www.nuget.org/) 4.9+ | .NET, C# | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [setuptools](https://setuptools.readthedocs.io/en/latest/), [pip](https://pip.pypa.io/en/stable/), [Pipenv](https://pipenv.pypa.io/en/latest/) | Python | `setup.py`, `requirements.txt`, `requirements.pip`, `requires.txt`, `Pipfile` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| [sbt](https://www.scala-sbt.org/) 1.2 and below ([Ivy](http://ant.apache.org/ivy/)) | Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | Plans are underway for supporting the following languages, dependency managers, and dependency files. For details, see the issue link for each. -| Language (package managers) | Supported files | Scan tool(s) | Issue | -|----------------------------- | --------------- | ------------ | ----- | -| 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) | +| Package Managers | Languages | Supported files | Scan tools | +| ------------------- | --------- | --------------- | ------------ | +| [Pipenv](https://pipenv.pypa.io/en/latest/) | Python | `Pipfile.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#11756](https://gitlab.com/gitlab-org/gitlab/-/issues/11756) | +| [Poetry](https://python-poetry.org/) | Python | `poetry.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#7006](https://gitlab.com/gitlab-org/gitlab/-/issues/7006) | +| [sbt](https://www.scala-sbt.org/) 1.3+ ([Coursier](https://get-coursier.io/))| Scala | `build.sbt` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | [GitLab#249526](https://gitlab.com/gitlab-org/gitlab/-/issues/249526) | ## Contribute your scanner @@ -81,7 +83,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) ## Configuration -To enable Dependency Scanning for GitLab 11.9 and later, you must +To enable dependency scanning for GitLab 11.9 and later, you must [include](../../../ci/yaml/README.md#includetemplate) the [`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) that is provided as a part of your GitLab installation. @@ -95,16 +97,16 @@ include: - template: Dependency-Scanning.gitlab-ci.yml ``` -The included template creates Dependency Scanning jobs in your CI/CD +The included template creates dependency scanning jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[Dependency Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning) +[dependency scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning) that you can later download and analyze. Due to implementation limitations, we -always take the latest Dependency Scanning artifact available. +always take the latest dependency scanning artifact available. -### Customizing the Dependency Scanning settings +### Customizing the dependency scanning settings -The Dependency Scanning settings can be changed through [environment variables](#available-variables) by using the +The dependency scanning settings can be changed through [environment variables](#available-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. For example: @@ -119,7 +121,7 @@ variables: Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -### Overriding Dependency Scanning jobs +### Overriding dependency scanning jobs CAUTION: **Deprecation:** Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) @@ -141,10 +143,10 @@ gemnasium-dependency_scanning: ### Available variables -Dependency Scanning can be [configured](#customizing-the-dependency-scanning-settings) +Dependency scanning can be [configured](#customizing-the-dependency-scanning-settings) using environment variables. -#### Configuring Dependency Scanning +#### Configuring dependency scanning The following variables allow configuration of global dependency scanning settings. @@ -156,7 +158,7 @@ The following variables allow configuration of global dependency scanning settin | `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` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info` | -#### Configuring specific analyzers used by Dependency Scanning +#### Configuring specific analyzers used by dependency scanning The following variables are used for configuring specific analyzers (used for a specific language/framework). @@ -176,7 +178,7 @@ The following variables are used for configuring specific analyzers (used for a | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are 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 are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | -| `BUNDLER_AUDIT_UPDATE_DISABLED` | `bundler-audit` | `"false"` | Disable automatic updates for the `bundler-audit` analyzer. Useful if you're running Dependency Scanning in an offline, air-gapped environment.| +| `BUNDLER_AUDIT_UPDATE_DISABLED` | `bundler-audit` | `"false"` | Disable automatic updates for the `bundler-audit` analyzer. Useful if you're running dependency scanning in an offline, air-gapped environment.| | `BUNDLER_AUDIT_ADVISORY_DB_URL` | `bundler-audit` | `https://github.com/rubysec/ruby-advisory-db` | URL of the advisory database used by bundler-audit. | | `BUNDLER_AUDIT_ADVISORY_DB_REF_NAME` | `bundler-audit` | `master` | Git ref for the advisory database specified by `BUNDLER_AUDIT_ADVISORY_DB_URL`. | | `RETIREJS_JS_ADVISORY_DB` | `retire.js` | `https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/jsrepository.json` | Path or URL to `retire.js` JS vulnerability data file. Note that if the URL hosting the data file uses a custom SSL certificate, for example in an offline installation, you can pass the certificate in the `ADDITIONAL_CA_CERT_BUNDLE` environment variable. | @@ -214,16 +216,16 @@ For more information about the vulnerabilities database update, check the ## Dependency List -An additional benefit of Dependency Scanning is the ability to view your +An additional benefit of dependency scanning is the ability to view your project's dependencies and their known vulnerabilities. Read more about the [Dependency List](../dependency_list/index.md). ## Reports JSON format -The Dependency Scanning tool emits a JSON report file. For more information, see the +The dependency scanning tool emits a JSON report file. For more information, see the [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dependency-scanning-report-format.json). -Here's an example Dependency Scanning report: +Here's an example dependency scanning report: ```json-doc { @@ -342,36 +344,35 @@ You can search the [gemnasium-db](https://gitlab.com/gitlab-org/security-product to find a vulnerability in the Gemnasium database. You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). -## Running Dependency Scanning in an offline environment +## Running dependency scanning in an offline environment For self-managed GitLab instances in an environment with limited, restricted, or intermittent access -to external resources through the internet, some adjustments are required for Dependency Scanning +to external resources through the internet, some adjustments are required for dependency scanning jobs to run successfully. For more information, see [Offline environments](../offline_deployments/index.md). -### Requirements for offline Dependency Scanning +### Requirements for offline dependency scanning -Here are the requirements for using Dependency Scanning in an offline environment: +Here are the requirements for using dependency scanning in an offline environment: - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). -- Docker Container Registry with locally available copies of Dependency Scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- Docker Container Registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/). This is required because, in an offline environment, the Gemnasium analyzer can't fetch the latest advisories from the online repository. - _Only if scanning Ruby projects_: Host an offline Git copy of the [advisory database](https://github.com/rubysec/ruby-advisory-db). - _Only if scanning npm/yarn projects_: Host an offline copy of the [retire.js](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [js](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases. -NOTE: **Note:** -GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), +Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) in an offline environment if you prefer using only locally available Docker images. However, we recommend keeping the pull policy setting to `always` if not in an offline environment, as this enables the use of updated scanners in your CI/CD pipelines. -### Make GitLab Dependency Scanning analyzer images available inside your Docker registry +### Make GitLab dependency scanning analyzer images available inside your Docker registry -For Dependency Scanning with all [supported languages and frameworks](#supported-languages-and-package-managers), -import the following default Dependency Scanning analyzer images from `registry.gitlab.com` into +For dependency scanning with all [supported languages and frameworks](#supported-languages-and-package-managers), +import the following default dependency scanning analyzer images from `registry.gitlab.com` into your [local Docker container registry](../../packages/container_registry/index.md): ```plaintext @@ -392,7 +393,19 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). -### Set Dependency Scanning CI job variables to use local Dependency Scanning analyzers +#### Support for Custom Certificate Authorities + +Support for custom certificate authorities was introduced in the following versions. + +| Analyzer | Version | +| -------- | ------- | +| `gemnasium` | [v2.8.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/releases/v2.8.0) | +| `gemnasium-maven` | [v2.9.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/releases/v2.9.0) | +| `gemnasium-python` | [v2.7.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/releases/v2.7.0) | +| `retire.js` | [v2.4.0](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js/-/releases/v2.4.0) | +| `bundler-audit` | [v2.4.0](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit/-/releases/v2.4.0) | + +### Set dependency scanning CI job variables to use local dependency scanning analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must change the value of `SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry. You must also change the @@ -479,7 +492,19 @@ As a workaround, remove the [`retire.js`](analyzers.md#selecting-specific-analyz ### `Error response from daemon: error processing tar file: docker-tar: relocation error` -This error occurs when the Docker version that runs the Dependency Scanning job is `19.03.00`. +This error occurs when the Docker version that runs the dependency scanning job is `19.03.00`. Consider updating to Docker `19.03.1` or greater. Older versions are not affected. Read more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). + +### Getting warning message `gl-dependency-scanning-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + +### Limitation when using rules:exists + +The [dependency scanning CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) +uses the [`rules:exists`](../../../ci/yaml/README.md#rulesexists) +syntax. This directive is limited to 10000 checks and always returns `true` after reaching this +number. Because of this, and depending on the number of files in your repository, a dependency +scanning job might be triggered even if the scanner doesn't support your project. diff --git a/doc/user/application_security/img/cve_request_communication.png b/doc/user/application_security/img/cve_request_communication.png Binary files differindex 0766b371c11..5c58df463ef 100644 --- a/doc/user/application_security/img/cve_request_communication.png +++ b/doc/user/application_security/img/cve_request_communication.png diff --git a/doc/user/application_security/img/cve_request_communication_publication.png b/doc/user/application_security/img/cve_request_communication_publication.png Binary files differindex 9e34c217e13..9eb6f2f8d9f 100644 --- a/doc/user/application_security/img/cve_request_communication_publication.png +++ b/doc/user/application_security/img/cve_request_communication_publication.png diff --git a/doc/user/application_security/img/new_cve_request_issue.png b/doc/user/application_security/img/new_cve_request_issue.png Binary files differindex a342c73992e..6ea7ca4a2ab 100644 --- a/doc/user/application_security/img/new_cve_request_issue.png +++ b/doc/user/application_security/img/new_cve_request_issue.png diff --git a/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png b/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png Binary files differindex f497b0fbc4e..7b04988afdb 100644 --- a/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png +++ b/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png diff --git a/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png b/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png Binary files differindex fc847b578f5..b9b6dd13294 100644 --- a/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png +++ b/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png diff --git a/doc/user/application_security/img/vulnerability-check_v13_4.png b/doc/user/application_security/img/vulnerability-check_v13_4.png Binary files differindex e0b53059b45..3e38f6eebe7 100644 --- a/doc/user/application_security/img/vulnerability-check_v13_4.png +++ b/doc/user/application_security/img/vulnerability-check_v13_4.png diff --git a/doc/user/application_security/img/vulnerability_solution.png b/doc/user/application_security/img/vulnerability_solution.png Binary files differindex d86b89a5f99..63e9c1473b6 100644 --- a/doc/user/application_security/img/vulnerability_solution.png +++ b/doc/user/application_security/img/vulnerability_solution.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index d509176f2b2..413a9f894e2 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -22,10 +22,10 @@ Testing (SAST), and Secret Detection by adding the following to your `.gitlab-ci ```yaml include: - - template: Dependency-Scanning.gitlab-ci.yml - - template: License-Scanning.gitlab-ci.yml - - template: SAST.gitlab-ci.yml - - template: Secret-Detection.gitlab-ci.yml + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml ``` To add Dynamic Application Security Testing (DAST) scanning, add the following to your @@ -33,7 +33,7 @@ To add Dynamic Application Security Testing (DAST) scanning, add the following t ```yaml include: - - template: DAST.gitlab-ci.yml + - template: Security/DAST.gitlab-ci.yml variables: DAST_WEBSITE: https://staging.example.com @@ -449,7 +449,7 @@ To fix this issue, you can either: ```yaml include: - template: SAST.gitlab-ci.yml + template: Security/SAST.gitlab-ci.yml spotbugs-sast: stage: unit-tests @@ -458,6 +458,15 @@ To fix this issue, you can either: [Learn more on overriding SAST jobs](sast/index.md#overriding-sast-jobs). All the security scanning tools define their stage, so this error can occur with all of them. +### Getting warning messages `… report.json: no matching files` + +This is often followed by the [error `No files to upload`](../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload), +and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Please +check the entire job log for such messages. If you don't find these messages, retry the failed job +after setting `SECURE_LOG_LEVEL: "debug"` as a +[custom environment variable](../../ci/variables/README.md#custom-environment-variables). +This provides useful information to investigate further. + ### Getting error message `sast job: config key may not be used with 'rules': only/except` When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template @@ -490,7 +499,7 @@ would look similar to: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml # Ensure that the scanning is only executed on master or merge requests spotbugs-sast: @@ -505,7 +514,7 @@ would be written as follows: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml # Ensure that the scanning is only executed on master or merge requests spotbugs-sast: @@ -519,7 +528,7 @@ it would look similar to: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml # Ensure that the scanning is not executed on tags spotbugs-sast: @@ -531,7 +540,7 @@ To transition to the new `rules` syntax, the override would be rewritten as: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml # Ensure that the scanning is not executed on tags spotbugs-sast: diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 727f077aa09..6167c0445f9 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -25,6 +25,7 @@ SAST supports the following official analyzers: - [`flawfinder`](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) (Flawfinder) - [`gosec`](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) (Gosec) - [`kubesec`](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec) (Kubesec) +- [`mobsf`](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf) (MobSF (beta)) - [`nodejs-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) (NodeJsScan) - [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) (PHP CS security-audit) - [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) (PMD (Apex only)) @@ -53,7 +54,7 @@ In `.gitlab-ci.yml` define: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml variables: SECURE_ANALYZERS_PREFIX: my-docker-registry/gl-images @@ -70,7 +71,7 @@ In `.gitlab-ci.yml` define: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml variables: SAST_DEFAULT_ANALYZERS: "bandit,flawfinder" @@ -86,7 +87,7 @@ default analyzers. In `.gitlab-ci.yml` define: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml variables: SAST_DEFAULT_ANALYZERS: "" @@ -118,24 +119,24 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) ## Analyzers Data -| 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 | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | x | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | ✓ | -| Source code extract | 𐄂 | ✓ | ✓ | ✓ | 𐄂 | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | 𐄂 | -| Internal ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 𐄂 | 𐄂 | ✓ | ✓ | ✓ | +| Property / Tool | Apex | Bandit | Brakeman | ESLint security | SpotBugs | Flawfinder | Gosec | Kubesec Scanner | MobSF | 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 | 𐄂 | ✓ | ✓ | 𐄂 | ✓ | x | ✓ | ✓ | 𐄂 | 𐄂 | 𐄂 | 𐄂 | ✓ | +| 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/index.md b/doc/user/application_security/sast/index.md index a4fc3c9e638..9e4d4112ae8 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -11,8 +11,8 @@ type: reference, howto 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. +explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your +organization. If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known vulnerabilities using Static Application Security Testing (SAST). GitLab checks the SAST report and @@ -31,8 +31,10 @@ The results are sorted by the priority of the vulnerability: 1. Unknown 1. Everything else -NOTE: **Note:** -A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard doesn't show SAST results. The analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code) on failure. +A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish +for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST +job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, +the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). ## Use cases @@ -59,39 +61,41 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae GitLab SAST supports a variety of languages, package managers, and frameworks. Our SAST security scanners also feature automatic language detection which works even for mixed-language projects. If any supported language is detected in project source code we will automatically run the appropriate SAST analyzers. -You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). +You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). | Language (package managers) / framework | Scan tool | Introduced in GitLab Version | |--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| Go | [Gosec](https://github.com/securego/gosec) | 10.7, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| 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), [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| 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), [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2 | -| Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | -| React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2 | -| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) 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), [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| .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 | +| 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.1 | +| 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) | +| Java (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | +| Kotlin (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6 | +| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1 | +| Objective-C (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| 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 | +| 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) | +| Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | | TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | -NOTE: **Note:** -The Java analyzers can also be used for variants like the +Note that 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). +[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 have been moved to the GitLab Core tier. Progress can be -tracked in the corresponding -[epic](https://gitlab.com/groups/gitlab-org/-/epics/2098). +All open source (OSS) analyzers have been moved to the GitLab Core tier as of GitLab 13.3. #### Summary of features per tier @@ -147,16 +151,19 @@ always take the latest SAST artifact available. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab Ultimate 13.4. +> - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/3635) in GitLab Ultimate 13.5. You can enable and configure SAST with a basic configuration using the **SAST Configuration** page: 1. From the project's home page, go to **Security & Compliance** > **Configuration** in the left sidebar. -1. If the project does not have a `gitlab-ci.yml` file, click **Enable** in the Static Application Security Testing (SAST) row, otherwise click **Configure**. -1. Enter the custom SAST values, then click **Create Merge Request**. +1. If the project does not have a `.gitlab-ci.yml` file, click **Enable** in the Static Application Security Testing (SAST) row, otherwise click **Configure**. +1. Enter the custom SAST values. Custom values are stored in the `.gitlab-ci.yml` file. For variables not in the SAST Configuration page, their values are left unchanged. Default values are inherited from the GitLab SAST template. +1. Optionally, expand the **SAST analyzers** section, select individual [SAST analyzers](./analyzers.md) and enter custom analyzer values. +1. Click **Create Merge Request**. 1. Review and merge the merge request. ### Customizing the SAST settings @@ -169,7 +176,7 @@ set the `SAST_GOSEC_LEVEL` variable to `2`: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml variables: SAST_GOSEC_LEVEL: 2 @@ -191,13 +198,78 @@ inclusion and specify any additional keys under it. For example, this enables `F ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml spotbugs-sast: variables: FAIL_NEVER: 1 ``` +### Custom rulesets + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. + +You can customize the default scanning rules provided with SAST's NodeJS-Scan and Gosec analyzers. +Customization allows you to exclude rules and modify the behavior of existing rules. + +To customize the default scanning rules, create a file containing custom rules. These rules +are passed through to the analyzer's underlying scanner tool. + +To create a custom ruleset: + +1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. +1. Create a custom ruleset file named `sast-ruleset.toml` in the `.gitlab` directory. +1. In the `sast-ruleset.toml` file, do one of the following: + + - Define a custom analyzer configuration. In this example, customized rules are defined for the + `nodejs-scan` scanner: + + ```toml + [nodejs-scan] + description = 'custom ruleset for nodejs-scan' + + [[nodejs-scan.passthrough]] + type = "raw" + value = ''' + - nodejs-extensions: + - .js + + template-extensions: + - .new + - .hbs + - '' + + ignore-filenames: + - skip.js + + ignore-paths: + - __MACOSX + - skip_dir + - node_modules + + ignore-extensions: + - .hbs + + ignore-rules: + - regex_injection_dos + - pug_jade_template + - express_xss + + ''' + ``` + + - Provide the name of the file containing a custom analyzer configuration. In this example, + customized rules for the `gosec` scanner are contained in the file `gosec-config.json`: + + ```toml + [gosec] + description = 'custom ruleset for gosec' + + [[gosec.passthrough]] + type = "file" + value = "gosec-config.json" + ``` + ### Using environment variables to pass credentials for private repositories Some analyzers require downloading the project's dependencies in order to @@ -222,7 +294,7 @@ Kubesec analyzer. In `.gitlab-ci.yml`, define: ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml variables: SCAN_KUBERNETES_MANIFESTS: "true" @@ -248,7 +320,7 @@ stages: - test include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml build: stage: build @@ -264,17 +336,16 @@ spotbugs-sast: - build variables: MAVEN_REPO_PATH: ./.m2/repository - COMPILE: false + COMPILE: "false" artifacts: reports: sast: gl-sast-report.json ``` -NOTE: **Note:** -The path to the vendored directory must be specified explicitly to allow -the analyzer to recognize the compiled artifacts. This configuration can vary per -analyzer but in the case of Java above, `MAVEN_REPO_PATH` can be used. -See [Analyzer settings](#analyzer-settings) for the complete list of available options. +To allow the analyzer to recognize the compiled artifacts, you must explicitly specify the path to +the vendored directory. This configuration can vary per analyzer but in the case of Java above, you +can use `MAVEN_REPO_PATH`. See +[Analyzer settings](#analyzer-settings) for the complete list of available options. ### Available variables @@ -358,13 +429,29 @@ CAUTION: **Caution:** Variables having names starting with these prefixes will **not** be propagated to the SAST Docker container and/or analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, `PATH`, `SHLVL`, `HOSTNAME`. +### Experimental features + +Receive early access to experimental features. + +Currently, this will enable scanning of iOS and Android apps via the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). + +To enable experimental features, add the following to your `.gitlab-ci.yml` file: + +```yaml +include: + - template: Security/SAST.gitlab-ci.yml + +variables: + SAST_EXPERIMENTAL_FEATURES: "true" +``` + ## Reports JSON format The SAST tool emits a JSON report file. For more information, see the [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json). -The JSON report file can be downloaded from the CI pipelines page, for more -information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). +The JSON report file can be downloaded from the CI pipelines page, or the +pipelines tab on merge requests. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). Here's an example SAST report: @@ -480,7 +567,6 @@ To use SAST in an offline environment, you need: - A Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. - Configure certificate checking of packages (optional). -NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local copy is available. The GitLab Runner [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy) @@ -518,6 +604,25 @@ For details on saving and transporting Docker images as a file, see Docker's doc [`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), [`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). +#### If support for Custom Certificate Authorities are needed + +Support for custom certificate authorities was introduced in the following versions. + +| Analyzer | Version | +| -------- | ------- | +| `bandit` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/bandit/-/releases/v2.3.0) | +| `brakeman` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman/-/releases/v2.1.0) | +| `eslint` | [v2.9.2](https://gitlab.com/gitlab-org/security-products/analyzers/eslint/-/releases/v2.9.2) | +| `flawfinder` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder/-/releases/v2.3.0) | +| `gosec` | [v2.5.0](https://gitlab.com/gitlab-org/security-products/analyzers/gosec/-/releases/v2.5.0) | +| `kubesec` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/kubesec/-/releases/v2.1.0) | +| `nodejs-scan` | [v2.9.5](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan/-/releases/v2.9.5) | +| `phpcs-security-audit` | [v2.8.2](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit/-/releases/v2.8.2) | +| `pmd-apex` | [v2.1.0](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex/-/releases/v2.1.0) | +| `security-code-scan` | [v2.7.3](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan/-/releases/v2.7.3) | +| `sobelow` | [v2.2.0](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow/-/releases/v2.2.0) | +| `spotbugs` | [v2.7.1](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/releases/v2.7.1) | + ### Set SAST CI job variables to use local SAST analyzers Add the following configuration to your `.gitlab-ci.yml` file. You must replace @@ -525,7 +630,7 @@ Add the following configuration to your `.gitlab-ci.yml` file. You must replace ```yaml include: - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml variables: SECURE_ANALYZERS_PREFIX: "localhost:5000/analyzers" @@ -549,3 +654,16 @@ This error occurs when the Docker version that runs the SAST job is `19.03.0`. Consider updating to Docker `19.03.1` or greater. Older versions are not affected. Read more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/13830#note_211354992 "Current SAST container fails"). + +### Getting warning message `gl-sast-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + +### Limitation when using rules:exists + +The [SAST CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) +uses the `rules:exists` parameter. For performance reasons, a maximum number of matches are made +against the given glob pattern. If the number of matches exceeds the maximum, the `rules:exists` +parameter returns `true`. Depending on the number of files in your repository, a SAST job might be +triggered even if the scanner doesn't support your project. For more details about this issue, see +the [`rules:exists` documentation](../../../ci/yaml/README.md#rulesexists). diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index f3e411cdc16..bb10e9d7315 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -9,8 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. -## Overview - A recurring problem when developing applications is that developers may unintentionally commit secrets and credentials to their remote repositories. If other people have access to the source, or if the project is public, the sensitive information is then exposed and can be leveraged by @@ -40,7 +38,7 @@ To run Secret Detection jobs, by default, you need GitLab Runner with the 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. +Our Secret Detection jobs expect a Linux container type. Windows containers are not supported. CAUTION: **Caution:** If you use your own runners, make sure the Docker version installed @@ -67,26 +65,27 @@ as shown in the following table: ## Configuration -NOTE: **Note:** -With GitLab 13.1 Secret Detection was split into its own CI/CD template. +> GitLab 13.1 splits Secret Detection from the [SAST configuration](../sast#configuration) into its own CI/CD template. If you're using GitLab 13.0 or earlier and SAST is enabled, then Secret Detection is already enabled. Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml) -during the `secret-detection` job. It runs regardless of the programming -language of your app. +during the `secret-detection` job. It runs regardless of your app's programming language. -The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) checks. +The Secret Detection analyzer includes [Gitleaks](https://github.com/zricethezav/gitleaks) and +[TruffleHog](https://github.com/dxa4481/truffleHog) checks. -NOTE: **Note:** -The Secret Detection analyzer will ignore "Password in URL" vulnerabilities if the password begins -with a dollar sign (`$`) as this likely indicates the password being used is an environment -variable. For example, `https://username:$password@example.com/path/to/repo` won't be -detected, whereas `https://username:password@example.com/path/to/repo` would be detected. +Note that the Secret Detection analyzer ignores Password-in-URL vulnerabilities if the password +begins with a dollar sign (`$`), as this likely indicates the password is an environment variable. +For example, `https://username:$password@example.com/path/to/repo` isn't detected, while +`https://username:password@example.com/path/to/repo` is. NOTE: **Note:** -You don't have to configure Secret Detection manually as shown in this section if you're using [Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection) +You don't have to configure Secret Detection manually as shown in this section if you're using +[Auto Secret Detection](../../../topics/autodevops/stages.md#auto-secret-detection) provided by [Auto DevOps](../../../topics/autodevops/index.md). -To enable Secret Detection for GitLab 13.1 and later, you must include the `Secret-Detection.gitlab-ci.yml` template that’s provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you can copy and use the job as defined in that template. +To enable Secret Detection for GitLab 13.1 and later, you must include the +`Secret-Detection.gitlab-ci.yml` template that's provided as a part of your GitLab installation. For +GitLab versions earlier than 11.9, you can copy and use the job as defined in that template. Add the following to your `.gitlab-ci.yml` file: @@ -103,30 +102,6 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. -### Using the SAST Template - -Prior to GitLab 13.1, Secret Detection was part of [SAST configuration](../sast#configuration). -If you already have SAST enabled for your app configured before GitLab 13.1, -you don't need to manually configure it. - -CAUTION: **Planned Deprecation:** -In a future GitLab release, configuring Secret Detection with the SAST template will be deprecated. Please begin using `Secret-Detection.gitlab-ci.yml` -to prevent future issues. We have made a -[video to guide you through the process of transitioning](https://www.youtube.com/watch?v=W2tjcQreDwQ) -to this new template. - -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=W2tjcQreDwQ">Walkthrough of historical secret scan</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/W2tjcQreDwQ" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - -When using the SAST template, Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml#L180) -during the `sast` job. It runs regardless of the programming -language of your app, and you don't need to change your -CI/CD configuration file to enable it. Results are available in the SAST report. - ### Customizing settings The Secret Detection scan settings can be changed through [environment variables](#available-variables) @@ -164,9 +139,52 @@ Secret Detection can be customized by defining available variables: |-------------------------|---------------|-------------| | `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. | | `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | -| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | 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. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | +| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | +### Custom rulesets + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. + +You can customize the default secret detection rules provided with GitLab. +Customization allows you to exclude rules and add new rules. + +To create a custom ruleset: + +1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. +1. Create a custom ruleset file named `secret-detection-ruleset.toml` in the `.gitlab` directory. +1. In the `secret-detection-ruleset.toml` file, do one of the following: + + - Define a custom ruleset: + + ```toml + [secrets] + description = 'secrets custom rules configuration' + + [[secrets.passthrough]] + type = "raw" + target = "gitleaks.toml" + value = """\ + title = "gitleaks config" + # add regexes to the regex table + [[rules]] + description = "Test for Raw Custom Rulesets" + regex = '''Custom Raw Ruleset T[est]{3}''' + """ + ``` + + - Provide the name of the file containing a custom ruleset: + + ```toml + [secrets] + description = 'secrets custom rules configuration' + + [[secrets.passthrough]] + type = "file" + target = "gitleaks.toml" + value = "config/gitleaks.toml" + ``` + ### Logging level To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. @@ -197,3 +215,35 @@ We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showca <figure class="video-container"> <iframe src="https://www.youtube.com/embed/wDtc_K00Y0A" frameborder="0" allowfullscreen="true"> </iframe> </figure> + +### Make GitLab Secret Detection analyzer image available inside your Docker registry + +Import the following default Secret Detection analyzer images from `registry.gitlab.com` into your +[local Docker container registry](../../packages/container_registry/index.md): + +```plaintext +registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:3 +``` + +The process for importing Docker images into a local offline Docker registry depends on +**your network security policy**. Please consult your IT staff to find an accepted and approved +process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database) +with new definitions, so consider if you're able to make periodic updates yourself. + +For details on saving and transporting Docker images as a file, see Docker's documentation on +[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), +[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). + +#### If support for Custom Certificate Authorities are needed + +Support for custom certificate authorities was introduced in the following versions. + +| Analyzer | Version | +| -------- | ------- | +| secrets | [v3.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/releases/v3.0.0) | + +## Troubleshooting + +### Getting warning message `gl-secret-detection-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png Binary files differindex 67a7bb5f368..0310ef3ea0a 100644 --- a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_center_settings_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_center_settings_v13_4.png Binary files differnew file mode 100644 index 00000000000..4223494c294 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/instance_security_center_settings_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png Binary files differindex 3c618090be8..5edceb32e5c 100644 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png Binary files differindex d010adcc90c..5379b5c6e5d 100644 --- a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png Binary files differnew file mode 100644 index 00000000000..eb1dfe6c6f4 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png Binary files differdeleted file mode 100644 index 878bb83c2a2..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png +++ /dev/null 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 differdeleted file mode 100644 index 7cab7b0a61f..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_2.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png Binary files differdeleted file mode 100644 index 34c64f830ba..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png Binary files differnew file mode 100644 index 00000000000..c46a8295a53 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png Binary files differindex eb91cfc47ad..760942c3239 100644 --- a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png +++ b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 51d9b4f45cd..5fa8ebb80e0 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -5,21 +5,26 @@ 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)** +# GitLab Security Dashboard, Security Center, and Vulnerability Reports **(ULTIMATE)** -The Security Dashboard is a good place to get an overview of all the security -vulnerabilities in your groups, projects, and pipelines. +GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: + +- Security dashboards: An overview of the security status in your instance, groups, and projects. +- Vulnerability reports: Detailed lists of all vulnerabilities for the instance, group, project, or + pipeline. This is where you triage and manage vulnerabilities. +- Security Center: A dedicated area for vulnerability management at the instance level. This + includes a security dashboard, vulnerability report, and settings. You can also drill down into a vulnerability and get extra information. This includes the project it comes from, any related file(s), and metadata that helps you analyze the risk it poses. You can also dismiss a vulnerability or create an issue for it. -To benefit from the Security Dashboard you must first configure one of the +To benefit from these features, you must first configure one of the [security scanners](../index.md). ## Supported reports -The Security Dashboard displays vulnerabilities detected by scanners such as: +The vulnerability report displays vulnerabilities detected by scanners such as: - [Container Scanning](../container_scanning/index.md) - [Dynamic Application Security Testing](../dast/index.md) @@ -29,7 +34,7 @@ The Security Dashboard displays vulnerabilities detected by scanners such as: ## Requirements -To use the instance, group, project, or pipeline security dashboard: +To use the security dashboards and vulnerability reports: 1. At least one project inside a group must be configured with at least one of the [supported reports](#supported-reports). @@ -41,15 +46,19 @@ To use the instance, group, project, or pipeline security dashboard: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. -At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline was run against. +At the pipeline level, the Security section displays the vulnerabilities present in the branch of +the project the pipeline ran against.  Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view the pipeline's security findings, select the **Security** tab when viewing the pipeline. -NOTE: **Note:** -A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard will not show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure. +A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish +for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST +job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, +the analyzer outputs an +[exit code](../../../development/integrations/secure.md#exit-code). ## Project Security Dashboard @@ -60,12 +69,15 @@ At the project level, the Security Dashboard displays the vulnerabilities merged to **Security & Compliance > Security Dashboard**. By default, the Security Dashboard displays all detected and confirmed vulnerabilities. -The Security Dashboard first displays the total number of vulnerabilities by severity (for example, +The Security Dashboard first displays the time at which the last pipeline completed on the project's +default branch. There's also a link to view this in more detail. + +The Security Dashboard next displays the total number of vulnerabilities by severity (for example, Critical, High, Medium, Low, Info, Unknown). Below this, a 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. - + You can filter the vulnerabilities by one or more of the following: @@ -78,7 +90,7 @@ You can also dismiss vulnerabilities in the table: 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 @@ -86,79 +98,99 @@ You can also dismiss vulnerabilities in the table: 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. By default, the Security Dashboard displays all detected and confirmed -vulnerabilities. +after selecting your group. By default, the Security Dashboard displays all detected and confirmed +vulnerabilities. If you don't see the vulnerabilities over time graph, the likely cause is that you +have not selected a group. -NOTE: **Note:** -The Security Dashboard only shows projects with [security reports](#supported-reports) enabled in a -group. +Note that the Security Dashboard only shows projects with +[security reports](#supported-reports) +enabled in a group.  There 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 -90 days, with the default being 90. Hover over the chart to get more details about -the open vulnerabilities at a specific time. +vulnerabilities your projects had at various points in time. You can display the vulnerability +trends over a 30, 60, or 90-day time frame (the default is 90 days). Hover over the chart to get +more details about the open vulnerabilities at a specific time. Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: -- F: 1 or more "critical" -- D: 1 or more "high" or "unknown" -- C: 1 or more "medium" -- B: 1 or more "low" -- A: 0 vulnerabilities +- F: One or more "critical" +- D: One or more "high" or "unknown" +- C: One or more "medium" +- B: One or more "low" +- A: Zero vulnerabilities Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed -vulnerabilities are not included either. +vulnerabilities are excluded. -Navigate to the group's [Vulnerability Report](#vulnerability-list) to view the vulnerabilities found. +Navigate to the group's [vulnerability report](#vulnerability-report) to view the vulnerabilities found. -## Instance Security Dashboard +## Instance Security Center -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6953) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. -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. +The Security Center is where you manage vulnerabilities for your instance. It displays the +vulnerabilities present in the default branches of all the projects you configure. It includes the +following: + +- The [group security dashboard's](#group-security-dashboard) features. +- A [vulnerability report](#vulnerability-report). +- A dedicated settings area to configure which projects to display.  -You can access the Instance Security Dashboard from the menu +You can access the Instance Security Center from the menu bar at the top of the page. Under **More**, select **Security**. - + -The dashboard is empty before you add projects to it. +The dashboard and vulnerability report are empty before you add projects. - + -### Adding projects to the dashboard +### Adding projects to the Security Center -To add projects to the dashboard: +To add projects to the Security Center: 1. Click **Settings** in the left navigation bar or click the **Add projects** button. 1. Search for and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. -After you add projects, the Security Dashboard displays the vulnerabilities found in those projects' -default branches. + + +After you add projects, the security dashboard and vulnerability report display the vulnerabilities +found in those projects' default branches. ## Export vulnerabilities > [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 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 **Security Dashboard**, -as filters don't apply to the export function. - - +You can export all your vulnerabilities in CSV (comma separated values) format by clicking the +**{upload}** **Export** button located at top right of the Security Dashboard. When the report is +ready, the CSV report downloads to your local machine. The report contains all 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. +thousands of vulnerabilities. Don't close the page until the download finishes. + +The fields in the export include: + +- Group Name +- Project Name +- Scanner Type +- Scanner Name +- Status +- Vulnerability +- Details +- Additional Info +- Severity +- [CVE](https://cve.mitre.org/) (Common Vulnerabilities and Exposures) +- [CWE](https://cwe.mitre.org/) (Common Weakness Enumeration) +- Other Identifiers + + ## Keeping the dashboards up to date @@ -191,14 +223,14 @@ 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 +## Vulnerability report -Each dashboard's vulnerability list contains vulnerabilities from the latest scans that were merged +Each vulnerability report contains vulnerabilities from the latest scans that were merged into the default branch.  -You can filter which vulnerabilities the Security Dashboard displays by: +You can filter which vulnerabilities the vulnerability report displays by: - Status - Severity @@ -211,8 +243,10 @@ To create an issue associated with the vulnerability, click the **Create Issue**  -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). +Once you create the issue, the linked issue icon in the vulnerability list: + +- Indicates that an issue has been created for that vulnerability. +- Shows a tooltip that contains a link to the issue.  diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index 8006a49ba35..f975de213ef 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -13,7 +13,6 @@ This terminology list for GitLab Secure and Defend aims to: - Improve the effectiveness of communication regarding GitLab's application security features. - Get new contributors up to speed faster. -NOTE: **Note:** This document defines application security terms in the specific context of GitLab's Secure and Defend products. Terms may therefore have different meanings outside of GitLab Secure and Defend. diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 5414800b290..391666a077e 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -105,11 +105,10 @@ disabled state. Once enabled,a predefined policy deploys to the selected environment's deployment platform and you can manage it like the regular policies. -NOTE: **Note:** -If you're using [Auto DevOps](../../../topics/autodevops/index.md) and -change a policy in this section, your `auto-deploy-values.yaml` file -doesn't update. Auto DevOps users must make changes by following -the [Container Network Policy documentation](../../../topics/autodevops/stages.md#network-policy). +Note that if you're using [Auto DevOps](../../../topics/autodevops/index.md) +and change a policy in this section, your `auto-deploy-values.yaml` file doesn't update. Auto DevOps +users must make changes by following the +[Container Network Policy documentation](../../../topics/autodevops/stages.md#network-policy). ### Changing enforcement status @@ -119,12 +118,9 @@ To change a network policy's enforcement status: - Click the **Enforcement status** toggle to update the selected policy. - Click the **Apply changes** button to deploy network policy changes. -NOTE: **Note:** -Disabled network policies have the -`network-policy.gitlab.com/disabled_by: gitlab` selector inside the -`podSelector` block. This narrows the scope of such a policy and as a -result it doesn't affect any pods. The policy itself is still deployed -to the corresponding deployment namespace. +Disabled network policies have the `network-policy.gitlab.com/disabled_by: gitlab` selector inside +the `podSelector` block. This narrows the scope of such a policy and as a result it doesn't affect +any pods. The policy itself is still deployed to the corresponding deployment namespace. ### Container Network Policy editor @@ -135,10 +131,8 @@ create a new policy click the **New policy** button located in the **Policy** tab's header. To edit an existing policy, click**Edit policy** in the selected policy drawer. -NOTE: **Note:** -The policy editor only supports the -[CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/)specification. Regular -Kubernetes +Note that the policy editor only supports the +[CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/)specification. Regular Kubernetes [NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) resources aren't supported. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index ff383fdf553..ee3fd6c4dd4 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -14,6 +14,7 @@ Each security vulnerability in a project's [Security Dashboard](../security_dash - Details of the vulnerability. - The status of the vulnerability within the project. - Available actions for the vulnerability. +- Issues related to the vulnerability. On the vulnerability page, you can interact with the vulnerability in several different ways: @@ -23,6 +24,7 @@ several different ways: - [Create issue](#creating-an-issue-for-a-vulnerability) - Create a new issue with the title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../../project/issues/confidential_issues.md). +- [Link issues](#link-issues-to-the-vulnerability) - Link existing issues to vulnerability. - [Solution](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, a solution is provided for how to fix the vulnerability. @@ -38,6 +40,9 @@ the following values: | Dismissed | A user has seen this vulnerability and dismissed it | | Resolved | The vulnerability has been fixed and is no longer in the codebase | +A timeline shows you when the vulnerability status has changed, +and allows you to comment on a change. + ## Creating an issue for a vulnerability You can create an issue for a vulnerability by selecting the **Create issue** button. @@ -47,6 +52,12 @@ project the vulnerability came from, and pre-populates it with useful informatio the vulnerability report. After the issue is created, GitLab redirects you to the issue page so you can edit, assign, or comment on the issue. +## Link issues to the vulnerability + +You can link one or more existing issues to the vulnerability. This allows you to +indicate that this vulnerability affects multiple issues. It also allows you to indicate +that the resolution of one issue would resolve multiple vulnerabilities. + ## Automatic remediation for vulnerabilities You can fix some vulnerabilities by applying the solution that GitLab automatically |
