diff options
Diffstat (limited to 'doc/user/application_security/index.md')
| -rw-r--r-- | doc/user/application_security/index.md | 321 |
1 files changed, 188 insertions, 133 deletions
diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 7b95769a81f..d5e801ced9c 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -31,19 +31,20 @@ For an overview of GitLab application security, see [Shifting Security Left](htt GitLab uses the following tools to scan and report known vulnerabilities found in your project. -| Secure scanning tool | Description | -|:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------| -| [Container Scanning](container_scanning/index.md) **(ULTIMATE)** | Scan Docker containers for known vulnerabilities. | -| [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | -| [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | -| [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | -| [DAST API](dast_api/index.md) **(ULTIMATE)** | Analyze running web APIs for known vulnerabilities. | -| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | -| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | -| [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | -| [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | -| [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | -| [Cluster Image Scanning](cluster_image_scanning/index.md) **(ULTIMATE)** | Scan Kubernetes clusters for known vulnerabilities. | +| Secure scanning tool | Description | +| :------------------------------------------------------------- | :------------------------------------------------------------------ | +| [Container Scanning](container_scanning/index.md) | Scan Docker containers for known vulnerabilities. | +| [Dependency List](dependency_list/index.md) | View your project's dependencies and their known vulnerabilities. | +| [Dependency Scanning](dependency_scanning/index.md) | Analyze your dependencies for known vulnerabilities. | +| [Dynamic Application Security Testing (DAST)](dast/index.md) | Analyze running web applications for known vulnerabilities. | +| [DAST API](dast_api/index.md) | Analyze running web APIs for known vulnerabilities. | +| [API fuzzing](api_fuzzing/index.md) | Find unknown bugs and vulnerabilities in web APIs with fuzzing. | +| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. | +| [Security Dashboard](security_dashboard/index.md) | View vulnerabilities in all your projects and groups. | +| [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | +| [Infrastructure as Code (IaC) Scanning](iac_scanning/index.md) | Analyze your IaC coniguration files for known vulnerabilities. | +| [Coverage fuzzing](coverage_fuzzing/index.md) | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | +| [Cluster Image Scanning](cluster_image_scanning/index.md) | Scan Kubernetes clusters for known vulnerabilities. | ## Security scanning with Auto DevOps @@ -185,61 +186,51 @@ By default, the vulnerability report does not show vulnerabilities of `dismissed ## Security approvals in merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in GitLab 12.2. -You can implement merge request approvals to require approval by selected users or a group when a -merge request would introduce one of the following security issues: +You can enforce an additional approval for merge requests that would introduce one of the following +security issues: -- A security vulnerability -- A software license compliance violation +- A security vulnerability. For more details, read + [Vulnerability-Check rule](#vulnerability-check-rule). +- A software license compliance violation. For more details, read + [Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). -When the Vulnerability-Check merge request rule is enabled, additional merge request approval +### Vulnerability-Check rule + +To prevent a merge request introducing a security vulnerability in a project, enable the +Vulnerability-Check rule. While this rule is enabled, additional merge request approval by +[eligible approvers](../project/merge_requests/approvals/rules.md#eligible-approvers) is required when the latest security report in a merge request: -- Contains vulnerabilities that are not present in the - target branch. Note that approval is still required for dismissed vulnerabilities. +- Contains vulnerabilities with states (for example, `previously detected`, `dismissed`) matching the rule's vulnerability states. Only `newly detected` will be considered if the target branch differs from the project default branch. - Contains vulnerabilities with severity levels (for example, `high`, `critical`, or `unknown`) matching the rule's severity levels. - Contains a vulnerability count higher than the rule allows. -- Is not generated during pipeline execution. +- Is not yet generated (until pipeline completion). An approval is optional when the security report: -- Contains no new vulnerabilities when compared to the target branch. +- Contains only vulnerabilities with states (for example, `newly detected`, `resolved`) **NOT** matching the rule's vulnerability states. - Contains only vulnerabilities with severity levels (for example, `low`, `medium`) **NOT** matching the rule's severity levels. - Contains a vulnerability count equal to or less than what the rule allows. -When the License-Check merge request rule is enabled, additional approval is required if a merge -request contains a denied license. For more details, see [Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). - -### Enable the Vulnerability-Check rule - -Prerequisites: - -- Maintainer or Owner [role](../permissions.md#project-members-permissions). +Project members assigned [at least the Maintainer role](../permissions.md#project-members-permissions) can enable or edit +the Vulnerability-Check rule. -For this approval group, you must set the number of approvals required to greater than zero. +#### Enable the Vulnerability-Check rule -Follow these steps to enable `Vulnerability-Check`: +To enable or edit the Vulnerability-Check rule: 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. -1. Select the **Target branch**. -1. Set the **Vulnerabilities allowed** to the number of vulnerabilities allowed before the rule is - triggered. -1. Set the **Severity levels** to the severity levels that the rule applies to. -1. Set the **Approvals required** to the number of approvals that the rule requires. -1. Select the users or groups to provide approval. +1. Select **Activate** or **Edit** of the Vulnerability-Check. +1. Complete the fields. **Approvals required** must be at least 1. 1. Select **Add approval rule**. -Once this group is added to your project, the approval rule is enabled for all merge requests. -Any code changes cause the approvals required to reset. - - +The approval rule is enabled for all merge requests. Any code changes reset the approvals required. ## Using private Maven repositories @@ -270,28 +261,44 @@ under your project's settings: </settings> ``` -## DAST On-Demand Scans +## Using a custom scanning stage -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. +When security scanning is enabled by including CI/CD templates as described in the +[Security scanning without Auto DevOps](#security-scanning-without-auto-devops) section, the scanning jobs +use the predefined `test` stage by default. If you specify a custom stage in your `.gitlab-ci.yml` file without +including a `test` stage, an error occurs. -## Security report validation +For example, the following attempts to use a `unit-tests` stage: -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. -> - Schema validation message [added](https://gitlab.com/gitlab-org/gitlab/-/issues/321730) in GitLab 14.0. +```yaml +include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml -You can optionally enable validation of the security report artifacts based on the -[report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/tree/master/dist). -If you enable validation, GitLab validates the report artifacts before ingesting the vulnerabilities. -This prevents ingestion of broken vulnerability data into the database. +stages: + - unit-tests -In GitLab 14.0 and later, the pipeline's **Security** tab lists any report artifacts -that failed validation. Security report validation must first be enabled. +custom job: + stage: unit-tests + script: + - echo "custom job" +``` -### Enable security report validation +The above `.gitlab-ci.yml` causes a linting error: -To enable report artifacts validation, set the `VALIDATE_SCHEMA` environment variable to `"true"` for the jobs in the `.gitlab-ci.yml` file. +```plaintext +Found errors in your .gitlab-ci.yml: +- dependency_scanning job: chosen stage does not exist; available stages are .pre +- unit-tests +- .post +``` + +This error appears because the `test` stage used by the security scanning jobs isn't declared in the `.gitlab-ci.yml` file. +To fix this issue, you can either: -For example, the configuration below enables validation for only the `sast` job: +- Add a `test` stage in your `.gitlab-ci.yml`: ```yaml include: @@ -301,26 +308,98 @@ For example, the configuration below enables validation for only the `sast` job: - template: Security/Secret-Detection.gitlab-ci.yml stages: - - security-scan + - test + - unit-tests + + custom job: + stage: unit-tests + script: + - echo "custom job" + ``` + +- Override the default stage of each security job. For example, to use a pre-defined stage named `unit-tests`: + + ```yaml + include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml + + stages: + - unit-tests dependency_scanning: - stage: security-scan + stage: unit-tests license_scanning: - stage: security-scan + stage: unit-tests sast: - stage: security-scan - variables: - VALIDATE_SCHEMA: "true" + stage: unit-tests .secret-analyzer: - stage: security-scan + stage: unit-tests + + custom job: + stage: unit-tests + script: + - echo "custom job" ``` -## Interacting with findings and vulnerabilities +Learn more on overriding security jobs: + +- [Overriding SAST jobs](sast/index.md#overriding-sast-jobs). +- [Overriding Dependency Scanning jobs](dependency_scanning/index.md#overriding-dependency-scanning-jobs). +- [Overriding Container Scanning jobs](container_scanning/index.md#overriding-the-container-scanning-template). +- [Overriding Secret Detection jobs](secret_detection/index.md#customizing-settings). +- [Overriding DAST jobs](dast/index.md#customize-dast-settings). +- [Overriding License Compliance jobs](../compliance/license_compliance/index.md#overriding-the-template). + +All the security scanning tools define their stage, so this error can occur with all of them. + +## Security report validation + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. +> - Schema validation message [added](https://gitlab.com/gitlab-org/gitlab/-/issues/321730) in GitLab 14.0. + +You can enforce validation of the security report artifacts before ingesting the vulnerabilities. +This prevents ingestion of broken vulnerability data into the database. GitLab validates the +artifacts based on the [report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/tree/master/dist). + +In GitLab 14.0 and later, when artifact validation is enabled, the pipeline's **Security** tab lists +any report artifacts that failed validation. + +### Enable security report validation + +To enable report artifacts validation, set the `VALIDATE_SCHEMA` environment variable to `"true"` +for the desired jobs in the `.gitlab-ci.yml` file. -There are a variety of locations and ways to interact with the results of the security scanning tools: +For example, to enable validation for only the `sast` job: + +```yaml +include: + - template: Security/Dependency-Scanning.gitlab-ci.yml + - template: Security/License-Scanning.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - template: Security/Secret-Detection.gitlab-ci.yml +stages: + - security-scan +dependency_scanning: + stage: security-scan +license_scanning: + stage: security-scan +sast: + stage: security-scan + variables: + VALIDATE_SCHEMA: "true" +.secret-analyzer: + stage: security-scan +``` + +## Interact with findings and vulnerabilities + +You can interact with the results of the security scanning tools in several locations: - [Scan information in merge requests](#view-security-scan-information-in-merge-requests) - [Project Security Dashboard](security_dashboard/#project-security-dashboard) @@ -331,13 +410,33 @@ There are a variety of locations and ways to interact with the results of the se - [Vulnerability Pages](vulnerabilities/index.md) - [Dependency List](dependency_list/index.md) -For more details about which findings or vulnerabilities you can view in each of those locations, select the respective link. Each page details the ways in which you can interact with the findings and vulnerabilities. As an example, in most cases findings start out as _detected_ status. You have the option to: +For more details about which findings or vulnerabilities you can view in each of those locations, +select the respective link. Each page details the ways in which you can interact with the findings +and vulnerabilities. As an example, in most cases findings start out as _detected_ status. + +You have the option to: - Change the status. - Create an issue. - Link it to an existing issue. - [Resolve the vulnerability](vulnerabilities/index.md#resolve-a-vulnerability), if a solution is known. +## Security scanning configuration tips + +Each GitLab security scanning tool has a default +[CI/CD configuration file](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Security), +also known as a _template_. + +When customizing the configuration: + +- [Include](../../ci/yaml/index.md#include) the scanning tool's CI/CD template. Don't _copy_ the content + of the template. +- Use the [stable](../../development/cicd/templates.md#stable-version) version of each template + for production workflows. The stable version changes less often, and breaking changes are only + made between major GitLab versions. The [latest](../../development/cicd/templates.md#latest-version) + version contains the most recent changes, but may have significant changes between minor GitLab versions. +- Only override values in the template as needed. All other values are inherited from the template. + ## Troubleshooting ### Secure job failing with exit code 1 @@ -352,8 +451,8 @@ variables: ### Outdated security reports -When a security report generated for a merge request becomes outdated, the merge request shows a warning -message in the security widget and prompts you to take an appropriate action. +When a security report generated for a merge request becomes outdated, the merge request shows a +warning message in the security widget and prompts you to take an appropriate action. This can happen in two scenarios: @@ -362,73 +461,28 @@ This can happen in two scenarios: #### Source branch is behind the target branch -This means the most recent common ancestor commit between the target branch and the source branch is -not the most recent commit on the target branch. This is by far the most common situation. +A security report can be out of date when the most recent common ancestor commit between the +target branch and the source branch is not the most recent commit on the target branch. -In this case you must rebase or merge to incorporate the changes from the target branch. +To fix this issue, rebase or merge to incorporate the changes from the target branch.  #### Target branch security report is out of date -This can happen for many reasons, including failed jobs or new advisories. When the merge request shows that a -security report is out of date, you must run a new pipeline on the target branch. -You can do it quickly by following the hyperlink given to run a new pipeline. +This can happen for many reasons, including failed jobs or new advisories. When the merge request +shows that a security report is out of date, you must run a new pipeline on the target branch. +Select **new pipeline** to run a new pipeline.  -### Getting error message `sast job: stage parameter should be [some stage name here]` - -When [including](../../ci/yaml/index.md#includetemplate) a `.gitlab-ci.yml` template -like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), -the following error may occur, depending on your GitLab CI/CD configuration: - -```plaintext -Found errors in your .gitlab-ci.yml: - -* sast job: stage parameter should be unit-tests -``` - -This error appears when the included job's stage (named `test`) isn't declared in `.gitlab-ci.yml`. -To fix this issue, you can either: - -- Add a `test` stage in your `.gitlab-ci.yml`. -- Override the default stage of each security job. For example, to use a pre-defined stage name `unit-tests`: - - ```yaml - include: - - template: Security/Dependency-Scanning.gitlab-ci.yml - - template: Security/License-Scanning.gitlab-ci.yml - - template: Security/SAST.gitlab-ci.yml - - template: Security/Secret-Detection.gitlab-ci.yml - - stages: - - unit-tests - - dependency_scanning: - stage: unit-tests - - license_scanning: - stage: unit-tests - - sast: - stage: unit-tests - - .secret-analyzer: - stage: unit-tests - ``` - -[Learn more on overriding SAST jobs](sast/index.md#overriding-sast-jobs). -All the security scanning tools define their stage, so this error can occur with all of them. - ### Getting warning messages `… report.json: no matching files` -This is often followed by the [error `No files to upload`](../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload), -and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Please -check the entire job log for such messages. If you don't find these messages, retry the failed job -after setting `SECURE_LOG_LEVEL: "debug"` as a -[custom CI/CD variable](../../ci/variables/index.md#custom-cicd-variables). -This provides useful information to investigate further. +This message is often followed by the [error `No files to upload`](../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload), +and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Check +the entire job log for such messages. If you don't find these messages, retry the failed job after +setting `SECURE_LOG_LEVEL: "debug"` as a [custom CI/CD variable](../../ci/variables/index.md#custom-cicd-variables). +This provides extra information to investigate further. ### Getting error message `sast job: config key may not be used with 'rules': only/except` @@ -526,23 +580,24 @@ involve pinning to the previous template versions, for example: ``` Additionally, we provide a dedicated project containing the versioned legacy templates. -This can be useful for offline setups or anyone wishing to use [Auto DevOps](../../topics/autodevops/index.md). +This can be used for offline setups or anyone wishing to use [Auto DevOps](../../topics/autodevops/index.md). Instructions are available in the [legacy template project](https://gitlab.com/gitlab-org/auto-devops-v12-10). #### Vulnerabilities are found, but the job succeeds. How can I have a pipeline fail instead? -This is the current default behavior, because the job's status indicates success or failure of the analyzer itself. -Analyzer results are displayed in the [job logs](../../ci/jobs/index.md#expand-and-collapse-job-log-sections), -[Merge Request widget](#view-security-scan-information-in-merge-requests) -or [Security Dashboard](security_dashboard/index.md). +In these circumstances, that the job succeeds is the default behavior. The job's status indicates +success or failure of the analyzer itself. Analyzer results are displayed in the +[job logs](../../ci/jobs/index.md#expand-and-collapse-job-log-sections), +[Merge Request widget](#view-security-scan-information-in-merge-requests) or +[Security Dashboard](security_dashboard/index.md). ### Error: job `is used for configuration only, and its script should not be executed` [Changes made in GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41260) to the `Security/Dependency-Scanning.gitlab-ci.yml` and `Security/SAST.gitlab-ci.yml` templates mean that if you enable the `sast` or `dependency_scanning` jobs by setting the `rules` attribute, -they will fail with the error `(job) is used for configuration only, and its script should not be executed`. +they fail with the error `(job) is used for configuration only, and its script should not be executed`. The `sast` or `dependency_scanning` stanzas can be used to make changes to all SAST or Dependency Scanning, such as changing `variables` or the `stage`, but they cannot be used to define shared `rules`. |