diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 13:18:24 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 13:18:24 +0000 |
| commit | 0653e08efd039a5905f3fa4f6e9cef9f5d2f799c (patch) | |
| tree | 4dcc884cf6d81db44adae4aa99f8ec1233a41f55 /doc/user/application_security | |
| parent | 744144d28e3e7fddc117924fef88de5d9674fe4c (diff) | |
| download | gitlab-ce-0653e08efd039a5905f3fa4f6e9cef9f5d2f799c.tar.gz | |
Add latest changes from gitlab-org/gitlab@14-3-stable-eev14.3.0-rc42
Diffstat (limited to 'doc/user/application_security')
32 files changed, 527 insertions, 420 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 7ed36572be4..e32989c2915 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -85,7 +85,7 @@ In GitLab 14.0 and later, API fuzzing configuration files must be in your reposi ### Web API fuzzing configuration form -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -98,17 +98,16 @@ a YAML snippet that you can paste in your GitLab CI/CD configuration. To generate an API Fuzzing configuration snippet: -1. From your project's home page, go to **Security & Compliance > Configuration** in the left - sidebar. -1. Select **Configure** in the **API Fuzzing** row. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. In the **API Fuzzing** row, select **Configure**. 1. Complete the form as needed. Read below for more information on available configuration options. 1. Select **Generate code snippet**. A modal opens with the YAML snippet corresponding to the options you've selected in the form. 1. Choose one of the following actions: - 1. Select **Copy code and open `.gitlab-ci.yml` file** to copy the snippet to your clipboard and - be redirected to your project's `.gitlab-ci.yml` file where you can paste the YAML - configuration. - 1. Select **Copy code only** to copy the snippet to your clipboard and close the modal. + 1. To copy the snippet to your clipboard and be redirected to your project's `.gitlab-ci.yml` file, + where you can paste the YAML configuration, select **Copy code and open `.gitlab-ci.yml` file**. + 1. To copy the snippet to your clipboard and close the modal, select **Copy code only**. ### OpenAPI Specification @@ -995,7 +994,7 @@ Follow these steps to view details of a fuzzing fault: **API Fuzzing detected N potential vulnerabilities**. Click the title to display the fault details. -1. Click the fault's title to display the fault's details. The table below describes these details. +1. Select the fault's title to display the fault's details. The table below describes these details. | Field | Description | |:--------------------|:----------------------------------------------------------------------------------------| diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 664fcd9b72f..98e241ba3bd 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -13,61 +13,56 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - A simplified version was made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/294076) in GitLab 13.10. > - [Redesigned](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in 14.2. -The Security Configuration page displays what security scans are available, links to documentation and also simple enablement tools for the current project. +The Security Configuration page lists the following for the security testing and compliance tools: -To view a project's security configuration, go to the project's home page, -then in the left sidebar go to **Security & Compliance > Configuration**. - -For each security control the page displays: - -- Its name, description and a documentation link. +- Name, description, and a documentation link. - Whether or not it is available. - A configuration button or a link to its configuration guide. +The status of each security control is determined by the project's latest default branch +[CI pipeline](../../../ci/pipelines/index.md). +If a job with the expected security report artifact exists in the pipeline, the feature's status is +_enabled_. + +If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), +all security features are configured by default. + +To view a project's security configuration: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. + +Select **Configuration history** to see the `.gitlab-ci.yml` file's history. + ## Security testing You can configure the following security controls: -- Auto DevOps - - Click **Enable Auto DevOps** on the alert to enable it for the current project. For more details, see [Auto DevOps](../../../topics/autodevops/index.md). -- SAST - - Click **Enable SAST** to use SAST for the current project. For more details, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). -- DAST **(ULTIMATE)** - - Click **Enable DAST** to use DAST for the current Project. To manage the available DAST profiles used for on-demand scans Click **Manage Scans**. For more details, see [DAST on-demand scans](../dast/index.md#on-demand-scans). +- Static Application Security Testing (SAST) + - Select **Enable SAST** to configure SAST for the current project. + For more details, read [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). +- Dynamic Application Security Testing (DAST) **(ULTIMATE)** + - Select **Enable DAST** to configure DAST for the current project. + - Select **Manage scans** to manage the saved DAST scans, site profiles, and scanner profiles. + For more details, read [DAST on-demand scans](../dast/index.md#on-demand-scans). - Dependency Scanning **(ULTIMATE)** - Select **Configure via Merge Request** to create a merge request with the changes required to enable Dependency Scanning. For more details, see [Enable Dependency Scanning via an automatic merge request](../dependency_scanning/index.md#enable-dependency-scanning-via-an-automatic-merge-request). - - Container Scanning **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [Container Scanning](../../../user/application_security/container_scanning/index.md#configuration). - Cluster Image Scanning **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [Cluster Image Scanning](../../../user/application_security/cluster_image_scanning/#configuration). - Secret Detection - Select **Configure via Merge Request** to create a merge request with the changes required to - enable Secret Detection. For more details, see [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). - + enable Secret Detection. For more details, read [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request). - API Fuzzing **(ULTIMATE)** - - Click **Enable API Fuzzing** to use API Fuzzing for the current Project. For more details, see [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). + - Select **Enable API Fuzzing** to use API Fuzzing for the current project. For more details, read [API Fuzzing](../../../user/application_security/api_fuzzing/index.md#enable-web-api-fuzzing). - Coverage Fuzzing **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#configuration). - -## Status **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. - -The status of each security control is determined by the project's latest default branch -[CI pipeline](../../../ci/pipelines/index.md). -If a job with the expected security report artifact exists in the pipeline, the feature's status is -_enabled_. - -If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), -all security features are configured by default. - -Click **View history** to see the `.gitlab-ci.yml` file's history. + - Can be configured with `.gitlab-ci.yml`. For more details, read [Coverage Fuzzing](../../../user/application_security/coverage_fuzzing/index.md#configuration). ## Compliance **(ULTIMATE)** You can configure the following security controls: - License Compliance **(ULTIMATE)** - - Can be configured via `.gitlab-ci.yml`. For more details, see [License Compliance](../../../user/compliance/license_compliance/index.md#configuration). + - Can be configured with `.gitlab-ci.yml`. For more details, read [License Compliance](../../../user/compliance/license_compliance/index.md#configuration). diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 5791351a067..2b3d4dbfc0a 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,14 +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. -WARNING: -Versions of GitLab prior to 14.0 used Clair as the default container scanning engine. GitLab 14.0 -removes Clair from the product and replaces it with two new scanners. If you -run container scanning with the default settings, GitLab switches you seamlessly and automatically -to Trivy in GitLab 14.0. However, if you customized the variables in your container scanning job, -you should review the [migration guide](#change-scanners) -and make any necessary updates. - 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. @@ -57,37 +49,9 @@ To enable container scanning in your pipeline, you need the following: ## Configuration -How you enable container scanning depends on your GitLab version: - -- GitLab 11.9 and later: [Include](../../../ci/yaml/index.md#includetemplate) the - [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) - that comes with your GitLab installation. -- GitLab versions earlier than 11.9: Copy and use the job from the - [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). - -Other changes: - -- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for - [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the - `CS_MAJOR_VERSION` from `2` to `3`. Version `3` of the `container_scanning` Docker image uses - [`centos:centos8`](https://hub.docker.com/_/centos) - as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) - script and instead executes the analyzer by default. Any customizations made to the - `container_scanning` job's [`before_script`](../../../ci/yaml/index.md#before_script) - and [`after_script`](../../../ci/yaml/index.md#after_script) - blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based - Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables) - variable. -- GitLab 13.9 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) integration with - [Trivy](https://github.com/aquasecurity/trivy) by upgrading `CS_MAJOR_VERSION` from `3` to `4`. -- GitLab 14.0 [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61850) - an integration with [Trivy](https://github.com/aquasecurity/trivy) - as the default for container scanning, and also [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326279) - an integration with [Grype](https://github.com/anchore/grype) - as an alternative scanner. - -To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the -following to your `.gitlab-ci.yml` file: +To enable container scanning, add the +[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) +to your `.gitlab-ci.yml` file: ```yaml include: @@ -157,7 +121,7 @@ You can [configure](#customizing-the-container-scanning-settings) analyzers by u | `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | All | | `CS_ANALYZER_IMAGE` | `registry.gitlab.com/security-products/container-scanning:4` | Docker image of the analyzer. | All | | `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | -| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | Trivy. The registry must listen on port `80/tcp`. | +| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. Works with all scanners, but the registry must listen on port `80/tcp` for Trivy to work. | All | | `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | | `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | All | | `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. The default is only set if `$DOCKER_IMAGE` resides at [`$CI_REGISTRY`](../../../ci/variables/predefined_variables.md). | All | @@ -625,3 +589,29 @@ To prevent the error, ensure the Docker version that the runner is using is ### 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). + +## Changes + +- GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for + [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the + `CS_MAJOR_VERSION` from `2` to `3`. Version `3` of the `container_scanning` Docker image uses + [`centos:centos8`](https://hub.docker.com/_/centos) + as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77) + script and instead executes the analyzer by default. Any customizations made to the + `container_scanning` job's [`before_script`](../../../ci/yaml/index.md#before_script) + and [`after_script`](../../../ci/yaml/index.md#after_script) + blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based + Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables) + variable. +- GitLab 13.9 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) integration with + [Trivy](https://github.com/aquasecurity/trivy) by upgrading `CS_MAJOR_VERSION` from `3` to `4`. +- GitLab 13.9 [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/321451) the integration with + [Clair](https://github.com/quay/clair/). +- GitLab 14.0 [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61850) + an integration with [Trivy](https://github.com/aquasecurity/trivy) + as the default for container scanning, and also [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326279) + an integration with [Grype](https://github.com/anchore/grype) + as an alternative scanner. + +Other changes to the container scanning analyzer can be found in the project's +[changelog](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/blob/master/CHANGELOG.md). diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 679d20a6394..0d5eb2b6d50 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Coverage Guided Fuzz Testing **(ULTIMATE)** +# Coverage-guided fuzz testing **(ULTIMATE)** GitLab allows you to add coverage-guided fuzz testing to your pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. Coverage-guided fuzzing sends @@ -82,7 +82,7 @@ The `my_fuzz_target` job (the separate job for your fuzz target) does the follow - Runs on a fuzz stage that usually comes after a test stage. The `gitlab-cov-fuzz` is a command-line tool that runs the instrumented application. It parses and -analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](#glossary) +analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](../terminology/index.md#corpus) and crash events from previous pipelines automatically. This helps your fuzz targets build on the progress of previous fuzzing jobs. The parsed crash events and data are written to `gl-coverage-fuzzing-report.json`. @@ -97,7 +97,7 @@ Each fuzzing step outputs these artifacts: - `crashes`: Holds all crash events the current job encountered as well as those not fixed in previous jobs. -### Types of Fuzzing Jobs +### Types of fuzzing jobs There are two types of jobs: @@ -127,7 +127,7 @@ any option available in the underlying fuzzing engine. | `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | | `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | -The files in the seed corpus (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new +The files in the [seed corpus](../terminology/index.md#seed-corpus) (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new files to your Git repository. There's usually no need to frequently update the seed corpus. As part of the GitLab artifacts system, GitLab saves in a corpus directory the new test cases that every run generates. In any subsequent runs, GitLab also reuses the generated corpus together with the seed @@ -172,13 +172,13 @@ Here's an example coverage fuzzing report: } ``` -### Additional Configuration +### Additional configuration The `gitlab-cov-fuzz` command passes all arguments it receives to the underlying fuzzing engine. You can therefore use all the options available in that fuzzing engine. For more information on these options, see the underlying fuzzing engine's documentation. -### Offline Environment +### Offline environment To use coverage fuzzing in an offline environment, follow these steps: @@ -262,12 +262,3 @@ vulnerability: - Scanner: The scanner that detected the vulnerability (for example, Coverage Fuzzing). - Scanner Provider: The engine that did the scan. For Coverage Fuzzing, this can be any of the engines listed in [Supported fuzzing engines and languages](#supported-fuzzing-engines-and-languages). - -### Glossary - -- Seed corpus: The set of test cases given as initial input to the fuzz target. This usually speeds - up the fuzz target substantially. This can be either manually created test cases or auto-generated - with the fuzz target itself from previous runs. -- Corpus: The set of meaningful test cases that are generated while the fuzzer is running. Each - meaningful test case produces new coverage in the tested program. It's advised to re-use the - corpus and pass it to subsequent runs. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index e8fbc17327c..5094ccd2196 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -19,7 +19,7 @@ The browser-based crawler works by loading the target application into a special such as clicking on a link or filling in a form. For each action found, the crawler will execute it, take a new snapshot and determine what in the page changed from the previous snapshot. Crawling continues by taking more snapshots and finding subsequent actions. -The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don’t understand. This results in better coverage of the website. +The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don't understand. This results in better coverage of the website. Using the browser-based crawler should provide greater coverage for most web applications, compared with the current DAST AJAX crawler. The new crawler replaces the AJAX crawler and is specifically designed to maximize crawl coverage in modern web applications. While both crawlers are currently used in conjunction with the existing DAST scanner, the combination of the browser-based crawler with the current DAST scanner is much more effective at finding and testing every page in an application. diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md index 725fab85789..f771bc82d58 100644 --- a/doc/user/application_security/dast/dast_troubleshooting.md +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -88,3 +88,7 @@ stages: include: - template: DAST.latest.gitlab-ci.yml ``` + +## Lack of IPv6 support + +Due to the underlying [ZAProxy engine not supporting IPv6](https://github.com/zaproxy/zaproxy/issues/3705), DAST is unable to scan or crawl IPv6-based applications. diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 7455915761c..0d60701b030 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -74,7 +74,7 @@ If your application utilizes Docker containers you have another option for deplo After your Docker build job completes and your image is added to your container registry, you can use the image as a [service](../../../ci/services/index.md). -By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. +By using service definitions in your `.gitlab-ci.yml`, you can scan services with the DAST analyzer. ```yaml stages: @@ -328,6 +328,8 @@ Vulnerability rules in an API scan are different than those in a normal website A new DAST API scanning engine is available in GitLab 13.12 and later. For more details, see [DAST API scanning engine](../dast_api). The new scanning engine supports REST, SOAP, GraphQL, and generic APIs using forms, XML, and JSON. Testing can be performed using OpenAPI, Postman Collections, and HTTP Archive (HAR) documents. +The target API instance’s base URL is provided by using the `DAST_API_TARGET_URL` variable or an `environment_url.txt` file. + #### Specification format API scans support OpenAPI V2 and OpenAPI V3 specifications. You can define these specifications using `JSON` or `YAML`. @@ -339,7 +341,7 @@ The specification does not have to be hosted on the same host as the API being t ```yaml include: - - template: DAST.gitlab-ci.yml + - template: DAST-API.gitlab-ci.yml variables: DAST_API_OPENAPI: http://my.api/api-specification.yml @@ -390,7 +392,7 @@ the following DAST configuration can be used: ```yaml include: - - template: DAST.gitlab-ci.yml + - template: DAST-API.gitlab-ci.yml variables: DAST_API_OPENAPI: http://api-test.host.com/api-specification.yml @@ -405,7 +407,7 @@ Headers are applied to every request DAST makes. ```yaml include: - - template: DAST.gitlab-ci.yml + - template: DAST-API.gitlab-ci.yml variables: DAST_API_OPENAPI: http://api-test.api.com/api-specification.yml @@ -554,6 +556,9 @@ By default, several rules are disabled because they either take a long time to run or frequently generate false positives. The complete list of disabled rules can be found in [exclude_rules.yml](https://gitlab.com/gitlab-org/security-products/dast/-/blob/main/src/config/exclude_rules.yml). +The lists for `DAST_EXCLUDE_RULES` and `DAST_ONLY_INCLUDE_RULES` **must** be enclosed in double +quotes (`"`), otherwise they are interpreted as numeric values. + ### Hide sensitive information > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. @@ -742,7 +747,7 @@ dast: when: always ``` -### Available CI/CD variables +## Available CI/CD variables These CI/CD variables are specific to DAST. They can be used to customize the behavior of DAST to your requirements. @@ -762,7 +767,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false`. | | `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1,2</sup> | selector | Comma-separated list of selectors that will be clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. Example: `"css:.navigation-menu,css:.login-menu-item"`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. | | `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. The whole list **must** be enclosed in double quotes (`"`). Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | | `DAST_EXCLUDE_URLS` <sup>1,2</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. Example, `http://example.com/sign-out`. | | `DAST_FIRST_SUBMIT_FIELD` <sup>2</sup> | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. For example, `css:button[type='user-submit']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` | @@ -772,7 +777,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | | `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | -| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | +| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. The whole list **must** be enclosed in double quotes (`"`). Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | | `DAST_PASSWORD` <sup>1,2</sup> | string | The password to authenticate to in the website. Example: `P@55w0rd!` | | `DAST_PASSWORD_FIELD` <sup>1,2</sup> | string | The selector of password field at the sign-in HTML form. Example: `id:password` | | `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | @@ -795,7 +800,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be 1. Available to an on-demand DAST scan. 1. Used for authentication. -#### Selectors +### Selectors Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. Selectors have the format `type`:`search string`. The crawler will search for the selector using the search string based on the type. @@ -808,7 +813,7 @@ Selectors have the format `type`:`search string`. The crawler will search for th | `xpath` | `xpath://input[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. Note that XPath searches are expected to be less performant than other searches. | | None provided | `a.click-me` | Defaults to searching using a CSS selector. | -##### Find selectors with Google Chrome +#### Find selectors with Google Chrome Chrome DevTools element selector tool is an effective way to find a selector. @@ -824,7 +829,7 @@ Chrome DevTools element selector tool is an effective way to find a selector. In this example, the `id="user_login"` appears to be a good candidate. You can use this as a selector as the DAST username field by setting `DAST_USERNAME_FIELD: "id:user_login"`. -##### Choose the right selector +#### Choose the right selector Judicious choice of selector leads to a scan that is resilient to the application changing. @@ -919,7 +924,7 @@ The DAST job does not require the project's repository to be present when runnin > - Auditing for DAST profile management was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1. An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger -the scan. You must start it manually. +the scan. You must either start it manually, or schedule it to run. An on-demand DAST scan: @@ -928,8 +933,6 @@ An on-demand DAST scan: - Is associated with your project's default branch. - Is saved on creation so it can be run later. -In GitLab 13.10 and later, you can select to run an on-demand scan against a specific branch. - ### On-demand scan modes An on-demand scan can be run in active or passive mode: @@ -941,23 +944,34 @@ An on-demand scan can be run in active or passive mode: ### Run an on-demand DAST scan -NOTE: -You must have permission to run an on-demand DAST scan against a protected branch. -The default branch is automatically protected. For more information, see -[Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). - Prerequisites: +- You must have permission to run an on-demand DAST scan against a protected branch. The default + branch is automatically protected. For more information, read + [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). - A [scanner profile](#create-a-scanner-profile). - A [site profile](#create-a-site-profile). -- If you are running an active scan the site profile must be [validated](#validate-a-site-profile). +- If you are running an active scan the site profile must have been [validated](#validate-a-site-profile). + +You can run an on-demand scan immediately, once at a scheduled date and time or at a specified +frequency: + +- Every day +- Every week +- Every month +- Every 3 months +- Every 6 months +- Every year -To run an on-demand scan, either: +To run an on-demand scan immediately, either: -- [Create and run an on-demand scan](#create-and-run-an-on-demand-scan). +- [Create and run an on-demand scan immediately](#create-and-run-an-on-demand-scan-immediately). - [Run a previously saved on-demand scan](#run-a-saved-on-demand-scan). -#### Create and run an on-demand scan +To run an on-demand scan either at a scheduled date or frequency, read +[Schedule an on-demand scan](#schedule-an-on-demand-scan). + +#### Create and run an on-demand scan immediately 1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. @@ -965,44 +979,70 @@ To run an on-demand scan, either: 1. In GitLab 13.10 and later, select the desired branch from the **Branch** dropdown. 1. In **Scanner profile**, select a scanner profile from the dropdown. 1. In **Site profile**, select a site profile from the dropdown. -1. To run the on-demand scan now, select **Save and run scan**. Otherwise select **Save scan** to - [run](#run-a-saved-on-demand-scan) it later. +1. To run the on-demand scan immediately, select **Save and run scan**. Otherwise, select + **Save scan** to [run](#run-a-saved-on-demand-scan) it later. The on-demand DAST scan runs and the project's dashboard shows the results. -### List saved on-demand scans +#### Run a saved on-demand scan -To list saved on-demand scans: +To run a saved on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Configuration**. +1. Select **Manage DAST scans**. +1. In the **DAST Profiles** row, select **Manage**. 1. Select the **Saved Scans** tab. +1. In the scan's row, select **Run scan**. + + If the branch saved in the scan no longer exists, you must first + [edit the scan](#edit-an-on-demand-scan), select a new branch, and save the edited scan. -### View details of an on-demand scan +The on-demand DAST scan runs, and the project's dashboard shows the results. -To view details of an on-demand scan: +#### Schedule an on-demand scan + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328749) in GitLab 14.3. [Deployed behind the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md), disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per user, +ask an administrator to [disable the `dast_on_demand_scans_scheduler` flag](../../../administration/feature_flags.md). +The feature is not ready for production use. + +To schedule a scan: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > On-demand Scans**. +1. Complete the **Scan name** and **Description** text boxes. +1. In GitLab 13.10 and later, from the **Branch** dropdown list, select the desired branch. +1. In the **Scanner profile** section, from the dropdown list, select a scanner profile. +1. In the **Site profile** section, from the dropdown list, select a site profile. +1. Select **Schedule scan**. +1. In the **Start time** section, select a time zone, date, and time. +1. From the **Repeats** dropdown list, select your desired frequency: + - To run the scan once, select **Never**. + - For a recurring scan, select any other option. +1. To run the on-demand scan immediately, select **Save and run scan**. To [run](#run-a-saved-on-demand-scan) it according to the schedule you set, select + **Save scan**. + +#### List saved on-demand scans + +To list saved on-demand scans: 1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. 1. Select the **Saved Scans** tab. -1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. -### Run a saved on-demand scan +#### View details of an on-demand scan -To run a saved on-demand scan: +To view details of an on-demand scan: 1. From your project's home page, go to **Security & Compliance > Configuration**. 1. Select **Manage DAST scans**. 1. Select **Manage** in the **DAST Profiles** row. 1. Select the **Saved Scans** tab. -1. In the scan's row select **Run scan**. - - If the branch saved in the scan no longer exists, you must first - [edit the scan](#edit-an-on-demand-scan), select a new branch, and save the edited scan. - -The on-demand DAST scan runs and the project's dashboard shows the results. +1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. -### Edit an on-demand scan +#### Edit an on-demand scan To edit an on-demand scan: @@ -1014,7 +1054,7 @@ To edit an on-demand scan: 1. Edit the form. 1. Select **Save scan**. -### Delete an on-demand scan +#### Delete an on-demand scan To delete an on-demand scan: @@ -1049,11 +1089,7 @@ When an API site type is selected, a [host override](#host-override) is used to #### Site profile validation > - Site profile validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. -> - Meta tag validation [enabled on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2 and is ready for production use. -> - Meta tag validation [enabled with `dast_meta_tag_validation flag` flag](https://gitlab.com/gitlab-org/gitlab/-/issues/337711) for self-managed GitLab in GitLab 14.2 and is ready for production use. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the `dast_meta_tag_validation` flag](../../../administration/feature_flags.md). On GitLab.com, this feature is available but can be configured by GitLab.com administrators only. +> - Meta tag validation [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6460) in GitLab 14.2. Site profile validation reduces the risk of running an active scan against the wrong website. A site must be validated before an active scan can run against it. The site validation methods are as @@ -1096,7 +1132,7 @@ To edit an existing site profile: 1. Edit the fields then select **Save profile**. If a site profile is linked to a security policy, a user cannot edit the profile from this page. See -[Scan Policies](../policies/index.md) +[Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. #### Delete a site profile @@ -1110,7 +1146,7 @@ To delete an existing site profile: 1. Select **Delete** to confirm the deletion. If a site profile is linked to a security policy, a user cannot delete the profile from this page. -See [Scan Policies](../policies/index.md) +See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. #### Validate a site profile @@ -1147,6 +1183,21 @@ The site is validated and an active scan can run against it. If a validated site profile's target URL is edited, the site's validation status is revoked. +#### Retry a failed validation + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322609) in GitLab 14.3. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an +administrator to [disable the `dast_failed_site_validations` flag](../../../administration/feature_flags.md). + +If a site profile's validation fails, you can retry it by selecting the **Retry validation** button +in the profiles list. + +When loading the DAST profiles library, past failed validations are listed above the profiles +list. You can also retry the validation from there by selecting the **Retry validation** link in +the alert. You can also dismiss the alert to revoke failed validations. + #### Revoke a site profile's validation status Note that all site profiles with the same URL have their validation status revoked. @@ -1240,7 +1291,7 @@ To edit a scanner profile: 1. Select **Save profile**. If a scanner profile is linked to a security policy, a user cannot edit the profile from this page. -See [Scan Policies](../policies/index.md) +See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. #### Delete a scanner profile @@ -1254,7 +1305,7 @@ To delete a scanner profile: 1. Select **Delete**. If a scanner profile is linked to a security policy, a user cannot delete the profile from this -page. See [Scan Policies](../policies/index.md) +page. See [Scan Execution Policies](../policies/index.md#scan-execution-policy-editor) for more information. ### Auditing @@ -1311,9 +1362,9 @@ dast: By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If your DAST job does not rely on `environment_url.txt` to define the URL under test or any other files created in previous jobs, we recommend you don't download artifacts. To avoid downloading -artifacts, add the following to your `gitlab-ci.yml` file: +artifacts, add the following to your `.gitlab-ci.yml` file: -```json +```yaml dast: dependencies: [] ``` diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 48a784e0d03..055a2ceb161 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -897,7 +897,7 @@ variables: ### Exclude Paths -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. When testing an API it can be useful to exclude certain paths. For example, you might exclude testing of an authentication service or an older version of the API. To exclude paths, use the `FUZZAPI_EXCLUDE_PATHS` CI/CD variable . This variable is specified in your `.gitlab-ci.yml` file. To exclude multiple paths, separate entries using the `;` character. In the provided paths you can use a single character wildcard `?` and `*` for a multiple character wildcard. diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 1cb21d34853..edfd0333d54 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10075) in GitLab Ultimate 12.0. Use the dependency list to review your project's dependencies and key -details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. +details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. To see the dependency list, go to your project and select **Security & Compliance > Dependency List**. @@ -49,7 +49,7 @@ can also be sorted by name or by the packager that installed them. If a dependency has known vulnerabilities, view them by clicking the arrow next to the dependency's name or the badge that indicates how many known vulnerabilities exist. For each vulnerability, its severity and description appears below it. To view more details of a vulnerability, -select the vulnerability’s description. The [vulnerability's details](../vulnerabilities) page is opened. +select the vulnerability's description. The [vulnerability's details](../vulnerabilities) page is opened. ### Dependency paths @@ -78,8 +78,8 @@ You can download your project's full list of dependencies and their details in ### In the UI -You can download your project’s list of dependencies and their details in JSON format by selecting the **Export** button. Note that the dependency list only shows the results of the last successful pipeline to run on the default branch. +You can download your project's list of dependencies and their details in JSON format by selecting the **Export** button. Note that the dependency list only shows the results of the last successful pipeline to run on the default branch. ### Using the API -You can download your project’s list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the gemnasium family of analyzers and [not any other of the GitLab dependency analyzers](../dependency_scanning/analyzers.md). +You can download your project's list of dependencies [using the API](../../../api/dependencies.md#list-project-dependencies). Note this only provides the dependencies identified by the gemnasium family of analyzers and [not any other of the GitLab dependency analyzers](../dependency_scanning/analyzers.md). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 565b9c29934..d903ce58982 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -57,8 +57,8 @@ However, you can override the selection using the variable `DS_EXCLUDED_ANALYZER The language detection relies on CI job [`rules`](../../../ci/yaml/index.md#rules) and searches a maximum of two directory levels from the repository's root. For example, the -`gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or -`api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`. +`gemnasium-dependency_scanning` job is enabled if a repository contains either `Gemfile`, +`api/Gemfile`, or `api/client/Gemfile`, but not if the only supported dependency file is `api/v1/client/Gemfile`. The following languages and dependency managers are supported: @@ -147,7 +147,7 @@ table.supported-languages ul { </tr> <tr> <td rowspan="2">Java</td> - <td><a href="https://gradle.org/">Gradle</a></td> + <td><a href="https://gradle.org/">Gradle</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">1</a></b></sup></td> <td>Any</td> <td> <ul> @@ -228,7 +228,7 @@ table.supported-languages ul { <td> <ul> <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile</code></a></li> - <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">1</a></b></sup></li> + <li><a href="https://pipenv.pypa.io/en/latest/basics/#example-pipfile-pipfile-lock"><code>Pipfile.lock</code></a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">2</a></b></sup></li> </ul> </td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -236,7 +236,7 @@ table.supported-languages ul { </tr> <tr> <td>Scala</td> - <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">2</a></b></sup></td> + <td><a href="https://www.scala-sbt.org/">sbt</a><sup><b><a href="#notes-regarding-supported-languages-and-package-managers">3</a></b></sup></td> <td>Any</td> <td><code>build.sbt</code></td> <td><a href="https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium">Gemnasium</a></td> @@ -247,6 +247,8 @@ table.supported-languages ul { ### Notes regarding supported languages and package managers +1. Although Gradle with Java 8 is supported, there are other issues such that Android project builds are not supported at this time. Please see the backlog issue [Android support for Dependency Scanning (gemnasium-maven)](https://gitlab.com/gitlab-org/gitlab/-/issues/336866) for more details. + 1. The presence of a `Pipfile.lock` file alone will _not_ trigger the analyzer; the presence of a `Pipfile` is still required in order for the analyzer to be executed. However, if a `Pipfile.lock` file is found, it will be used by `Gemnasium` to scan the exact package versions listed in this file. @@ -262,7 +264,7 @@ GitLab relies on [`rules:exists`](../../../ci/yaml/index.md#rulesexists) to star `Supported files` in the repository as shown in the [table above](#supported-languages-and-package-managers). The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if -a repository contains either a `Gemfile.lock` or `api/Gemfile.lock` file, but not if the only supported dependency file is `api/client/Gemfile.lock`. +a repository contains either a `Gemfile.lock`, `api/Gemfile.lock`, or `api/client/Gemfile.lock`, but not if the only supported dependency file is `api/v1/client/Gemfile.lock`. ### How multiple files are processed @@ -287,13 +289,13 @@ We execute both analyzers because they use different sources of vulnerability da #### Python -We only execute one build in the directory where a requirements file has been detected, such as `requirements.txt` or any +We only execute one installation in the directory where a requirements file has been detected, such as `requirements.txt` or any variation of this file (for example, `requirements.pip` or `requires.txt`). #### Java and Scala We only execute one build in the directory where a build file has been detected, such as `build.sbt` or `build.gradle`. -Please note, we support the following types of Java project stuctures: +Please note, we support the following types of Java project structures: - [multi-project sbt builds](https://www.scala-sbt.org/1.x/docs/Multi-Project.html) - [multi-project gradle builds](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html) @@ -908,3 +910,19 @@ with a dependency on this version of Python should use `retire.js` version 2.10. ### Error: `dependency_scanning is used for configuration only, and its script should not be executed` For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed). + +### Import multiple certificates for Java-based projects + +The `gemnasium-maven` analyzer reads the contents of the `ADDITIONAL_CA_CERT_BUNDLE` variable using `keytool`, which imports either a single certificate or a certificate chain. Multiple unrelated certificates are ignored and only the first one is imported by `keytool`. + +To add multiple unrelated certificates to the analyzer, you can declare a `before_script` such as this in the definition of the `gemnasium-maven-dependency_scanning` job: + +```yaml +gemnasium-maven-dependency_scanning: + before_script: + - . $HOME/.bashrc # make the java tools available to the script + - OIFS="$IFS"; IFS=""; echo $ADDITIONAL_CA_CERT_BUNDLE > multi.pem; IFS="$OIFS" # write ADDITIONAL_CA_CERT_BUNDLE variable to a PEM file + - csplit -z --digits=2 --prefix=cert multi.pem "/-----END CERTIFICATE-----/+1" "{*}" # split the file into individual certificates + - for i in `ls cert*`; do keytool -v -importcert -alias "custom-cert-$i" -file $i -trustcacerts -noprompt -storepass changeit -keystore /opt/asdf/installs/java/adoptopenjdk-11.0.7+10.1/lib/security/cacerts 1>/dev/null 2>&1 || true; done # import each certificate using keytool (note the keystore location is related to the Java version being used and should be changed accordingly for other versions) + - unset ADDITIONAL_CA_CERT_BUNDLE # unset the variable so that the analyzer doesn't duplicate the import +``` diff --git a/doc/user/application_security/img/mr_security_scanning_results_v14_3.png b/doc/user/application_security/img/mr_security_scanning_results_v14_3.png Binary files differnew file mode 100644 index 00000000000..3e0113dfb46 --- /dev/null +++ b/doc/user/application_security/img/mr_security_scanning_results_v14_3.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 50fd727b892..7b95769a81f 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -159,7 +159,9 @@ We recommended you run a scan of the `default` branch before enabling feature br The merge request security widget displays only a subset of the vulnerabilities in the generated JSON artifact because it contains both NEW and EXISTING findings. -From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. Select **View Full Report** to go directly to the **Security** tab in the latest branch pipeline. +From the merge request security widget, select **Expand** to unfold the widget, displaying any new and no longer detected (removed) findings by scan type. Select **View full report** to go directly to the **Security** tab in the latest branch pipeline. + + ## View security scan information in the pipeline Security tab @@ -221,7 +223,8 @@ For this approval group, you must set the number of approvals required to greate Follow these steps to enable `Vulnerability-Check`: -1. Go to your project and select **Settings > General**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. 1. Expand **Merge request approvals**. 1. Select **Enable** or **Edit**. 1. Set the **Security scanners** that the rule applies to. @@ -269,7 +272,7 @@ under your project's settings: ## DAST On-Demand Scans -If you don’t want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. +If you don't want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. ## Security report validation @@ -337,6 +340,16 @@ For more details about which findings or vulnerabilities you can view in each of ## Troubleshooting +### Secure job failing with exit code 1 + +If a Secure job is failing and it's unclear why, add `SECURE_LOG_LEVEL: "debug"` as a global CI/CD variable for +more verbose output that is helpful for troubleshooting. + +```yaml +variables: + SECURE_LOG_LEVEL: "debug" +``` + ### Outdated security reports When a security report generated for a merge request becomes outdated, the merge request shows a warning diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 3bf9d85cd0b..cdf54070d69 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -111,7 +111,7 @@ example of such a transfer: GitLab provides a [vendored template](../../../ci/yaml/index.md#includetemplate) to ease this process. -This template should be used in a new, empty project, with a `gitlab-ci.yml` file containing: +This template should be used in a new, empty project, with a `.gitlab-ci.yml` file containing: ```yaml include: diff --git a/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png b/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png Binary files differnew file mode 100644 index 00000000000..b21d0330b2f --- /dev/null +++ b/doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png diff --git a/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png Binary files differnew file mode 100644 index 00000000000..31d5eb57228 --- /dev/null +++ b/doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png diff --git a/doc/user/application_security/policies/img/policies_list_v14_3.png b/doc/user/application_security/policies/img/policies_list_v14_3.png Binary files differnew file mode 100644 index 00000000000..7a24860d4a7 --- /dev/null +++ b/doc/user/application_security/policies/img/policies_list_v14_3.png diff --git a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png Binary files differnew file mode 100644 index 00000000000..d04905eda59 --- /dev/null +++ b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png diff --git a/doc/user/application_security/policies/img/security_policy_project_v14_3.png b/doc/user/application_security/policies/img/security_policy_project_v14_3.png Binary files differnew file mode 100644 index 00000000000..5e3aefaeb81 --- /dev/null +++ b/doc/user/application_security/policies/img/security_policy_project_v14_3.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index 3d0135678b7..bd143d8608a 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -4,57 +4,189 @@ group: Container Security 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 --- -# Scan Policies **(ULTIMATE)** +# Policies **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. -> - Deployed behind a feature flag, disabled by default. -> - Disabled on GitLab.com. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5329) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. Deployed behind a feature flag, disabled by default. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/321258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 14.3. -Scan Policies in GitLab provide security teams a way to require scans of their choice to be run +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, +ask an administrator to [disable the `security_orchestration_policies_configuration` flag](../../../administration/feature_flags.md). +On GitLab.com, this feature is available. + +Policies in GitLab provide security teams a way to require scans of their choice to be run whenever a project pipeline runs according to the configuration specified. Security teams can therefore be confident that the scans they set up have not been changed, altered, or disabled. You -can access these by navigating to your project's **Security & Compliance > Scan Policies** page. +can access these by navigating to your project's **Security & Compliance > Policies** page. GitLab supports the following security policies: +- [Container Network Policy](#container-network-policy) - [Scan Execution Policy](#scan-execution-policy-schema) -WARNING: -Scan Policies is under development and is not ready for production use. It's deployed behind a -feature flag that's disabled by default. +## Policy management -NOTE: -We recommend using the [Security Policies project](#security-policies-project) -exclusively for managing policies for the project. Do not add your application's source code to such -projects. +The Policies page displays deployed +policies for all available environments. You can check a +policy's information (for example description, enforcement +status, etc.), and create and edit deployed policies: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. + + + +Network policies are fetched directly from the selected environment's +deployment platform while other policies are fetched from the project's +security policy project. Changes performed outside of this tab are +reflected upon refresh. + +By default, the policy list contains predefined network policies in a +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 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). + +## Policy editor + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. + +You can use the policy editor to create, edit, and delete policies: + +1. On the top bar, select **Menu > Projects** and find your group. +1. On the left sidebar, select **Security & Compliance > Policies**. + - To create a new policy, select **New policy** which is located in the **Policies** page's header. + - To edit an existing policy, select **Edit policy** in the selected policy drawer. + +The policy editor has two modes: + +- The visual _Rule_ mode allows you to construct and preview policy + rules using rule blocks and related controls. + +  + +- YAML mode allows you to enter a policy definition in `.yaml` format + and is aimed at expert users and cases that the Rule mode doesn't + support. + +  + +You can use both modes interchangeably and switch between them at any +time. If a YAML resource is incorrect or contains data not supported +by the Rule mode, Rule mode is automatically +disabled. If the YAML is incorrect, you must use YAML +mode to fix your policy before Rule mode is available again. -## Enable or disable scan policies +## Container Network Policy -Scan Policies is under development and is not ready for production use. It's deployed behind a -feature flag that's disabled by default. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it for your instance. Scan Policies can be enabled or disabled per-project. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -To enable it: +The **Container Network Policy** section provides packet flow metrics for +your application's Kubernetes namespace. This section has the following +prerequisites: -```ruby -# Instance-wide -Feature.enable(:security_orchestration_policies_configuration) -# or by project -Feature.enable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +- Your project contains at least one [environment](../../../ci/environments/index.md). +- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium). +- You've configured the [Prometheus service](../../project/integrations/prometheus.md#enabling-prometheus-integration). + +If you're using custom Helm values for Cilium, you must enable Hubble +with flow metrics for each namespace by adding the following lines to +your [Cilium values](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium): + +```yaml +hubble: + enabled: true + metrics: + enabled: + - 'flow:sourceContext=namespace;destinationContext=namespace' ``` -To disable it: +The **Container Network Policy** section displays the following information +about your packet flow: + +- The total amount of the inbound and outbound packets +- The proportion of packets dropped according to the configured + policies +- The per-second average rate of the forwarded and dropped packets + accumulated over time window for the requested time interval -```ruby -# Instance-wide -Feature.disable(:security_orchestration_policies_configuration) -# or by project -Feature.disable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +If a significant percentage of packets is dropped, you should +investigate it for potential threats by +examining the Cilium logs: + +```shell +kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor ``` +### Change the enforcement status + +To change a network policy's enforcement status: + +- Select the network policy you want to update. +- Select **Edit policy**. +- Select the **Policy status** toggle to update the selected policy. +- Select **Save changes** to deploy network policy changes. + +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 + +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. + +Rule mode supports the following rule types: + +- [Labels](https://docs.cilium.io/en/v1.8/policy/language/#labels-based). +- [Entities](https://docs.cilium.io/en/v1.8/policy/language/#entities-based). +- [IP/CIDR](https://docs.cilium.io/en/v1.8/policy/language/#ip-cidr-based). Only + the `toCIDR` block without `except` is supported. +- [DNS](https://docs.cilium.io/en/v1.8/policy/language/#dns-based). +- [Level 4](https://docs.cilium.io/en/v1.8/policy/language/#layer-4-examples) + can be added to all other rules. + +Once your policy is complete, save it by selecting **Save policy** +at the bottom of the editor. Existing policies can also be +removed from the editor interface by selecting **Delete policy** +at the bottom of the editor. + +### Configure a Network Policy Alert + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. + +You can use policy alerts to track your policy's impact. Alerts are only available if you've +[installed](../../clusters/agent/repository.md) +and [configured](../../clusters/agent/index.md#create-an-agent-record-in-gitlab) +a Kubernetes Agent for this project. + +There are two ways to create policy alerts: + +- In the [policy editor UI](#container-network-policy-editor), + by clicking **Add alert**. +- In the policy editor's YAML mode, through the `metadata.annotations` property: + + ```yaml + metadata: + annotations: + app.gitlab.com/alert: 'true' + ``` + +Once added, the UI updates and displays a warning about the dangers of too many alerts. + ## Security Policies project +NOTE: +We recommend using the [Security Policies project](#security-policies-project) +exclusively for managing policies for the project. Do not add your application's source code to such +projects. + The Security Policies feature is a repository to store policies. All security policies are stored as the `.gitlab/security-policies/policy.yml` YAML file with this format: @@ -85,6 +217,40 @@ scan_execution_policy: site_profile: Site Profile D ``` +## Security Policy project selection + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +When the Security Policy project is created and policies are created within that repository, you +must create an association between that project and the project you want to apply policies to: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Policies**. +1. Select **Edit Policy Project**, and search for and select the + project you would like to link from the dropdown menu. +1. Select **Save**. + +  + +### Scan Execution Policy editor + +NOTE: +Only project Owners have the [permissions](../../permissions.md#project-members-permissions) +to select Security Policy Project. + +Once your policy is complete, save it by selecting **Create merge request** +at the bottom of the editor. You will be redirected to the merge request on the project's +configured security policy project. If one does not link to your project, a security +policy project will be automatically created. Existing policies can also be +removed from the editor interface by selecting **Delete policy** +at the bottom of the editor. + + + +The policy editor currently only supports the YAML mode. The Rule mode is tracked in the [Allow Users to Edit Rule-mode Scan Execution Policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363) epic. + ### Scan Execution Policies Schema The YAML file with Scan Execution Policies consists of an array of objects matching Scan Execution Policy Schema nested under the `scan_execution_policy` key. You can configure a maximum of 5 policies under the `scan_execution_policy` key. @@ -121,6 +287,16 @@ This rule enforces the defined actions and schedules a scan on the provided date | `type` | `string` | `schedule` | The rule's type. | | `branches` | `array` of `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | | `cadence` | `string` | CRON expression (for example, `0 0 * * *`) | A whitespace-separated string containing five fields that represents the scheduled time. | +| `clusters` | `object` | | The cluster where the given policy will enforce running selected scans (only for `container_scanning`/`cluster_image_scanning` scans). The key of the object is the name of the Kubernetes cluster configured for your project in GitLab. In the optionally provided value of the object, you can precisely select Kubernetes resources that will be scanned. | + +#### `cluster` schema + +| Field | Type | Possible values | Description | +|--------------|---------------------|--------------------------|-------------| +| `containers` | `array` of `string` | | The container name that will be scanned (only the first value is currently supported). | +| `resources` | `array` of `string` | | The resource name that will be scanned (only the first value is currently supported). | +| `namespaces` | `array` of `string` | | The namespace that will be scanned (only the first value is currently supported). | +| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind that should be scanned (only the first value is currently supported). | ### `scan` action type @@ -149,6 +325,9 @@ Note the following: - A secret detection scan runs in `normal` mode when executed as part of a pipeline, and in [`historic`](../secret_detection/index.md#full-history-secret-scan) mode when executed as part of a scheduled scan. +- A container scanning and cluster image scanning scans configured for the `pipeline` rule type will ignore the cluster defined in the `clusters` object. + They will use predefined CI/CD variables defined for your project. Cluster selection with the `clusters` object is supported for the `schedule` rule type. + Cluster with name provided in `clusters` object must be created and configured for the project. To be able to successfully perform the `container_scanning`/`cluster_image_scanning` scans for the cluster you must follow instructions for the [Cluster Image Scanning feature](../cluster_image_scanning/index.md#prerequisites). Here's an example: @@ -179,8 +358,8 @@ scan_execution_policy: scanner_profile: Scanner Profile C site_profile: Site Profile D - scan: secret_detection -- name: Enforce Secret Detection in every default branch pipeline - description: This policy enforces pipeline configuration to have a job with Secret Detection scan for the default branch +- name: Enforce Secret Detection and Container Scanning in every default branch pipeline + description: This policy enforces pipeline configuration to have a job with Secret Detection and Container Scanning scans for the default branch enabled: true rules: - type: pipeline @@ -188,6 +367,25 @@ scan_execution_policy: - main actions: - scan: secret_detection + - scan: container_scanning +- name: Enforce Cluster Image Scanning on production-cluster every 24h + description: This policy enforces Cluster Image Scanning scan to run every 24 hours + enabled: true + rules: + - type: schedule + cadence: '15 3 * * *' + clusters: + production-cluster: + containers: + - database + resources: + - production-application + namespaces: + - production-namespace + kinds: + - deployment + actions: + - scan: cluster_image_scanning ``` In this example: @@ -196,22 +394,9 @@ In this example: `release/v1.2.1`), DAST scans run with `Scanner Profile A` and `Site Profile B`. - DAST and secret detection scans run every 10 minutes. The DAST scan runs with `Scanner Profile C` and `Site Profile D`. -- Secret detection scans run for every pipeline executed on the `main` branch. - -## Security Policy project selection - -When the Security Policy project is created and policies are created within that repository, you -must create an association between that project and the project you want to apply policies to. To do -this, navigate to your project's **Security & Compliance > Policies**, select -**Security policy project** from the dropdown menu, then select the **Create policy** button to save -changes. - -You can always change the **Security policy project** by navigating to your project's -**Security & Compliance > Policies** and modifying the selected project. - -NOTE: -Only project Owners have the [permissions](../../permissions.md#project-members-permissions) -to select Security Policy Project. +- Secret detection and container scanning scans run for every pipeline executed on the `main` branch. +- Cluster Image Scanning scan runs every 24h. The scan runs on the `production-cluster` cluster and fetches vulnerabilities + from the container with the name `database` configured for deployment with the name `production-application` in the `production-namespace` namespace. ## Roadmap diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 661a4ee8e82..d399dcaf4a9 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -65,8 +65,8 @@ Any custom change to the official analyzers can be achieved by using a You can switch to a custom Docker registry that provides the official analyzer images under a different prefix. For instance, the following instructs -SAST to pull `my-docker-registry/gl-images/bandit` -instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/bandit`. +SAST to pull `my-docker-registry/gl-images/sast/bandit` +instead of `registry.gitlab.com/security-products/sast/bandit`. In `.gitlab-ci.yml` define: ```yaml diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 6e88f38d900..3caa1771a5b 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -361,6 +361,9 @@ To create a custom ruleset: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292686) in GitLab 14.2. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the `vulnerability_flags` flag](../../../administration/feature_flags.md). On GitLab.com, this feature is available. + Vulnerabilities that have been detected and are false positives will be flagged as false positives in the security dashboard. ### Using CI/CD variables to pass credentials for private repositories @@ -669,19 +672,19 @@ import the following default SAST analyzer images from `registry.gitlab.com` int [local Docker container registry](../../packages/container_registry/index.md): ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/bandit:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/brakeman:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/eslint:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/flawfinder:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/gosec:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/kubesec:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/pmd-apex:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/security-code-scan:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/sobelow:2 -registry.gitlab.com/gitlab-org/security-products/analyzers/spotbugs:2 +registry.gitlab.com/security-products/sast/bandit:2 +registry.gitlab.com/security-products/sast/brakeman:2 +registry.gitlab.com/security-products/sast/eslint:2 +registry.gitlab.com/security-products/sast/flawfinder:2 +registry.gitlab.com/security-products/sast/gosec:3 +registry.gitlab.com/security-products/sast/kubesec:2 +registry.gitlab.com/security-products/sast/nodejs-scan:2 +registry.gitlab.com/security-products/sast/phpcs-security-audit:2 +registry.gitlab.com/security-products/sast/pmd-apex:2 +registry.gitlab.com/security-products/sast/security-code-scan:2 +registry.gitlab.com/security-products/sast/semgrep:2 +registry.gitlab.com/security-products/sast/sobelow:2 +registry.gitlab.com/security-products/sast/spotbugs:2 ``` The process for importing Docker images into a local offline Docker registry depends on diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index b6ff68c861b..cd1014d36a6 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -35,7 +35,7 @@ GitLab displays identified secrets visibly in a few places: Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). -The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes the following key types: +The [default ruleset provided by TruffleHog and Gitleaks](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes the following key types: - Cloud services: - Amazon Web Services (AWS) @@ -89,12 +89,13 @@ However not all features are available on every tier. See the breakdown below fo Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Free | In Ultimate | +| Capability | In Free & Premium | In Ultimate | |:----------------------------------------------------------------|:--------------------|:-------------------| | [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | | View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | | Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | +| View identified secrets in the pipelines' **Security** tab | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | @@ -330,7 +331,7 @@ Import the following default Secret Detection analyzer images from `registry.git [local Docker container registry](../../packages/container_registry/index.md): ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:3 +registry.gitlab.com/security-products/secret-detection:3 ``` The process for importing Docker images into a local offline Docker registry depends on diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png Binary files differindex 3a195a5ce8d..52249cef343 100644 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_2.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index b799177ec5a..c78179e9693 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -46,7 +46,7 @@ The security dashboard and vulnerability report displays information about vulne ## Pipeline Security -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3. At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline ran against. @@ -64,7 +64,7 @@ the analyzer outputs an ### Scan details -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10. The **Scan details** section lists the scans run in the pipeline and the total number of vulnerabilities per scan. For the DAST scan, select **Download scanned resources** to download a @@ -104,7 +104,7 @@ To download an SVG image of the chart, select **Save chart to an image** (**{dow ## Group Security Dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in GitLab 11.5. The group Security Dashboard gives an overview of the vulnerabilities found in the default branches of the projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** @@ -139,7 +139,7 @@ Navigate to the group's [vulnerability report](../vulnerability_report/index.md) ## Security Center -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in GitLab 13.4. The Security Center is personal space where you manage vulnerabilities across all your projects. It displays the vulnerabilities present in the default branches of all the projects you configure. It includes @@ -166,22 +166,17 @@ To add projects to the Security Center: After you add projects, the security dashboard and vulnerability report display the vulnerabilities found in those projects' default branches. -## Keeping the dashboards up to date +## Keep dashboards up to date -The Security Dashboard displays information from the results of the most recent -security scan on the [default branch](../../project/repository/branches/default.md), -which means that security scans are performed every time the branch is updated. - -If the default branch is updated infrequently, scans are run infrequently and the -information on the Security Dashboard can become outdated as new vulnerabilities -are discovered. +The Security Dashboard displays results of the most recent security scan on the +[default branch](../../project/repository/branches/default.md). By default, security scans are run +only when the default branch is updated. Information on the Security Dashboard may not reflect +newly-discovered vulnerabilities. To ensure the information on the Security Dashboard is regularly updated, -[configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a -daily security scan. This updates the information displayed on the Security -Dashboard regardless of how often the default branch is updated. - -That way, reports are created even if no code change happens. +[configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a daily security scan. +This updates the information displayed on the Security Dashboard regardless of how often the default +branch is updated. WARNING: Running Dependency Scanning from a scheduled pipeline might result in false negatives if your @@ -191,12 +186,6 @@ can occur because the dependency version resolved during the scan might differ f resolved when your project was built and released, in a previous pipeline. Java projects can't have lock files. Python projects can have lock files, but GitLab Secure tools don't support them. -## Security scans using Auto DevOps - -When using [Auto DevOps](../../../topics/autodevops/index.md), use -[special environment variables](../../../topics/autodevops/customize.md#cicd-variables) -to configure daily security scans. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index c96497e9233..8277c30b81f 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -38,6 +38,12 @@ The different places in an application that are vulnerable to attack. Secure pro search the attack surface during scans. Each product defines the attack surface differently. For example, SAST uses files and line numbers, and DAST uses URLs. +### Corpus + +The set of meaningful test cases that are generated while the fuzzer is running. Each meaningful +test case produces new coverage in the tested program. It's advised to re-use the corpus and pass it +to subsequent runs. + ### CVE Common Vulnerabilities and Exposures (CVE®) is a list of common identifiers for publicly known @@ -142,6 +148,12 @@ A standard report format that Secure products comply with when creating JSON rep Provides an overview of all the vulnerabilities for a project, group, or GitLab instance. Vulnerabilities are only created from findings discovered on the project's default branch. +### Seed corpus + +The set of test cases given as initial input to the fuzz target. This usually speeds up the fuzz +target substantially. This can be either manually created test cases or auto-generated with the fuzz +target itself from previous runs. + ### Vendor The party maintaining an analyzer. As such, a vendor is responsible for integrating a scanner into diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png Binary files differdeleted file mode 100644 index e165c7e6ceb..00000000000 --- a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png +++ /dev/null diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v14_3.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v14_3.png Binary files differnew file mode 100644 index 00000000000..a11a7fafc4a --- /dev/null +++ b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v14_3.png diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 8cecb9c5929..79f202a6edb 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. -The **Threat Monitoring** page provides metrics and policy management +The **Threat Monitoring** page provides alerts and metrics for the GitLab application runtime security features. You can access these by navigating to your project's **Security & Compliance > Threat Monitoring** page. @@ -18,153 +18,7 @@ GitLab supports statistics for the following security features: - [Container Network Policies](../../../topics/autodevops/stages.md#network-policy) -## Container Network Policy - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. - -The **Container Network Policy** section provides packet flow metrics for -your application's Kubernetes namespace. This section has the following -prerequisites: - -- Your project contains at least one [environment](../../../ci/environments/index.md) -- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium) -- You've configured the [Prometheus service](../../project/integrations/prometheus.md#enabling-prometheus-integration) - -If you're using custom Helm values for Cilium, you must enable Hubble -with flow metrics for each namespace by adding the following lines to -your [Cilium values](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium): - -```yaml -hubble: - enabled: true - metrics: - enabled: - - 'flow:sourceContext=namespace;destinationContext=namespace' -``` - -The **Container Network Policy** section displays the following information -about your packet flow: - -- The total amount of the inbound and outbound packets -- The proportion of packets dropped according to the configured - policies -- The per-second average rate of the forwarded and dropped packets - accumulated over time window for the requested time interval - -If a significant percentage of packets is dropped, you should -investigate it for potential threats by -examining the Cilium logs: - -```shell -kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor -``` - -## Container Network Policy management - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3328) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. - -The **Threat Monitoring** page's **Policy** tab displays deployed -network policies for all available environments. You can check a -network policy's `yaml` manifest, its enforcement -status, and create and edit deployed policies. This section has the -following prerequisites: - -- Your project contains at least one [environment](../../../ci/environments/index.md) -- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium) - -Network policies are fetched directly from the selected environment's -deployment platform. Changes performed outside of this tab are -reflected upon refresh. - -By default, the network policy list contains predefined policies in a -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 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 - -To change a network policy's enforcement status: - -- Click the network policy you want to update. -- Click the **Edit policy** button. -- Click the **Policy status** toggle to update the selected policy. -- Click the **Save changes** button to deploy network policy changes. - -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 - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3403) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. - -You can use the policy editor to create, edit, and delete policies. - -- To 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. - -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. - -The policy editor has two modes: - -- The visual _Rule_ mode allows you to construct and preview policy - rules using rule blocks and related controls. -- YAML mode allows you to enter a policy definition in `.yaml` format - and is aimed at expert users and cases that the Rule mode doesn't - support. - -You can use both modes interchangeably and switch between them at any -time. If a YAML resource is incorrect, Rule mode is automatically -disabled. You must use YAML mode to fix your policy before Rule mode -is available again. - -Rule mode supports the following rule types: - -- [Labels](https://docs.cilium.io/en/v1.8/policy/language/#labels-based). -- [Entities](https://docs.cilium.io/en/v1.8/policy/language/#entities-based). -- [IP/CIDR](https://docs.cilium.io/en/v1.8/policy/language/#ip-cidr-based). Only - the `toCIDR` block without `except` is supported. -- [DNS](https://docs.cilium.io/en/v1.8/policy/language/#dns-based). -- [Level 4](https://docs.cilium.io/en/v1.8/policy/language/#layer-4-examples) - can be added to all other rules. - -Once your policy is complete, save it by pressing the **Save policy** -button at the bottom of the editor. Existing policies can also be -removed from the editor interface by clicking the **Delete policy** -button at the bottom of the editor. - -### Configuring Network Policy Alerts - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. -> - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. - -You can use policy alerts to track your policy's impact. Alerts are only available if you've -[installed](../../clusters/agent/repository.md) -and [configured](../../clusters/agent/index.md#create-an-agent-record-in-gitlab) -a Kubernetes Agent for this project. - -There are two ways to create policy alerts: - -- In the [policy editor UI](#container-network-policy-editor), - by clicking **Add alert**. -- In the policy editor's YAML mode, through the `metadata.annotations` property: - - ```yaml - metadata: - annotations: - app.gitlab.com/alert: 'true' - ``` - -Once added, the UI updates and displays a warning about the dangers of too many alerts. - -### Container Network Policy Alert list +## Container Network Policy Alert list > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. @@ -184,7 +38,7 @@ the selector menu in the **Status** column to set the status for each alert: By default, the list doesn't display resolved or dismissed alerts. - + Clicking an alert's row opens the alert drawer, which shows more information about the alert. A user can also create an incident from the alert and update the alert status in the alert drawer. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index a727dc88ffc..9ebecc67704 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -37,7 +37,9 @@ A vulnerability's status can be one of the following: | Detected | The default state for a newly discovered vulnerability. | | Confirmed | A user has seen this vulnerability and confirmed it to be accurate. | | Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. | -| Resolved | The vulnerability has been fixed and is no longer valid. | +| Resolved | The vulnerability has been fixed or is no longer present. | + +Dismissed vulnerabilities are ignored if detected in subsequent scans. Resolved vulnerabilities that are reintroduced and detected by subsequent scans have a _new_ vulnerability record created. When an existing vulnerability is no longer detected in a project's `default` branch, you should change its status to Resolved. This ensures that if it is accidentally reintroduced in a future merge, it will be visible again as a new record. You can use the [Activity filter](../vulnerability_report/#activity-filter) to select all vulnerabilities that are no longer detected, and [change their status](../vulnerability_report#change-status-of-multiple-vulnerabilities). ## Change vulnerability status diff --git a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png Binary files differindex 193efe9c386..44c689eda3e 100644 --- a/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png +++ b/doc/user/application_security/vulnerability_report/img/group_vulnerability_report_v14_2.png diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png Binary files differindex 056e051363d..a43340544ca 100644 --- a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v14_2.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index c2c2e7459ba..8b811c62ec3 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -145,6 +145,17 @@ To change the status of vulnerabilities in the table:  +### Change status of multiple vulnerabilities + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. + +You can change the status of multiple vulnerabilities at once: + +1. In the list of vulnerabilities, select the checkbox for each vulnerability you want to update. + To select all, select the checkbox in the table header. +1. Above the table, select a new status. +1. Click **Change status** to save. + ## Export vulnerability details > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in the Security Center (previously known as the Instance Security Dashboard) and project-level Vulnerability Report (previously known as the Project Security Dashboard) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. @@ -191,14 +202,3 @@ You can dismiss a vulnerability for the entire project: 1. Optional. Add a reason for the dismissal and select **Save comment**. To undo this action, select a different status from the same menu. - -### Dismiss multiple vulnerabilities - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35816) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. - -You can dismiss multiple vulnerabilities at once: - -1. In the list of vulnerabilities, select the checkbox for each vulnerability you want to dismiss. - To select all, select the checkbox in the table header. -1. Above the table, select a dismissal reason. -1. Select **Dismiss Selected**. |
