diff options
Diffstat (limited to 'doc/user/application_security')
30 files changed, 755 insertions, 357 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index 036da0068b5..dfb7e12a8be 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -63,6 +63,7 @@ Examples of both configurations can be found here: - [Example OpenAPI v2 specification project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/openapi) - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing-example/-/tree/har) - [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/postman-api-fuzzing-example) +- [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-fuzzing/graphql-api-fuzzing-example) WARNING: GitLab 14.0 will require that you place API fuzzing configuration files (for example, @@ -73,10 +74,6 @@ starting in GitLab 14.0, GitLab will not check your repository's root for config ### Configuration form > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299234) in GitLab 13.10. -> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-api-fuzzing-configuration-form). **(ULTIMATE)** WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -102,25 +99,6 @@ to your project's `.gitlab-ci.yml` file where you can paste the YAML configurati Select **Copy code only** to copy the snippet to your clipboard and close the modal. -#### Enable or disable API Fuzzing configuration form **(ULTIMATE)** - -The API Fuzzing configuration form is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:api_fuzzing_configuration_ui) -``` - -To disable it: - -```ruby -Feature.disable(:api_fuzzing_configuration_ui) -``` - ### OpenAPI Specification > Support for OpenAPI Specification v3 was @@ -465,7 +443,7 @@ To use HTTP basic authentication, two CI/CD variables are added to your `.gitlab - `FUZZAPI_HTTP_USERNAME`: The username for authentication. - `FUZZAPI_HTTP_PASSWORD`: The password for authentication. -For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) +For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#custom-cicd-variables) (for example, `TEST_API_PASSWORD`) set to the password. You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the **Variables** section. Use that variable as the value for `FUZZAPI_HTTP_PASSWORD`: @@ -500,7 +478,7 @@ outgoing HTTP requests. Follow these steps to provide the bearer token with `FUZZAPI_OVERRIDES_ENV`: -1. [Create a CI/CD variable](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), +1. [Create a CI/CD variable](../../../ci/variables/README.md#custom-cicd-variables), for example `TEST_API_BEARERAUTH`, with the value `{"headers":{"Authorization":"Bearer dXNlcm5hbWU6cGFzc3dvcmQ="}}` (substitute your token). You can create CI/CD variables from the GitLab projects page at **Settings > CI/CD**, in the @@ -839,7 +817,7 @@ variables: ``` In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a -[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-level-cicd-variables): +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-cicd-variables): ```yaml include: @@ -975,7 +953,7 @@ faults it reports. ## Viewing fuzzing faults The API Fuzzing analyzer produces a JSON report that is collected and used -[to populate the faults into GitLab vulnerability screens](../index.md#view-details-of-an-api-fuzzing-vulnerability). +[to populate the faults into GitLab vulnerability screens](#view-details-of-an-api-fuzzing-vulnerability). Fuzzing faults show up as vulnerabilities with a severity of Unknown. The faults that API fuzzing finds require manual investigation and aren't associated with a specific @@ -984,8 +962,42 @@ they should be fixed. See [handling false positives](#handling-false-positives) for information about configuration changes you can make to limit the number of false positives reported. -For additional information, see -[View details of an API Fuzzing vulnerability](../index.md#view-details-of-an-api-fuzzing-vulnerability). +### View details of an API Fuzzing vulnerability + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. + +Faults detected by API Fuzzing occur in the live web application, and require manual investigation +to determine if they are vulnerabilities. Fuzzing faults are included as vulnerabilities with a +severity of Unknown. To facilitate investigation of the fuzzing faults, detailed information is +provided about the HTTP messages sent and received along with a description of the modification(s) +made. + +Follow these steps to view details of a fuzzing fault: + +1. You can view faults in a project, or a merge request: + + - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** + page. This page shows all vulnerabilities from the default branch only. + - In a merge request, go the merge request's **Security** section and click the **Expand** + button. API Fuzzing faults are available in a section labeled + **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. + + | Field | Description | + |:--------------------|:----------------------------------------------------------------------------------------| + | Description | Description of the fault including what was modified. | + | Project | Namespace and project in which the vulnerability was detected. | + | Method | HTTP method used to detect the vulnerability. | + | URL | URL at which the vulnerability was detected. | + | Request | The HTTP request that caused the fault. | + | Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | + | Actual Response | Response received from fuzzed request. | + | Evidence | How we determined a fault occurred. | + | Identifiers | The fuzzing check used to find this fault. | + | Severity | Severity of the finding is always Unknown. | + | Scanner Type | Scanner used to perform testing. | ### Security Dashboard @@ -1016,7 +1028,7 @@ False positives can be handled in two ways: Checks perform testing of a specific type and can be turned on and off for specific configuration profiles. The provided [configuration files](#configuration-files) define several profiles that you can use. The profile definition in the configuration file lists all the checks that are active -during a scan. To turn off a specific check, simply remove it from the profile definition in the +during a scan. To turn off a specific check, remove it from the profile definition in the configuration file. The profiles are defined in the `Profiles` section of the configuration file. Example profile definition: @@ -1131,6 +1143,51 @@ Profiles: UnicodeFuzzing: true ``` +## Troubleshooting + +### Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema + +At the start of an API Fuzzing job the OpenAPI specification is validated against the [published schema](https://github.com/OAI/OpenAPI-Specification/tree/master/schemas). This error is shown when the provided OpenAPI specification has validation errors. Errors can be introduced when creating an OpenAPI specification manually, and also when the schema is generated. + +For OpenAPI specifications that are generated automatically validation errors are often the result of missing code annotations. + +**Error message** + +- In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/323939), `Error, the OpenAPI document is not valid. Errors were found during validation of the document using the published OpenAPI schema` + - `OpenAPI 2.0 schema validation error ...` + - `OpenAPI 3.0.x schema validation error ...` + +**Solution** + +**For generated OpenAPI specifications** + +1. Identify the validation errors. + 1. Use the [Swagger Editor](https://editor.swagger.io/) to identify validation problems in your specification. The visual nature of the Swagger Editor makes it easier to understand what needs to change. + 1. Alternatively, you can check the log output and look for schema validation warnings. They are prefixed with messages such as `OpenAPI 2.0 schema validation error` or `OpenAPI 3.0.x schema validation error`. Each failed validation provides extra information about `location` and `description`. Note that JSON Schema validation messages might not be easy to understand. This is why we recommend the use of editors to validate schema documents. +1. Review the documentation for the OpenAPI generation your framework/tech stack is using. Identify the changes needed to produce a correct OpenAPI document. +1. Once the validation issues are resolved, re-run your pipeline. + +**For manually created OpenAPI Specifications** + +1. Identify the validation errors. + 1. The simplest solution is to use a visual tool to edit and validate the OpenAPI document. For example the [Swagger Editor](https://editor.swagger.io/) will point out schema errors and possible solutions. + 1. Alternatively, you can check the log output and look for schema validation warnings. They are prefixed with messages such as `OpenAPI 2.0 schema validation error` or `OpenAPI 3.0.x schema validation error`. Each failed validation provides extra information about `location` and `description`. Correct each of the validation failures and then resubmit the OpenAPI doc. Note that JSON Schema validation message might not be easy to understand. This is why we recommend the use of editors to validate document. +1. Once the validation issues are resolved, re-run your pipeline. + +### Failed to start scanner session (version header not found) + +The API Fuzzing engine outputs an error message when it cannot establish a connection with the scanner application component. The error message is shown in the job output window of the `apifuzzer_fuzz` job. A common cause of this issue is changing the `FUZZAPI_API` variable from its default. + +**Error message** + +- In [GitLab 13.11 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/323939), `Failed to start scanner session (version header not found).` +- In GitLab 13.10 and earlier, `API Security version header not found. Are you sure that you are connecting to the API Security server?`. + +**Solution** + +- Remove the `FUZZAPI_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the API Fuzzing CI/CD template. We recommend this method instead of manually setting a value. +- If removing the variable is not possible, check to see if this value has changed in the latest version of the [API Fuzzing CI/CD template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. + <!-- ### Target Container diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 909065d7907..fcf5c81db74 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -103,7 +103,7 @@ The included template: (see [requirements](#requirements)) and scans it for possible vulnerabilities. GitLab saves the results as a -[Container Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscontainer_scanning) +[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning) that you can download and analyze later. When downloading, you always receive the most-recent artifact. @@ -241,7 +241,7 @@ container_scanning: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. ### Vulnerability allowlisting @@ -250,8 +250,85 @@ To allowlist specific vulnerabilities, follow these steps: 1. Set `GIT_STRATEGY: fetch` in your `.gitlab-ci.yml` file by following the instructions in [overriding the container scanning template](#overriding-the-container-scanning-template). 1. Define the allowlisted vulnerabilities in a YAML file named `vulnerability-allowlist.yml`. This must use - the format described in the [allowlist example file](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/raw/master/testdata/vulnerability-allowlist.yml). -1. Add the `vulnerability-allowlist.yml` file to your project's Git repository. + the format described in [vulnerability-allowlist.yml data format](#vulnerability-allowlistyml-data-format). +1. Add the `vulnerability-allowlist.yml` file to the root folder of your project's Git repository. + +#### vulnerability-allowlist.yml data format + +The `vulnerability-allowlist.yml` file is a YAML file that specifies a list of CVE IDs of vulnerabilities that are **allowed** to exist, because they're _false positives_, or they're _not applicable_. + +If a matching entry is found in the `vulnerability-allowlist.yml` file, the following happens: + +- The vulnerability **is not included** when the analyzer generates the `gl-container-scanning-report.json` file. +- The Security tab of the pipeline **does not show** the vulnerability. It is not included in the JSON file, which is the source of truth for the Security tab. + +Example `vulnerability-allowlist.yml` file: + +```yaml +generalallowlist: + CVE-2019-8696: + CVE-2014-8166: cups + CVE-2017-18248: +images: + registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256: + CVE-2018-4180: + your.private.registry:5000/centos: + CVE-2015-1419: libxml2 + CVE-2015-1447: +``` + +This example excludes from `gl-container-scanning-report.json`: + +1. All vulnerabilities with CVE IDs: _CVE-2019-8696_, _CVE-2014-8166_, _CVE-2017-18248_. +1. All vulnerabilities found in the `registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256` container image with CVE ID _CVE-2018-4180_. +1. All vulnerabilities found in `your.private.registry:5000/centos` container with CVE IDs _CVE-2015-1419_, _CVE-2015-1447_. + +##### File format + +- `generalallowlist` block allows you to specify CVE IDs globally. All vulnerabilities with matching CVE IDs are excluded from the scan report. + +- `images` block allows you to specify CVE IDs for each container image independently. All vulnerabilities from the given image with matching CVE IDs are excluded from the scan report. The image name is retrieved from one of the environment variables used to specify the Docker image to be scanned, such as `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` or `DOCKER_IMAGE`. The image provided in this block **must** match this value and **must not** include the tag value. For example, if you specify the image to be scanned using `DOCKER_IMAGE=alpine:3.7`, then you would use `alpine` in the `images` block, but you cannot use `alpine:3.7`. + + You can specify container image in multiple ways: + + - as image name only (ie. `centos`). + - as full image name with registry hostname (ie. `your.private.registry:5000/centos`). + - as full image name with registry hostname and sha256 label (ie. `registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256`). + +NOTE: +The string after CVE ID (`cups` and `libxml2` in the previous example) is an optional comment format. It has **no impact** on the handling of vulnerabilities. You can include comments to describe the vulnerability. + +##### Container scanning job log format + +You can verify the results of your scan and the correctness of your `vulnerability-allowlist.yml` file by looking +at the logs that are produced by the container scanning analyzer in `container_scanning` job details. + +The log contains a list of found vulnerabilities as a table, for example: + +```plainttext ++------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ +| STATUS | CVE SEVERITY | PACKAGE NAME | PACKAGE VERSION | CVE DESCRIPTION | ++------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ +| Approved | High CVE-2019-3462 | apt | 1.4.8 | Incorrect sanitation of the 302 redirect field in HTTP transport metho | +| | | | | d of apt versions 1.4.8 and earlier can lead to content injection by a | +| | | | | MITM attacker, potentially leading to remote code execution on the ta | +| | | | | rget machine. | ++------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ +| Unapproved | Medium CVE-2020-27350 | apt | 1.4.8 | APT had several integer overflows and underflows while parsing .deb pa | +| | | | | ckages, aka GHSL-2020-168 GHSL-2020-169, in files apt-pkg/contrib/extr | +| | | | | acttar.cc, apt-pkg/deb/debfile.cc, and apt-pkg/contrib/arfile.cc. This | +| | | | | issue affects: apt 1.2.32ubuntu0 versions prior to 1.2.32ubuntu0.2; 1 | +| | | | | .6.12ubuntu0 versions prior to 1.6.12ubuntu0.2; 2.0.2ubuntu0 versions | +| | | | | prior to 2.0.2ubuntu0.2; 2.1.10ubuntu0 versions prior to 2.1.10ubuntu0 | +| | | | | .1; | ++------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ +| Unapproved | Medium CVE-2020-3810 | apt | 1.4.8 | Missing input validation in the ar/tar implementations of APT before v | +| | | | | ersion 2.1.2 could result in denial of service when processing special | +| | | | | ly crafted deb files. | ++------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ +``` + +Vulnerabilities in the log are marked as `Approved` when the corresponding CVE ID is added to the `vulnerability-allowlist.yml` file. ### Running container scanning in an offline environment diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 94a7d5268b7..e9097836d83 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -109,7 +109,7 @@ There are two types of jobs: Here's our current suggestion for configuring your fuzz target's timeout: - Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (asynchronous) fuzzing - jobs. This is `master` by default. + jobs. This is normally the default branch. - Use regression or short-running fuzzing jobs for other branches or merge requests. This suggestion helps find new bugs on the development branch and catch old bugs in merge requests @@ -121,10 +121,10 @@ any option available in the underlying fuzzing engine. ### Available CI/CD variables -| CI/CD variable | Description | -|-----------------------|--------------------------------------------------------------------| -| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | -| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | +| CI/CD variable | Description | +|-----------------------|--------------------------------------------------------------------------------| +| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. This is normally the default branch. | +| `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 @@ -141,7 +141,7 @@ The `gitlab-cov-fuzz` tool emits a JSON report file. For more information, see t [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json). You can download the JSON report file from the CI pipelines page. For more information, see -[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#downloading-artifacts). +[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). Here's an example coverage fuzzing report: diff --git a/doc/user/application_security/dast/dast_troubleshooting.md b/doc/user/application_security/dast/dast_troubleshooting.md new file mode 100644 index 00000000000..48b48392e65 --- /dev/null +++ b/doc/user/application_security/dast/dast_troubleshooting.md @@ -0,0 +1,64 @@ +--- +stage: Secure +group: Dynamic Analysis +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: reference, howto +--- + +# Dynamic Application Security Testing (DAST) Troubleshooting **(ULTIMATE)** + +The following troubleshooting scenarios have been collected from customer support cases. If you +experience a problem not addressed here, or the information here does not fix your problem, create a +support ticket. For more details, see the [GitLab Support](https://about.gitlab.com/support/) page. + +## Running out of memory + +By default, ZAProxy, which DAST relies on, is allocated memory that sums to 25% +of the total memory on the host. +Since it keeps most of its information in memory during a scan, +it's possible for DAST to run out of memory while scanning large applications. +This results in the following error: + +```plaintext +[zap.out] java.lang.OutOfMemoryError: Java heap space +``` + +Fortunately, it's straightforward to increase the amount of memory available +for DAST by using the `DAST_ZAP_CLI_OPTIONS` CI/CD variable: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +variables: + DAST_ZAP_CLI_OPTIONS: "-Xmx3072m" +``` + +This example allocates 3072 MB to DAST. +Change the number after `-Xmx` to the required memory amount. + +## DAST job exceeding the job timeout + +If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some +tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). + +## Getting warning message `gl-dast-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). + +## Getting error `dast job: chosen stage does not exist` when including DAST CI template + +To avoid overwriting stages from other CI files, newer versions of the DAST CI template do not +define stages. If you recently started using `DAST.latest.gitlab-ci.yml` or upgraded to a new major +release of GitLab and began receiving this error, you must define a `dast` stage with your other +stages. Note that you must have a running application for DAST to scan. If your application is set +up in your pipeline, it must be deployed in a stage _before_ the `dast` stage: + +```yaml +stages: + - deploy # DAST needs a running application to scan + - dast + +include: + - template: DAST.latest.gitlab-ci.yml +``` diff --git a/doc/user/application_security/dast/img/dast_v13_4.png b/doc/user/application_security/dast/img/dast_v13_4.png Binary files differdeleted file mode 100644 index d9c1d1b5c66..00000000000 --- a/doc/user/application_security/dast/img/dast_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 209dd7ad251..d3f679fe9dd 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -7,125 +7,142 @@ type: reference, howto # Dynamic Application Security Testing (DAST) **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. +If you deploy your web application into a new environment, your application may +become exposed to new types of attacks. For example, misconfigurations of your +application server or incorrect assumptions about security controls may not be +visible from the source code. -Your application may be exposed to a new category of attacks once deployed into a new environment. For -example, application server misconfigurations or incorrect assumptions about security controls may -not be visible from source code alone. Dynamic Application Security Testing (DAST) checks an -application for these types of vulnerabilities in a deployed environment. GitLab DAST uses the -popular open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) to analyze your running -web application. +Dynamic Application Security Testing (DAST) examines applications for +vulnerabilities like these in deployed environments. DAST uses the open source +tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) for analysis. NOTE: -The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) -explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your -organization. +To learn how four of the top six attacks were application-based and how +to protect your organization, download our +["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) +whitepaper. -In GitLab, DAST is commonly initiated by a merge request and runs as a job in the CI/CD pipeline. -You can also run a DAST scan on demand, outside the CI/CD pipeline. Your running web application is -analyzed for known vulnerabilities. GitLab checks the DAST report, compares the vulnerabilities -found between the source and target branches, and shows any relevant findings on the merge request. +You can use DAST to examine your web applications: -Note that this comparison logic uses only the latest pipeline executed for the target branch's base -commit. Running the pipeline on any other commit has no effect on the merge request. +- When initiated by a merge request, running as CI/CD pipeline job. +- On demand, outside the CI/CD pipeline. - +After DAST creates its report, GitLab evaluates it for discovered +vulnerabilities between the source and target branches. Relevant +findings are noted in the merge request. -## Enable DAST +The comparison logic uses only the latest pipeline executed for the target +branch's base commit. Running the pipeline on other commits has no effect on +the merge request. + +## Prerequisite -### Prerequisites +To use DAST, ensure you're using GitLab Runner with the +[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). -- GitLab Runner with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). +## Enable DAST To enable DAST, either: -- Enable [Auto DAST](../../../topics/autodevops/stages.md#auto-dast), provided by - [Auto DevOps](../../../topics/autodevops/index.md). -- [Include the DAST template](#dast-cicd-template) in your existing `.gitlab-ci.yml` file. +- Enable [Auto DAST](../../../topics/autodevops/stages.md#auto-dast) (provided + by [Auto DevOps](../../../topics/autodevops/index.md)). +- Manually [include the DAST template](#include-the-dast-template) in your existing + `.gitlab-ci.yml` file. -### DAST CI/CD template +### Include the DAST template -The DAST job is defined in a CI/CD template file you reference in your CI/CD configuration file. The -template is included with GitLab. Updates to the template are provided with GitLab upgrades. You -benefit from any improvements and additions. +If you want to manually add DAST to your application, the DAST job is defined +in a CI/CD template file. Updates to the template are provided with GitLab +upgrades, allowing you to benefit from any improvements and additions. -The following templates are available: +To include the DAST template: -- [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml): - Stable version of the DAST CI/CD template. -- [`DAST.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.latest.gitlab-ci.yml): - Latest version of the DAST template. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) - in GitLab 13.8). Please note that the latest version may include breaking changes. Check the - [DAST troubleshooting guide](#troubleshooting) if you experience problems. +1. Select the CI/CD template you want to use: -Use the stable template unless you need a feature provided only in the latest template. + - [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml): + Stable version of the DAST CI/CD template. + - [`DAST.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.latest.gitlab-ci.yml): + Latest version of the DAST template. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) + in GitLab 13.8). -See the CI/CD [documentation](../../../development/cicd/templates.md#latest-version) -on template versioning for more information. + WARNING: + The latest version of the template may include breaking changes. Use the + stable template unless you need a feature provided only in the latest template. -#### Include the DAST template + For more information about template versioning, see the + [CI/CD documentation](../../../development/cicd/templates.md#latest-version). -The method of including the DAST template depends on the GitLab version: +1. Add a `dast` stage to your GitLab CI stages configuration: -- In GitLab 11.9 and later, [include](../../../ci/yaml/README.md#includetemplate) the - `DAST.gitlab-ci.yml` template. + ```yaml + stages: + - dast + ``` - Add the following to your `.gitlab-ci.yml` file: +1. Add the template to GitLab, based on your version of GitLab: - ```yaml - include: - - template: DAST.gitlab-ci.yml + - In GitLab 11.9 and later, [include](../../../ci/yaml/README.md#includetemplate) + the template by adding the following to your `.gitlab-ci.yml` file: - variables: - DAST_WEBSITE: https://example.com - ``` + ```yaml + include: + - template: <template_file.yml> -- In GitLab 11.8 and earlier, copy the template's content into your `.gitlab_ci.yml` file. + variables: + DAST_WEBSITE: https://example.com + ``` -#### Template options + - In GitLab 11.8 and earlier, add the contents of the template to your + `.gitlab_ci.yml` file. -Running a DAST scan requires a URL. There are two ways to define the URL to be scanned by DAST: +1. Define the URL to be scanned by DAST by using one of these methods: -1. Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/README.md#variables). + - Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/README.md#variables). + If set, this value takes precedence. -1. Add it in an `environment_url.txt` file at the root of your project. - This is useful for testing in dynamic environments. To run DAST against an application - dynamically created during a GitLab CI/CD pipeline, a job that runs prior to the DAST scan must - persist the application's domain in an `environment_url.txt` file. DAST automatically parses the - `environment_url.txt` file to find its scan target. + - Add the URL in an `environment_url.txt` file at the root of your project. This is + useful for testing in dynamic environments. To run DAST against an application + dynamically created during a GitLab CI/CD pipeline, a job that runs prior to + the DAST scan must persist the application's domain in an `environment_url.txt` + file. DAST automatically parses the `environment_url.txt` file to find its + scan target. - For example, in a job that runs prior to DAST, you could include code that looks similar to: + For example, in a job that runs prior to DAST, you could include code that + looks similar to: - ```yaml - script: - - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.domain.com > environment_url.txt - artifacts: - paths: [environment_url.txt] - when: always - ``` - - You can see an example of this in our [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) file. + ```yaml + script: + - echo http://${CI_PROJECT_ID}-${CI_ENVIRONMENT_SLUG}.domain.com > environment_url.txt + artifacts: + paths: [environment_url.txt] + when: always + ``` -If both values are set, the `DAST_WEBSITE` value takes precedence. + You can see an example of this in our + [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) + file. The included template creates a `dast` job in your CI/CD pipeline and scans your project's running application for possible vulnerabilities. The results are saved as a -[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast) -that you can later download and analyze. Due to implementation limitations we +[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast) +that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. Behind the scenes, the [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast) -is used to run the tests on the specified URL and scan it for possible vulnerabilities. +is used to run the tests on the specified URL and scan it for possible +vulnerabilities. By default, the DAST template uses the latest major version of the DAST Docker image. Using the `DAST_VERSION` variable, you can choose how DAST updates: -- Automatically update DAST with new features and fixes by pinning to a major version (such as `1`). +- Automatically update DAST with new features and fixes by pinning to a major + version (such as `1`). - Only update fixes by pinning to a minor version (such as `1.6`). - Prevent all updates by pinning to a specific version (such as `1.6.4`). -Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page. +Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) +page. ## Deployment options @@ -145,7 +162,7 @@ on how to configure Review Apps for DAST. If your application utilizes Docker containers you have another option for deploying and scanning with DAST. After your Docker build job completes and your image is added to your container registry, you can utilize the image as a -[service](../../../ci/docker/using_docker_images.md#what-is-a-service). +[service](../../../ci/services/index.md). By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. @@ -154,7 +171,7 @@ stages: - build - dast -include: +include: - template: DAST.gitlab-ci.yml # Deploys the container to the GitLab container registry @@ -261,7 +278,7 @@ that you periodically confirm the scanner's authentication is still working as t time due to authentication changes to the application. Create masked CI/CD variables to pass the credentials that DAST uses. -To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). +To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables). Note that the key of the username variable must be `DAST_USERNAME` and the key of the password variable must be `DAST_PASSWORD`. @@ -287,7 +304,7 @@ variables: ``` The results are saved as a -[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast) +[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast) that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. @@ -459,16 +476,14 @@ variables: #### Import API specification from a file -If your API specification is in your repository, you can provide the specification's -filename directly as the target. The specification file is expected to be in the -`/zap/wrk` directory. +If your API specification file is in your repository, you can provide its filename as the target. +The API specification file must be in the `/zap/wrk` directory. ```yaml dast: - script: + before_script: - mkdir -p /zap/wrk - cp api-specification.yml /zap/wrk/api-specification.yml - - /analyze -t $DAST_WEBSITE variables: GIT_STRATEGY: fetch DAST_API_SPECIFICATION: api-specification.yml @@ -486,6 +501,12 @@ host referenced may be different than the host of the API's review instance. This can cause incorrect URLs to be imported, or a scan on an incorrect host. Use the `DAST_API_HOST_OVERRIDE` CI/CD variable to override these values. +WARNING: +When using the API host override feature, you cannot use the `$DAST_WEBSITE` variable to override the hostname. +A host override is _only_ supported when importing the API specification from a URL. Attempts to override the +host throw an error when the API specification is imported from a file. This is due to a limitation in the +ZAP OpenAPI extension. + For example, with a OpenAPI V3 specification containing: ```yaml @@ -505,10 +526,6 @@ variables: DAST_API_HOST_OVERRIDE: api-test.host.com ``` -Note that using a host override is ONLY supported when importing the API specification from a URL. -It doesn't work and is ignored when importing the specification from a file. This is due to a -limitation in the ZAP OpenAPI extension. - #### Authentication using headers Tokens in request headers are often used as a way to authenticate API requests. @@ -526,7 +543,8 @@ variables: ### URL scan -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/273141) in GitLab 13.11. A URL scan allows you to specify which parts of a website are scanned by DAST. @@ -550,26 +568,19 @@ category/shoes/page1.html ``` To scan the URLs in that file, set the CI/CD variable `DAST_PATHS_FILE` to the path of that file. +The file can be checked into the project repository or generated as an artifact by a job that +runs before DAST. + +By default, DAST scans do not clone the project repository. Instruct the DAST job to clone +the project by setting `GIT_STRATEGY` to fetch. Give a file path relative to `CI_PROJECT_DIR` to `DAST_PATHS_FILE`. ```yaml include: - template: DAST.gitlab-ci.yml variables: - DAST_PATHS_FILE: url_file.txt -``` - -By default, DAST scans do not clone the project repository. If the file is checked in to the project, instruct the DAST job to clone the project by setting GIT_STRATEGY to fetch. The file is expected to be in the `/zap/wrk` directory. - -```yaml -dast: - script: - - mkdir -p /zap/wrk - - cp url_file.txt /zap/wrk/url_file.txt - - /analyze -t $DAST_WEBSITE - variables: - GIT_STRATEGY: fetch - DAST_PATHS_FILE: url_file.txt + GIT_STRATEGY: fetch + DAST_PATHS_FILE: url_file.txt # url_file.txt lives in the root directory of the project ``` ##### Use `DAST_PATHS` CI/CD variable @@ -584,7 +595,7 @@ include: - template: DAST.gitlab-ci.yml variables: - DAST_PATHS=/page1.html,/category1/page1.html,/page3.html + DAST_PATHS: "/page1.html,/category1/page1.html,/page3.html" ``` When using `DAST_PATHS` and `DAST_PATHS_FILE`, note the following: @@ -643,7 +654,7 @@ DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. | `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_EXCLUDE_URLS` | 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. | | `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | -| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | +| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/293595) in GitLab 13.8, to be removed in 14.0. Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | | `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | @@ -656,7 +667,7 @@ DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. | `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `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. | -| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line and be in `/zap/wrk`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | | `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_FIRST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | @@ -708,6 +719,22 @@ variables: DAST_ZAP_CLI_OPTIONS: "-config replacer.full_list(0).description=auth -config replacer.full_list(0).enabled=true -config replacer.full_list(0).matchtype=REQ_HEADER -config replacer.full_list(0).matchstr=Authorization -config replacer.full_list(0).regex=false -config replacer.full_list(0).replacement=TOKEN" ``` +### Bleeding-edge vulnerability definitions + +ZAP first creates rules in the `alpha` class. After a testing period with +the community, they are promoted to `beta`. DAST uses `beta` definitions by +default. To request `alpha` definitions, use the +`DAST_INCLUDE_ALPHA_VULNERABILITIES` CI/CD variable as shown in the +following configuration: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_INCLUDE_ALPHA_VULNERABILITIES: "true" +``` + ### Cloning the project's repository The DAST job does not require the project's repository to be present when running, so by default @@ -747,7 +774,7 @@ successfully run. For more information, see [Offline environments](../offline_de To use DAST in an offline environment, you need: -- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisites). +- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisite). - Docker Container Registry with a locally available copy of the DAST [container image](https://gitlab.com/gitlab-org/security-products/dast), found in the [DAST container registry](https://gitlab.com/gitlab-org/security-products/dast/container_registry). @@ -798,8 +825,9 @@ Alternatively, you can use the CI/CD variable `SECURE_ANALYZERS_PREFIX` to overr > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. -> - The saved scans feature was [added](https://gitlab.com/groups/gitlab-org/-/epics/5100) in -> GitLab 13.9. +> - The saved scans feature was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5100) in GitLab 13.9. +> - The option to select a branch was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4847) in GitLab 13.10. +> - DAST branch selection [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/322672) in GitLab 13.11. 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. @@ -811,6 +839,8 @@ 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: @@ -843,6 +873,7 @@ To run an on-demand scan, either: 1. From your project's home page, go to **Security & Compliance > On-demand Scans** in the left sidebar. 1. Complete the **Scan name** and **Description** fields. +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 @@ -877,6 +908,9 @@ To run a saved on-demand scan: 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. ### Edit an on-demand scan @@ -911,6 +945,14 @@ A site profile contains the following: - **Profile name**: A name you assign to the site to be scanned. - **Target URL**: The URL that DAST runs against. +- **Excluded URLs**: A comma-separated list of URLs to exclude from the scan. +- **Request headers**: A comma-separated list of HTTP request headers, including names and values. These headers are added to every request made by DAST. +- **Authentication**: + - **Authenticated URL**: The URL of the page containing the sign-in HTML form on the target website. The username and password are submitted with the login form to create an authenticated scan. + - **Username**: The username used to authenticate to the website. + - **Password**: The password used to authenticate to the website. + - **Username form field**: The name of username field at the sign-in HTML form. + - **Password form field**: The name of password field at the sign-in HTML form. #### Site profile validation @@ -926,7 +968,7 @@ follows: - _Header validation_ requires the header `Gitlab-On-Demand-DAST` be added to the target site, with a value unique to the project. The validation process checks that the header is present, and checks its value. - + Both methods are equivalent in functionality. Use whichever is feasible. #### Create a site profile @@ -950,7 +992,9 @@ To edit an existing site profile: 1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Edit**. 1. Edit the fields then select **Save profile**. -The site profile is updated with the edited details. +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) +for more information. #### Delete a site profile @@ -962,7 +1006,9 @@ To delete an existing site profile: 1. In the profile's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. 1. Select **Delete** to confirm the deletion. -The site profile is deleted. +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) +for more information. #### Validate a site profile @@ -1084,7 +1130,9 @@ To edit a scanner profile: 1. Edit the form. 1. Select **Save profile**. -The scanner profile is updated with the edited details. +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) +for more information. #### Delete a scanner profile @@ -1096,7 +1144,9 @@ To delete a scanner profile: 1. In the scanner's row select the **More actions** (**{ellipsis_v}**) menu, then select **Delete**. 1. Select **Delete**. -The scanner profile is deleted. +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) +for more information. ## Reports @@ -1145,38 +1195,6 @@ dast: - gl-dast-report.json ``` -## Security Dashboard - -The Security Dashboard is a good place to get an overview of all the security -vulnerabilities in your groups, projects and pipelines. Read more about the -[Security Dashboard](../security_dashboard/index.md). - -## Bleeding-edge vulnerability definitions - -ZAP first creates rules in the `alpha` class. After a testing period with -the community, they are promoted to `beta`. DAST uses `beta` definitions by -default. To request `alpha` definitions, use the -`DAST_INCLUDE_ALPHA_VULNERABILITIES` CI/CD variable as shown in the -following configuration: - -```yaml -include: - template: DAST.gitlab-ci.yml - -variables: - DAST_INCLUDE_ALPHA_VULNERABILITIES: "true" -``` - -## Interacting with the vulnerabilities - -Once a vulnerability is found, you can interact with it. Read more on how to -[address the vulnerabilities](../index.md#addressing-vulnerabilities). - -## Vulnerabilities database update - -For more information about the vulnerabilities database update, check the -[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). - ## Optimizing DAST By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If @@ -1188,70 +1206,3 @@ artifacts, add the following to your `gitlab-ci.yml` file: dast: dependencies: [] ``` - -## Troubleshooting - -### Running out of memory - -By default, ZAProxy, which DAST relies on, is allocated memory that sums to 25% -of the total memory on the host. -Since it keeps most of its information in memory during a scan, -it's possible for DAST to run out of memory while scanning large applications. -This results in the following error: - -```plaintext -[zap.out] java.lang.OutOfMemoryError: Java heap space -``` - -Fortunately, it's straightforward to increase the amount of memory available -for DAST by using the `DAST_ZAP_CLI_OPTIONS` CI/CD variable: - -```yaml -include: - - template: DAST.gitlab-ci.yml - -variables: - DAST_ZAP_CLI_OPTIONS: "-Xmx3072m" -``` - -Here, DAST is being allocated 3072 MB. -Change the number after `-Xmx` to the required memory amount. - -### DAST job exceeding the job timeout - -If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). - -### Getting warning message `gl-dast-report.json: no matching files` - -For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). - -### Getting error `dast job: chosen stage does not exist` when including DAST CI template - -Newer versions of the DAST CI template do not define stages in order to avoid -overwriting stages from other CI files. If you've recently started using -`DAST.latest.gitlab-ci.yml` or upgraded to a new major release of GitLab and -began receiving this error, you will need to define a `dast` stage with your -other stages. Please note that you must have a running application for DAST to -scan. If your application is set up in your pipeline, it must be deployed - in a stage _before_ the `dast` stage: - -```yaml -stages: - - deploy # DAST needs a running application to scan - - dast - -include: - - template: DAST.latest.gitlab-ci.yml -``` - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_10.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_10.png Binary files differdeleted file mode 100644 index 2755b42f1e4..00000000000 --- a/doc/user/application_security/dependency_list/img/dependency_list_v12_10.png +++ /dev/null diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png b/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png Binary files differnew file mode 100644 index 00000000000..5b2bd985ce4 --- /dev/null +++ b/doc/user/application_security/dependency_list/img/dependency_list_v13_11.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md index 6ed3b15d829..25b7615a8ae 100644 --- a/doc/user/application_security/dependency_list/index.md +++ b/doc/user/application_security/dependency_list/index.md @@ -26,7 +26,7 @@ To view your project's dependencies, ensure you meet the following requirements: ## View a project's dependencies - + GitLab displays dependencies with the following information: @@ -44,7 +44,8 @@ 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. +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. ### Dependency paths diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index f87ea8edc7b..53387acefef 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -105,7 +105,7 @@ include: The included template creates dependency scanning jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[dependency scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning) +[dependency scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest dependency scanning artifact available. @@ -183,10 +183,11 @@ The following variables are used for configuring specific analyzers (used for a | `BUNDLER_AUDIT_ADVISORY_DB_URL` | `bundler-audit` | `https://github.com/rubysec/ruby-advisory-db` | URL of the advisory database used by bundler-audit. | | `BUNDLER_AUDIT_ADVISORY_DB_REF_NAME` | `bundler-audit` | `master` | Git ref for the advisory database specified by `BUNDLER_AUDIT_ADVISORY_DB_URL`. | | `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local Gemnasium database. | +| `GEMNASIUM_DB_UPDATE_DISABLED` | `gemnasium` | `"false"` | Disable automatic updates for the `gemnasium-db` advisory database (For usage see: [examples](#hosting-a-copy-of-the-gemnasium_db-advisory-database))| | `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the Gemnasium database. | | `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. | | `DS_REMEDIATE` | `gemnasium` | `"true"` | Enable automatic remediation of vulnerable dependencies. | -| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle use the Java version specified by this value. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`. Maven and Gradle use the Java version specified by this value. | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | @@ -214,7 +215,7 @@ variables: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. ### Using private Maven repositories @@ -505,6 +506,50 @@ ensure that it can reach your private repository. Here is an example configurati setuptools.ssl_support.cert_paths = ['internal.crt'] ``` +## Hosting a copy of the gemnasium_db advisory database + +The [gemnasium_db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) Git repository is +used by `gemnasium`, `gemnasium-maven`, and `gemnasium-python` as the source of vulnerability data. +This repository updates at scan time to fetch the latest advisories. However, due to a restricted +networking environment, running this update is sometimes not possible. In this case, a user can do +one of the following: + +- [Host a copy of the advisory database](#host-a-copy-of-the-advisory-database) +- [Use a local clone](#use-a-local-clone) + +### Host a copy of the advisory database + +If [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is not reachable +from within the environment, the user can host their own Git copy. Then the analyzer can be +instructed to update the database from the user's copy by using `GEMNASIUM_DB_REMOTE_URL`: + +```yaml +variables: + GEMNASIUM_DB_REMOTE_URL: https://users-own-copy.example.com/gemnasium-db/.git + +... +``` + +### Use a local clone + +If a hosted copy is not possible, then the user can clone [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) +or create an archive before the scan and point the analyzer to the directory (using: +`GEMNASIUM_DB_LOCAL_PATH`). Turn off the analyzer's self-update mechanism (using: +`GEMNASIUM_DB_UPDATE_DISABLED`). In this example, the database directory is created in the +`before_script`, before the `gemnasium` analyzer's scan job: + +```yaml +... + +gemnasium-dependency_scanning: + variables: + GEMNASIUM_DB_LOCAL_PATH: ./gemnasium-db-local + GEMNASIUM_DB_UPDATE_DISABLED: "true" + before_script: + - mkdir $GEMNASIUM_DB_LOCAL_PATH + - tar -xzf gemnasium_db.tar.gz -C $GEMNASIUM_DB_LOCAL_PATH +``` + ## Limitations ### Referencing local dependencies using a path in JavaScript projects diff --git a/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png b/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png Binary files differdeleted file mode 100644 index 8e7bcf09428..00000000000 --- a/doc/user/application_security/img/adding_a_dismissal_reason_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png Binary files differindex 54ccfa24374..55694fc7926 100644 --- a/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png +++ b/doc/user/application_security/img/create_mr_from_vulnerability_v13_4.png diff --git a/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png b/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png Binary files differdeleted file mode 100644 index db698995469..00000000000 --- a/doc/user/application_security/img/interacting_with_vulnerability_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/img/multi_select_v12_9.png b/doc/user/application_security/img/multi_select_v12_9.png Binary files differdeleted file mode 100644 index ec3648bff08..00000000000 --- a/doc/user/application_security/img/multi_select_v12_9.png +++ /dev/null diff --git a/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif b/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif Binary files differdeleted file mode 100644 index 562ffe7e329..00000000000 --- a/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif +++ /dev/null diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index b0457ec0690..1ba2161362c 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -178,43 +178,6 @@ authorization credentials. By default, content of specific headers are masked in reports. You can specify the list of all headers to be masked. For details, see [Hide sensitive information](dast/index.md#hide-sensitive-information). -## View details of an API Fuzzing vulnerability - -> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. - -Faults detected by API Fuzzing occur in the live web application, and require manual investigation -to determine if they are vulnerabilities. Fuzzing faults are included as vulnerabilities with a -severity of Unknown. To facilitate investigation of the fuzzing faults, detailed information is -provided about the HTTP messages sent and received along with a description of the modification(s) -made. - -Follow these steps to view details of a fuzzing fault: - -1. You can view faults in a project, or a merge request: - - - In a project, go to the project's **{shield}** **Security & Compliance > Vulnerability Report** - page. This page shows all vulnerabilities from the default branch only. - - In a merge request, go the merge request's **Security** section and click the **Expand** - button. API Fuzzing faults are available in a section labeled - **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. - -| Field | Description | -|:-----------------|:------------------------------------------------------------------ | -| Description | Description of the fault including what was modified. | -| Project | Namespace and project in which the vulnerability was detected. | -| Method | HTTP method used to detect the vulnerability. | -| URL | URL at which the vulnerability was detected. | -| Request | The HTTP request that caused the fault. | -| Unmodified Response | Response from an unmodified request. This is what a normal working response looks like. | -| Actual Response | Response received from fuzzed request. | -| Evidence | How we determined a fault occurred. | -| Identifiers | The fuzzing check used to find this fault. | -| Severity | Severity of the finding is always Unknown. | -| Scanner Type | Scanner used to perform testing. | - ## Addressing vulnerabilities > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.8. @@ -265,15 +228,7 @@ If you already have an open issue, you can link to it from the vulnerability. To link to an existing issue: 1. Open the vulnerability. -1. In the **Related Issues** section, select the plus (**{plus}**) icon. -1. In the text box that appears, type an issue number or paste an issue link. - - Type `#` followed by a number to show an autocomplete menu. - - You can enter multiple issues at once. Press the space bar after each issue number or link to converts them to tags. -1. Select **Add**. - -To remove an issue, to the right of the issue number, select **{close}**. - - +1. [Add a linked issue](../project/issues/related_issues.md). ### Apply an automatic remediation for a vulnerability @@ -311,7 +266,7 @@ request created to automatically solve the issue. If this action is available: 1. Select the **Resolve with merge request** dropdown, then select **Resolve with merge request**. - +  A merge request is created. It that applies the solution to the source branch. @@ -407,7 +362,7 @@ to pass a username and password. You can set it under your project's settings so that your credentials aren't exposed in `.gitlab-ci.yml`. If the username is `myuser` and the password is `verysecret` then you would -[set the following variable](../../ci/variables/README.md#create-a-custom-variable-in-the-ui) +[set the following variable](../../ci/variables/README.md#custom-cicd-variables) under your project's settings: | Type | Key | Value | @@ -616,9 +571,8 @@ Instructions are available in the [legacy template project](https://gitlab.com/g 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](sast/index.md) +[Merge Request widget](#view-security-scan-information-in-merge-requests) or [Security Dashboard](security_dashboard/index.md). -There is [an open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/235772) in which changes to this behavior are being discussed. ### Error: job `is used for configuration only, and its script should not be executed` diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md new file mode 100644 index 00000000000..208fbdfa5f3 --- /dev/null +++ b/doc/user/application_security/policies/index.md @@ -0,0 +1,183 @@ +--- +stage: Protect +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)** + +> - [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. + +Scan 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. + +GitLab supports the following security policies: + +- [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. + +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. + +## Enable or disable scan policies + +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. + +To enable it: + +```ruby +# Instance-wide +Feature.enable(:security_orchestration_policies_configuration) +# or by project +Feature.enable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +``` + +To disable it: + +```ruby +# Instance-wide +Feature.disable(:security_orchestration_policies_configuration) +# or by project +Feature.disable(:security_orchestration_policies_configuration, Project.find(<project ID>)) +``` + +## Security Policies project + +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: + +```yaml +--- +scan_execution_policy: +- name: Enforce DAST in every pipeline + description: This policy enforces pipeline configuration to have a job with DAST scan + enabled: true + rules: + - type: pipeline + branch: master + actions: + - scan: dast + scanner_profile: Scanner Profile A + site_profile: Site Profile B +- name: Enforce DAST in every pipeline in main branch + description: This policy enforces pipeline configuration to have a job with DAST scan for main branch + enabled: true + rules: + - type: pipeline + branch: main + actions: + - scan: dast + scanner_profile: Scanner Profile C + site_profile: Site Profile D +``` + +### 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. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `scan_execution_policy` | `array` of Scan Execution Policy | | List of scan execution policies (maximum 5) | + +### Scan Execution Policy Schema + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `name` | `string` | | Name of the policy. | +| `description` (optional) | `string` | | Description of the policy. | +| `enabled` | `boolean` | `true`, `false` | Flag to enable (`true`) or disable (`false`) the policy. | +| `rules` | `array` of rules | | List of rules that the policy applies. | +| `actions` | `array` of actions | | List of actions that the policy enforces. | + +### `pipeline` rule type + +This rule enforces the defined actions whenever the pipeline runs for a selected branch. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `type` | `string` | `pipeline` | The rule's type. | +| `branch` | `string` | `*` or the branch's name | The branch the given policy applies to (supports wildcard). | + +### `scan` action type + +This action executes the selected `scan` with additional parameters when conditions for at least one +rule in the defined policy are met. + +| Field | Type | Possible values | Description | +|-------|------|-----------------|-------------| +| `scan` | `string` | `dast` | The action's type. | +| `site_profile` | `string` | Name of the selected [DAST site profile](../dast/index.md#site-profile). | The DAST site profile to execute the DAST scan. | +| `scanner_profile` | `string` or `null` | Name of the selected [DAST scanner profile](../dast/index.md#scanner-profile). | The DAST scanner profile to execute the DAST scan. | + +Note the following: + +- You must create the [site profile](../dast/index.md#site-profile) and [scanner profile](../dast/index.md#scanner-profile) + with selected names for each project that is assigned to the selected Security Policy Project. + Otherwise, the policy is not applied and a job with an error message is created instead. +- Once you associate the site profile and scanner profile by name in the policy, it is not possible + to modify or delete them. If you want to modify them, you must first disable the policy by setting + the `active` flag to `false`. + +Here's an example: + +```yaml +--- +scan_execution_policy: +- name: Enforce DAST in every release pipeline + description: This policy enforces pipeline configuration to have a job with DAST scan for release branches + enabled: true + rules: + - type: pipeline + branch: release/* + actions: + - scan: dast + scanner_profile: Scanner Profile A + site_profile: Site Profile B +- name: Enforce DAST in every pipeline in main branch + description: This policy enforces pipeline configuration to have a job with DAST scan for main branch + enabled: true + rules: + - type: pipeline + branch: main + actions: + - scan: dast + scanner_profile: Scanner Profile C + site_profile: Site Profile D +``` + +In this example, the DAST scan runs with the scanner profile `Scanner Profile A` and the site +profile `Site Profile B` for every pipeline executed on branches that match the +`release/*` wildcard (for example, branch name `release/v1.2.1`); and the DAST scan runs with +the scanner profile `Scanner Profile C` and the site profile `Site Profile D` for every pipeline executed on `main` branch. + +NOTE: +All scanner and site profiles must be configured and created for each project that is assigned to the selected Security Policy Project. +If they are not created, the job will fail with the error message. + +## 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. + +## Roadmap + +See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/) +for more information on the product direction of Container Network Security. diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 83f85951388..c085dafac12 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -43,6 +43,19 @@ dedicated containers for each analysis. SAST is pre-configured with a set of **default images** that are maintained by GitLab, but users can also integrate their own **custom images**. +## SAST analyzer features + +For an analyzer to be considered Generally Available, it is expected to minimally +support the following features: + +- [Customizable configuration](index.md#available-variables) +- [Customizable rulesets](index.md#customize-rulesets) +- [Scan projects](index.md#supported-languages-and-frameworks) +- [Multi-project support](index.md#multi-project-support) +- [Offline support](index.md#running-sast-in-an-offline-environment) +- [Emits JSON report format](index.md#reports-json-format) +- [SELinux support](index.md#running-sast-in-selinux) + ## Official default analyzers Any custom change to the official analyzers can be achieved by using a diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index fffff4efba6..cbd05f6267e 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -64,32 +64,36 @@ GitLab SAST supports a variety of languages, package managers, and frameworks. O You can also [view our language roadmap](https://about.gitlab.com/direction/secure/static-analysis/sast/#language-support) and [request other language support by opening an issue](https://gitlab.com/groups/gitlab-org/-/epics/297). -| Language (package managers) / framework | Scan tool | Introduced in GitLab Version | -|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | -| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0 | -| Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 | -| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | -| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | -| Go | [Gosec](https://github.com/securego/gosec) | 10.7 | -| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | -| Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | -| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | -| Java (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | -| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | -| Kotlin (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | -| Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6 | -| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1 | -| Objective-C (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | -| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | -| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | -| Python | [Semgrep](https://semgrep.dev) | 13.9 | -| React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | -| Ruby | [brakeman](https://brakemanscanner.org) | 13.9 | -| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | -| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | -| Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | -| TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | +| Language (package managers) / framework | Scan tool | Introduced in GitLab Version | +|---------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| +| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | +| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0 | +| Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 | +| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | +| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.1 | +| Go | [Gosec](https://github.com/securego/gosec) | 10.7 | +| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | +| Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | +| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | +| Java (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | +| JavaScript | [Semgrep](https://semgrep.dev) | 13.10 | +| Kotlin (Android) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| Kotlin (General) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 13.11 | +| Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6 | +| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1 | +| Objective-C (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | +| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | +| Python | [Semgrep](https://semgrep.dev) | 13.9 | +| React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | +| React | [Semgrep](https://semgrep.dev) | 13.10 | +| Ruby | [brakeman](https://brakemanscanner.org) | 13.9 | +| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | +| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/), and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | +| Swift (iOS) | [MobSF (beta)](https://github.com/MobSF/Mobile-Security-Framework-MobSF) | 13.5 | +| TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | +| TypeScript | [Semgrep](https://semgrep.dev) | 13.10 | Note that the Java analyzers can also be used for variants like the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), @@ -172,7 +176,7 @@ The included template creates SAST jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. The results are saved as a -[SAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssast) +[SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast) that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. @@ -441,7 +445,7 @@ variables: -----END CERTIFICATE----- ``` -The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. +The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables), either as a `file`, which requires the path to the certificate, or as a variable, which requires the text representation of the certificate. #### Docker images @@ -513,6 +517,7 @@ removed, or promoted to regular features at any time. Experimental features available are: - Enable scanning of iOS and Android apps using the [MobSF analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/mobsf/). +- Enable the [semgrep analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/). #### Enable experimental features @@ -532,7 +537,7 @@ The SAST tool emits a JSON report file. For more information, see the [schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json). The JSON report file can be downloaded from the CI pipelines page, or the -pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/pipelines/job_artifacts.md#defining-artifacts-in-gitlab-ciyml) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). +pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml/README.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). Here's an example SAST report: @@ -703,8 +708,21 @@ offline environment, certificate verification with an external source is not pos self-signed certificate or disable certificate verification. Refer to the package manager's documentation for instructions. +## Running SAST in SELinux + +By default SAST analyzers are supported in GitLab instances hosted on SELinux. Adding a `before_script` in an [overriden SAST job](#overriding-sast-jobs) may not work as runners hosted on SELinux have restricted permissions. + ## Troubleshooting +### SAST debug logging + +Increase the [Secure scanner log verbosity](#logging-level) to `debug` in a global CI variable to help troubleshoot SAST jobs. + +```yaml +variables: + SECURE_LOG_LEVEL: "debug" +``` + ### `Error response from daemon: error processing tar file: docker-tar: relocation error` This error occurs when the Docker version that runs the SAST job is `19.03.0`. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index d2a576e9e03..f137ec26114 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -129,22 +129,10 @@ The included template creates Secret Detection jobs in your CI/CD pipeline and s your project's source code for secrets. The results are saved as a -[Secret Detection report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssecret_detection) +[Secret Detection report artifact](../../../ci/yaml/README.md#artifactsreportssecret_detection) that you can later download and analyze. Due to implementation limitations, we always take the latest Secret Detection artifact available. -### Post-processing - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. - -Upon detection of a secret, GitLab supports post processing hooks. These can be used to take actions like notifying the cloud service who issued the secret. The cloud provider can confirm the credentials and take remediation actions like revoking or reissuing a new secret and notifying the creator of the secret. Post-processing workflows vary by supported cloud providers. - -GitLab currently supports post-processing for following service providers: - -- Amazon Web Services (AWS) - -Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). Learn more about the [technical details of post-processing secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). - ### Customizing settings The Secret Detection scan settings can be changed through [CI/CD variables](#available-variables) @@ -249,6 +237,34 @@ From highest to lowest severity, the logging levels are: - `info` (default) - `debug` +## Post-processing and revocation + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4639) in GitLab 13.6. + +Upon detection of a secret, GitLab supports post-processing hooks. These can be used to take actions like notifying the cloud service who issued the secret. The cloud provider can confirm the credentials and take remediation actions like revoking or reissuing a new secret and notifying the creator of the secret. Post-processing workflows vary by supported cloud providers. + +GitLab currently supports post-processing for following service providers: + +- Amazon Web Services (AWS) + +Third party cloud and SaaS providers can [express integration interest by filling out this form](https://forms.gle/wWpvrtLRK21Q2WJL9). Learn more about the [technical details of post-processing secrets](https://gitlab.com/groups/gitlab-org/-/epics/4639). + +NOTE: +Post-processing is currently limited to a project's default branch, see the above epic for future efforts to support additional branches. + +```mermaid +sequenceDiagram + autonumber + Rails->>+Sidekiq: gl-secret-detection-report.json + Sidekiq-->+Sidekiq: BuildFinishedWorker + Sidekiq-->+RevocationAPI: GET revocable keys types + RevocationAPI-->>-Sidekiq: OK + Sidekiq->>+RevocationAPI: POST revoke revocable keys + RevocationAPI-->>-Sidekiq: ACCEPTED + RevocationAPI-->>+Cloud Vendor: revoke revocable keys + Cloud Vendor-->>+RevocationAPI: ACCEPTED +``` + ## Full History Secret Scan GitLab 12.11 introduced support for scanning the full history of a repository. This new functionality diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png Binary files differnew file mode 100644 index 00000000000..cc9f0061a31 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png Binary files differdeleted file mode 100644 index 6ccae80e80e..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_6.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 8a2c40406e2..326c88f9eef 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -39,7 +39,7 @@ The security dashboard and vulnerability report displays information about vulne 1. At least one project inside a group must be configured with at least one of the [supported reports](#supported-reports). -1. The configured jobs must use the [new `reports` syntax](../../../ci/pipelines/job_artifacts.md#artifactsreports). +1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports). 1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used. If you're using the shared runners on GitLab.com, this is already the case. @@ -71,17 +71,23 @@ CSV file containing details of the resources scanned. ## Project Security Dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in GitLab 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285476) in GitLab 13.10, options to zoom in on a date range, and download the vulnerabilities chart. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285477) in GitLab 13.11, date range slider to visualise data between given dates. At the project level, the Security Dashboard displays a chart with the number of vulnerabilities over time. Access it by navigating to **Security & Compliance > Security Dashboard**. We display historical data up to 365 days. The chart's data is updated daily. - + Filter the historical data by clicking on the corresponding legend name. The image above, for example, shows only the graph for vulnerabilities with **high** severity. +To zoom in, select the left-most icon, then select the desired rangeby dragging across the chart. Select **Remove Selection** (**{redo}**) to reset to the original date range. + +To download an SVG image of the chart, select **Save chart to an image** (**{download}**). + ## Group Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.5. @@ -152,7 +158,7 @@ found in those projects' default branches. ## Keeping the 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/index.md#default-branch), +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 diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_11.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_11.png Binary files differnew file mode 100644 index 00000000000..05df41483c4 --- /dev/null +++ b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_11.png diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png Binary files differdeleted file mode 100644 index a668ce1a3b8..00000000000 --- a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_9.png +++ /dev/null diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 747d31df356..ced4669e241 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -221,7 +221,7 @@ to set the status for each alert: By default, the list doesn't display resolved or dismissed alerts. To show these alerts, clear the checkbox **Hide dismissed alerts**. - + Clicking an alert's name takes the user to the [alert details page](../../../operations/incident_management/alerts.md#alert-details-page). diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png Binary files differdeleted file mode 100644 index a3034a7db04..00000000000 --- a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 416db5b07fc..b98d28f8c9f 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -50,7 +50,7 @@ From a vulnerability you can create either: - [A Jira issue](#create-a-jira-issue-for-a-vulnerability). Creating a Jira issue requires that -[Jira integration](../../project/integrations/jira_integrations.md) is enabled on the project. Note +[Jira integration](../../../integration/jira/index.md) is enabled on the project. Note that when Jira integration is enabled, the GitLab issue feature is not available. ### Create a GitLab issue for a vulnerability diff --git a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_9.png b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_10.png Binary files differindex f9f60810f20..f9f60810f20 100644 --- a/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_9.png +++ b/doc/user/application_security/vulnerability_report/img/project_security_dashboard_status_change_v13_10.png diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 583859e2541..8f7740f9bfc 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Report **(ULTIMATE)** The Vulnerability Report provides information about vulnerabilities from scans of the branch most -recently merged into the default branch. It is available at the instance, group, and project level. +recently merged into the default branch. It is available for groups, projects, and the Security Center. At all levels, the Vulnerability Report contains: @@ -36,6 +36,7 @@ From the Vulnerability Report you can: - [Filter the list of vulnerabilities](#filter-the-list-of-vulnerabilities). - [View more details about a vulnerability](#view-details-of-a-vulnerability). +- [View vulnerable source location](#view-vulnerable-source-location) (if available). - [View an issue raised for a vulnerability](#view-issues-raised-for-a-vulnerability). - [Change the status of vulnerabilities](#change-status-of-vulnerabilities). - [Export details of vulnerabilities](#export-vulnerability-details). @@ -72,7 +73,7 @@ The content of the Project filter depends on the current level: | Level | Content of the Project filter | |:---------------|:------------------------------| -| Instance level | Only projects you've [added to the instance-level Security Center](../security_dashboard/index.md#adding-projects-to-the-security-center). | +| Security Center | Only projects you've [added to your personal Security Center](../security_dashboard/index.md#adding-projects-to-the-security-center). | | Group level | All projects in the group. | | Project level | Not applicable. | @@ -99,6 +100,16 @@ Selection behavior when using the Activity filter: To view more details of a vulnerability, select the vulnerability's **Description**. The [vulnerability's details](../vulnerabilities) page is opened. +## View vulnerable source location + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267509) in GitLab 13.10. + +Some security scanners output the filename and line number of a potential vulnerability. When +that information is available, the vulnerability's details include a link to the relevant file, +in the default branch. + +To view the relevant file, select the filename in the vulnerability's details. + ## View issues raised for a vulnerability The **Activity** column indicates the number of issues that have been created for the vulnerability. @@ -108,12 +119,14 @@ Hover over an **Activity** entry and select a link go to that issue. ## Change status of vulnerabilities +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292636) in GitLab 13.10, all statuses became selectable. + To change the status of vulnerabilities in the table: 1. Select the checkbox for each vulnerability you want to update the status of. 1. In the dropdown that appears select the desired status, then select **Change status**. - + ## Export vulnerability details |
