Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitlab-foss.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGitLab Bot <gitlab-bot@gitlab.com>2021-07-20 12:55:51 +0300
committerGitLab Bot <gitlab-bot@gitlab.com>2021-07-20 12:55:51 +0300
commite8d2c2579383897a1dd7f9debd359abe8ae8373d (patch)
treec42be41678c2586d49a75cabce89322082698334 /doc/user/application_security
parentfc845b37ec3a90aaa719975f607740c22ba6a113 (diff)
Add latest changes from gitlab-org/gitlab@14-1-stable-eev14.1.0-rc42
Diffstat (limited to 'doc/user/application_security')
-rw-r--r--doc/user/application_security/api_fuzzing/create_har_files.md2
-rw-r--r--doc/user/application_security/api_fuzzing/index.md14
-rw-r--r--doc/user/application_security/cluster_image_scanning/index.md281
-rw-r--r--doc/user/application_security/configuration/index.md79
-rw-r--r--doc/user/application_security/container_scanning/index.md34
-rw-r--r--doc/user/application_security/coverage_fuzzing/index.md10
-rw-r--r--doc/user/application_security/dast/browser_based.md6
-rw-r--r--doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.pngbin203980 -> 62252 bytes
-rw-r--r--doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.pngbin155046 -> 46272 bytes
-rw-r--r--doc/user/application_security/dast/index.md203
-rw-r--r--doc/user/application_security/dast_api/index.md16
-rw-r--r--doc/user/application_security/dependency_list/index.md2
-rw-r--r--doc/user/application_security/dependency_scanning/index.md82
-rw-r--r--doc/user/application_security/index.md44
-rw-r--r--doc/user/application_security/offline_deployments/index.md4
-rw-r--r--doc/user/application_security/policies/index.md4
-rw-r--r--doc/user/application_security/sast/img/sast_results_in_mr_v14_0.pngbin0 -> 38616 bytes
-rw-r--r--doc/user/application_security/sast/index.md42
-rw-r--r--doc/user/application_security/secret_detection/index.md62
-rw-r--r--doc/user/application_security/security_dashboard/index.md5
-rw-r--r--doc/user/application_security/terminology/index.md1
-rw-r--r--doc/user/application_security/threat_monitoring/index.md23
-rw-r--r--doc/user/application_security/vulnerabilities/index.md2
-rw-r--r--doc/user/application_security/vulnerability_report/index.md4
24 files changed, 707 insertions, 213 deletions
diff --git a/doc/user/application_security/api_fuzzing/create_har_files.md b/doc/user/application_security/api_fuzzing/create_har_files.md
index 1162984a02d..7940e072420 100644
--- a/doc/user/application_security/api_fuzzing/create_har_files.md
+++ b/doc/user/application_security/api_fuzzing/create_har_files.md
@@ -12,7 +12,7 @@ requests and HTTP responses. A HAR file's content is JSON formatted, containing
with a web site. The file extension `.har` is commonly used.
The HAR files can be used to perform [web API Fuzz Testing](index.md#http-archive-har) as part of
-your [GitLab CI/CD](../../../ci/README.md) pipelines.
+your [GitLab CI/CD](../../../ci/index.md) pipelines.
WARNING:
A HAR file stores information exchanged between web client and web server. It could also
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md
index 2b2ac76a7af..e35415003c7 100644
--- a/doc/user/application_security/api_fuzzing/index.md
+++ b/doc/user/application_security/api_fuzzing/index.md
@@ -13,7 +13,7 @@ backend. This helps you discover bugs and potential security issues that other Q
miss.
We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s
-other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md),
+other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md),
you can run fuzz tests as part your CI/CD workflow.
## When Web API fuzzing runs
@@ -134,7 +134,7 @@ To configure API fuzzing in GitLab with an OpenAPI Specification:
1. Add the `fuzz` stage to your `.gitlab-ci.yml` file.
-1. [Include](../../../ci/yaml/README.md#includetemplate)
+1. [Include](../../../ci/yaml/index.md#includetemplate)
the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml)
in your `.gitlab-ci.yml` file.
@@ -200,7 +200,7 @@ To configure API fuzzing to use a HAR file:
1. Add the `fuzz` stage to your `.gitlab-ci.yml` file.
-1. [Include](../../../ci/yaml/README.md#includetemplate)
+1. [Include](../../../ci/yaml/index.md#includetemplate)
the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml)
in your `.gitlab-ci.yml` file.
@@ -271,7 +271,7 @@ To configure API fuzzing to use a Postman Collection file:
1. Add the `fuzz` stage to your `.gitlab-ci.yml` file.
-1. [Include](../../../ci/yaml/README.md#includetemplate)
+1. [Include](../../../ci/yaml/index.md#includetemplate)
the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml)
in your `.gitlab-ci.yml` file.
@@ -400,7 +400,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#custom-cicd-variables)
+For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/index.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`:
@@ -438,7 +438,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#custom-cicd-variables),
+1. [Create a CI/CD variable](../../../ci/variables/index.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
@@ -780,7 +780,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#add-a-cicd-variable-to-an-instance):
+[group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#add-a-cicd-variable-to-an-instance):
```yaml
stages:
diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md
new file mode 100644
index 00000000000..abbe00a85ab
--- /dev/null
+++ b/doc/user/application_security/cluster_image_scanning/index.md
@@ -0,0 +1,281 @@
+---
+type: reference, howto
+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/#assignments
+---
+
+# Cluster Image Scanning **(ULTIMATE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 14.1.
+
+WARNING:
+This analyzer is in [Alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha)
+and is unstable. The JSON report and CI/CD configuration may be subject to change or breakage
+across GitLab releases.
+
+Your Kubernetes cluster may run workloads based on images that the Container Security analyzer
+didn't scan. These images may therefore contain known vulnerabilities. By including an extra job in
+your pipeline that scans for those security risks and displays them in the vulnerability report, you
+can use GitLab to audit your Kubernetes workloads and environments.
+
+GitLab provides integration with open-source tools for vulnerability analysis in Kubernetes clusters:
+
+- [Starboard](https://github.com/aquasecurity/starboard)
+
+To integrate GitLab with security scanners other than those listed here, see
+[Security scanner integration](../../../development/integrations/secure.md).
+
+You can enable cluster image scanning by [including the CI job](#configuration)
+in your existing `.gitlab-ci.yml` file.
+
+## Prerequisites
+
+To enable cluster image scanning in your pipeline, you need the following:
+
+- [GitLab Runner](https://docs.gitlab.com/runner/)
+ with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html)
+ or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html)
+ executor.
+- Docker `18.09.03` or later installed on the same computer as the runner. If you're using the
+ shared runners on GitLab.com, then this is already the case.
+- [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/installation/kubectl/)
+ installed and configured in your cluster.
+- The configuration for accessing your Kubernetes cluster stored in the `CIS_KUBECONFIG`
+ [configuration variable](#cicd-variables-for-cluster-image-scanning)
+ with the type set to `File` (see [Configuring the cluster](#configuring-the-cluster)).
+
+## Configuring the cluster
+
+1. Create a new service account.
+
+ To properly fetch vulnerabilities from the cluster and to limit analyzer access to the workload,
+ you must create a new service account with the cluster role limited to `get`, `list`, and `watch`
+ `vulnerabilityreports` in the Kubernetes cluster:
+
+ ```shell
+ kubectl apply -f https://gitlab.com/gitlab-org/security-products/analyzers/cluster-image-scanning/-/raw/main/gitlab-vulnerability-viewer-service-account.yaml
+ ```
+
+1. Obtain the Kubernetes API URL.
+
+ Get the API URL by running this command:
+
+ ```shell
+ API_URL=$(kubectl cluster-info | grep -E 'Kubernetes master|Kubernetes control plane' | awk '/http/ {print $NF}')
+ ```
+
+1. Obtain the CA certificate:
+
+ 1. List the secrets with `kubectl get secrets`. One should have a name similar to
+ `default-token-xxxxx`. Copy that token name for use below.
+
+ 1. Run this command to get the certificate:
+
+ ```shell
+ CA_CERTIFICATE=$(kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}")
+ ```
+
+1. Obtain the service account token:
+
+ ```shell
+ TOKEN=$(kubectl -n kube-system get secret $(kubectl -n kube-system get secret | grep gitlab-vulnerability-viewer | awk '{print $1}') -o jsonpath="{.data.token}" | base64 --decode)
+ ```
+
+1. Generate the value for the `CIS_KUBECONFIG` variable. Copy the printed value from the output:
+
+ ```shell
+ echo "
+ ---
+ apiVersion: v1
+ kind: Config
+ clusters:
+ - name: gitlab-vulnerabilities-viewer
+ cluster:
+ server: $API_URL
+ certificate-authority-data: $CA_CERTIFICATE
+ contexts:
+ - name: gitlab-vulnerabilities-viewer
+ context:
+ cluster: gitlab-vulnerabilities-viewer
+ namespace: default
+ user: gitlab-vulnerabilities-viewer
+ current-context: gitlab-vulnerabilities-viewer
+ users:
+ - name: gitlab-vulnerabilities-viewer
+ user:
+ token: $TOKEN
+ "
+ ```
+
+1. Set the CI/CD variable:
+
+ 1. Navigate to your project's **Settings > CI/CD**.
+
+ 1. Expand the **Variables** section.
+
+ 1. Select **Add variable** and fill in the details:
+
+ - **Key**: `CIS_KUBECONFIG`.
+ - **Value**: `generated value`
+ - **Type**: `File`
+
+WARNING:
+The `CIS_KUBECONFIG` variable is accessible by all jobs executed for your project. Mark the
+`Protect variable` flag to export this variable to pipelines running on protected branches and tags
+only. You can apply additional protection to your cluster by
+[restricting service account access to a single namespace](https://kubernetes.io/docs/reference/access-authn-authz/rbac/),
+and [configuring Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/configuration/#install-modes)
+to install in restricted mode.
+
+## Configuration
+
+To include the `Cluster-Image-Scanning.gitlab-ci.yml` template (GitLab 14.1 and later), add the
+following to your `.gitlab-ci.yml` file:
+
+```yaml
+include:
+ - template: Security/Cluster-Image-Scanning.gitlab-ci.yml
+```
+
+The included template:
+
+- Creates a `cluster_image_scanning` job in your CI/CD pipeline.
+- Connects to your Kubernetes cluster with credentials provided in the `CIS_KUBECONFIG` variable and
+ fetches vulnerabilities found by [Starboard Operator](https://aquasecurity.github.io/starboard/v0.10.3/operator/).
+
+GitLab saves the results as a
+[Cluster Image Scanning report artifact](../../../ci/yaml/index.md#artifactsreportscluster_image_scanning)
+that you can download and analyze later. When downloading, you always receive the most recent
+artifact.
+
+### Customize the cluster image scanning settings
+
+You can customize how GitLab scans your cluster. For example, to restrict the analyzer to get
+results for only a certain workload, use the [`variables`](../../../ci/yaml/index.md#variables)
+parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#cicd-variables-for-cluster-image-scanning).
+The variables you set in your `.gitlab-ci.yml` overwrite those in
+`Cluster-Image-Scanning.gitlab-ci.yml`.
+
+#### CI/CD variables for cluster image scanning
+
+You can [configure](#customize-the-cluster-image-scanning-settings) analyzers by using the following CI/CD variables:
+
+| CI/CD Variable | Default | Description |
+| ------------------------------ | ------------- | ----------- |
+| `CIS_KUBECONFIG` | `""` | File used to configure access to the Kubernetes cluster. See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) for more details. |
+| `CIS_CONTAINER_NAME` | `""` | Name of the container used in the Kubernetes resource you want to filter vulnerabilities for. For example, `alpine`. |
+| `CIS_RESOURCE_NAME` | `""` | Name of the Kubernetes resource you want to filter vulnerabilities for. For example, `nginx`. |
+| `CIS_RESOURCE_NAMESPACE` | `""` | Namespace of the Kubernetes resource you want to filter vulnerabilities for. For example, `production`. |
+| `CIS_RESOURCE_KIND` | `""` | Kind of the Kubernetes resource you want to filter vulnerabilities for. For example, `deployment`. |
+
+### Override the cluster image scanning template
+
+If you want to override the job definition (for example, to change properties like `variables`), you
+must declare and override a job after the template inclusion, and then
+specify any additional keys.
+
+This example sets `CIS_RESOURCE_NAME` to `nginx`:
+
+```yaml
+include:
+ - template: Security/Cluster-Image-Scanning.gitlab-ci.yml
+
+cluster_image_scanning:
+ variables:
+ CIS_RESOURCE_NAME: nginx
+```
+
+### Connect with Kubernetes cluster associated to the project
+
+If you want to connect to the Kubernetes cluster associated with the project and run Cluster Image Scanning jobs without
+configuring the `CIS_KUBECONFIG` variable, you must extend `cluster_image_scanning` and specify the environment you want to scan.
+
+This example configures the `cluster_image_scanning` job to scan the Kubernetes cluster connected with the `staging` environment:
+
+```yaml
+cluster_image_scanning:
+ environment:
+ name: staging
+ action: prepare
+```
+
+## Reports JSON format
+
+The cluster image scanning tool emits a JSON report file. For more information, see the
+[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json).
+
+Here's an example cluster image scanning report:
+
+```json-doc
+{{
+ "version": "14.0.2",
+ "scan": {
+ "scanner": {
+ "id": "starboard_trivy",
+ "name": "Trivy (using Starboard Operator)",
+ "url": "https://github.com/aquasecurity/starboard",
+ "vendor": {
+ "name": "GitLab"
+ },
+ "version": "0.16.0"
+ },
+ "start_time": "2021-04-28T12:47:00Z",
+ "end_time": "2021-04-28T12:47:00Z",
+ "type": "cluster_image_scanning",
+ "status": "success"
+ },
+ "vulnerabilities": [
+ {
+ "id": "c15f22205ee842184c2d55f1a207b3708283353f85083d66c34379c709b0ac9d",
+ "category": "cluster_image_scanning",
+ "message": "CVE-2011-3374 in apt",
+ "description": "",
+ "cve": "library/nginx:1.18:apt:CVE-2011-3374",
+ "severity": "Low",
+ "confidence": "Unknown",
+ "solution": "Upgrade apt from 1.8.2.2",
+ "scanner": {
+ "id": "starboard_trivy",
+ "name": "Trivy (using Starboard Operator)"
+ },
+ "location": {
+ "dependency": {
+ "package": {
+ "name": "apt"
+ },
+ "version": "1.8.2.2"
+ },
+ "operating_system": "library/nginx:1.18",
+ "image": "index.docker.io/library/nginx:1.18"
+ },
+ "identifiers": [
+ {
+ "type": "cve",
+ "name": "CVE-2011-3374",
+ "value": "CVE-2011-3374",
+ "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3374"
+ }
+ ],
+ "links": [
+ "https://avd.aquasec.com/nvd/cve-2011-3374"
+ ]
+ }
+ ]
+}
+```
+
+## Security Dashboard
+
+The [Security Dashboard](../security_dashboard/index.md) shows you an overview of all
+the security vulnerabilities in your groups, projects, and pipelines.
+
+## Interacting with the vulnerabilities
+
+After a vulnerability is found, you can [address it](../vulnerabilities/index.md).
+
+## Troubleshooting
+
+### Getting warning message `gl-cluster-image-scanning-report.json: no matching files`
+
+For information on this error, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload).
diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md
index 8c34303ca00..3cc88a40b6f 100644
--- a/doc/user/application_security/configuration/index.md
+++ b/doc/user/application_security/configuration/index.md
@@ -25,6 +25,32 @@ For each security control the page displays:
- **Security Control:** Name, description, and a documentation link.
- **Manage:** A management option or a documentation link.
+## UI redesign
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326926) in 14.0 for GitLab Free and Premium, behind a feature flag, disabled by default.
+> - Enabled on GitLab.com for Free & Premium.
+> - Recommended for production use.
+> - It can be enabled or disabled for a single project.
+> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ui-redesign). **(FREE SELF)**
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/333109) in 14.1 for GitLab Ultimate, behind a feature flag, disabled by default.
+> - Disabled on GitLab.com.
+> - Not recommended for production use.
+> - It can be enabled or disabled for a single project.
+> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ui-redesign-for-ultimate). **(ULTIMATE SELF)**
+
+WARNING:
+This feature might not be available to you. Check the **version history** note above for details.
+
+The Security Configuration page has been redesigned in GitLab Free and Premium.
+The same functionality exists as before, but presented in a more extensible
+way.
+
+For each security control the page displays:
+
+- Its name, description and a documentation link.
+- Whether or not it is available.
+- A configuration button or a link to its configuration guide.
+
## Status **(ULTIMATE)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6.
@@ -52,3 +78,56 @@ You can configure the following security controls:
- Secret Detection
- Select **Configure via Merge Request** to create a merge request with the changes required to
enable Secret Detection. For more details, see [Enable Secret Detection via an automatic merge request](../secret_detection/index.md#enable-secret-detection-via-an-automatic-merge-request).
+- Dependency Scanning
+ - Select **Configure via Merge Request** to create a merge request with the changes required to
+ enable Dependency Scanning. For more details, see [Enable Dependency Scanning via an automatic merge request](../dependency_scanning/index.md#enable-dependency-scanning-via-an-automatic-merge-request).
+
+## Enable or disable UI redesign **(FREE SELF)**
+
+The Security Configuration redesign is under development, but is ready for
+production use. It is deployed behind a feature flag that is **disabled by
+default**.
+[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it.
+
+To enable it:
+
+```ruby
+# For the instance
+Feature.enable(:security_configuration_redesign)
+# For a single project
+Feature.enable(:security_configuration_redesign, Project.find(<project id>))
+```
+
+To disable it:
+
+```ruby
+# For the instance
+Feature.disable(:security_configuration_redesign)
+# For a single project
+Feature.disable(:security_configuration_redesign, Project.find(<project id>))
+```
+
+## Enable or disable UI redesign for Ultimate **(ULTIMATE SELF)**
+
+The Security Configuration redesign is under development, and is not ready for
+production use. It is deployed behind a feature flag that is **disabled by
+default**.
+[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) can enable it.
+
+To enable it:
+
+```ruby
+# For the instance
+Feature.enable(:security_configuration_redesign_ee)
+# For a single project
+Feature.enable(:security_configuration_redesign_ee, Project.find(<project id>))
+```
+
+To disable it:
+
+```ruby
+# For the instance
+Feature.disable(:security_configuration_redesign_ee)
+# For a single project
+Feature.disable(:security_configuration_redesign_ee, Project.find(<project id>))
+```
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md
index 323a064c3e4..90e1e4b025c 100644
--- a/doc/user/application_security/container_scanning/index.md
+++ b/doc/user/application_security/container_scanning/index.md
@@ -59,7 +59,7 @@ To enable container scanning in your pipeline, you need the following:
How you enable container scanning depends on your GitLab version:
-- GitLab 11.9 and later: [Include](../../../ci/yaml/README.md#includetemplate) the
+- GitLab 11.9 and later: [Include](../../../ci/yaml/index.md#includetemplate) the
[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml)
that comes with your GitLab installation.
- GitLab versions earlier than 11.9: Copy and use the job from the
@@ -73,8 +73,8 @@ Other changes:
[`centos:centos8`](https://hub.docker.com/_/centos)
as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77)
script and instead executes the analyzer by default. Any customizations made to the
- `container_scanning` job's [`before_script`](../../../ci/yaml/README.md#before_script)
- and [`after_script`](../../../ci/yaml/README.md#after_script)
+ `container_scanning` job's [`before_script`](../../../ci/yaml/index.md#before_script)
+ and [`after_script`](../../../ci/yaml/index.md#after_script)
blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based
Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables)
variable.
@@ -101,7 +101,7 @@ The included template:
(see [requirements](#requirements)) and scans it for possible vulnerabilities.
GitLab saves the results as a
-[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning)
+[Container Scanning report artifact](../../../ci/yaml/index.md#artifactsreportscontainer_scanning)
that you can download and analyze later. When downloading, you always receive the most-recent
artifact.
@@ -130,12 +130,12 @@ include:
There may be cases where you want to customize how GitLab scans your containers. For example, you
may want to enable more verbose output, access a Docker registry that requires
-authentication, and more. To change such settings, use the [`variables`](../../../ci/yaml/README.md#variables)
+authentication, and more. To change such settings, use the [`variables`](../../../ci/yaml/index.md#variables)
parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#available-cicd-variables).
The variables you set in your `.gitlab-ci.yml` overwrite those in
`Container-Scanning.gitlab-ci.yml`.
-This example [includes](../../../ci/yaml/README.md#include) the container scanning template and
+This example [includes](../../../ci/yaml/index.md#include) the container scanning template and
enables verbose output for the analyzer:
```yaml
@@ -172,6 +172,21 @@ Support depends on the scanner:
- [Grype](https://github.com/anchore/grype#grype)
- [Trivy](https://aquasecurity.github.io/trivy/latest/vuln-detection/os/) (Default).
+#### UBI-based images
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 14.1.
+
+GitLab also offers [Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image)
+versions of the container-scanning images. You can therefore replace standard images with UBI-based
+images. To configure the images, set the `CS_ANALYZER_IMAGE` variable to the standard tag plus the
+`-ubi` extension.
+
+| Scanner name | `CS_ANALYZER_IMAGE` |
+| --------------- | ------------------- |
+| Default (Trivy) | `registry.gitlab.com/security-products/container-scanning:4-ubi` |
+| Grype | `registry.gitlab.com/security-products/container-scanning/grype:4-ubi` |
+| Trivy | `registry.gitlab.com/security-products/container-scanning/trivy:4-ubi` |
+
### Overriding the container scanning template
If you want to override the job definition (for example, to change properties like `variables`), you
@@ -189,11 +204,6 @@ container_scanning:
GIT_STRATEGY: fetch
```
-WARNING:
-GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/README.md#only--except).
-When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules)
-instead.
-
### Change scanners
The container-scanning analyzer can use different scanners, depending on the value of the
@@ -256,7 +266,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#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.
+The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.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
diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md
index b46547b6828..679d20a6394 100644
--- a/doc/user/application_security/coverage_fuzzing/index.md
+++ b/doc/user/application_security/coverage_fuzzing/index.md
@@ -13,7 +13,7 @@ random inputs to an instrumented version of your application in an effort to cau
behavior, such as a crash. Such behavior indicates a bug that you should address.
We recommend that you use fuzz testing in addition to the other security scanners in [GitLab Secure](../index.md)
-and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md),
+and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md),
you can run your coverage-guided fuzz tests as part your CI/CD workflow. You can take advantage of
coverage-guided fuzzing by including the CI job in your existing `.gitlab-ci.yml` file.
@@ -38,7 +38,7 @@ Docker image with the fuzz engine to run your app.
## Configuration
To enable fuzzing, you must
-[include](../../../ci/yaml/README.md#includetemplate)
+[include](../../../ci/yaml/index.md#includetemplate)
the [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml)
provided as part of your GitLab installation.
@@ -59,8 +59,8 @@ my_fuzz_target:
- ./gitlab-cov-fuzz run --regression=$REGRESSION -- <your fuzz target>
```
-The included template makes available the [hidden job](../../../ci/yaml/README.md#hide-jobs)
-`.fuzz_base`, which you must [extend](../../../ci/yaml/README.md#extends) for each of your fuzz
+The included template makes available the [hidden job](../../../ci/yaml/index.md#hide-jobs)
+`.fuzz_base`, which you must [extend](../../../ci/yaml/index.md#extends) for each of your fuzz
targets. Each fuzz target **must** have a separate job. For example, the
[go-fuzzing-example project](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example)
contains one job that extends `.fuzz_base` for its single fuzz target.
@@ -192,7 +192,7 @@ To use coverage fuzzing in an offline environment, follow these steps:
### Continuous fuzzing (long-running asynchronous fuzzing jobs)
It's also possible to run the fuzzing jobs longer and without blocking your main pipeline. This
-configuration uses the GitLab [parent-child pipelines](../../../ci/parent_child_pipelines.md).
+configuration uses the GitLab [parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md).
The full example is available in the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing#running-go-fuzz-from-ci).
This example uses Go, but is applicable for any other supported languages.
diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md
index 072f6fba4ba..1288db21880 100644
--- a/doc/user/application_security/dast/browser_based.md
+++ b/doc/user/application_security/dast/browser_based.md
@@ -21,7 +21,7 @@ Crawling continues by taking more snapshots and finding subsequent actions.
The benefit of crawling by following user actions in a browser is that the crawler can interact with the target application much like a real user would, identifying complex flows that traditional web crawlers don’t understand. This results in better coverage of the website.
-Scanning a web application with both the browser-based crawler and GitLab DAST should provide greater coverage, compared with only GitLab DAST. The new crawler does not support API scanning or the DAST AJAX crawler.
+Using the browser-based crawler should provide greater coverage for most web applications, compared with the current DAST AJAX crawler. The new crawler replaces the AJAX crawler and is specifically designed to maximize crawl coverage in modern web applications. While both crawlers are currently used in conjunction with the existing DAST scanner, the combination of the browser-based crawler with the current DAST scanner is much more effective at finding and testing every page in an application.
## Enable browser-based crawler
@@ -63,8 +63,8 @@ The browser-based crawler can be configured using CI/CD variables.
The [DAST variables](index.md#available-cicd-variables) `SECURE_ANALYZERS_PREFIX`, `DAST_FULL_SCAN_ENABLED`, `DAST_AUTO_UPDATE_ADDONS`, `DAST_EXCLUDE_RULES`, `DAST_REQUEST_HEADERS`, `DAST_HTML_REPORT`, `DAST_MARKDOWN_REPORT`, `DAST_XML_REPORT`,
`DAST_AUTH_URL`, `DAST_USERNAME`, `DAST_PASSWORD`, `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, `DAST_SUBMIT_FIELD`, `DAST_EXCLUDE_URLS`, `DAST_AUTH_VERIFICATION_URL`, `DAST_BROWSER_AUTH_VERIFICATION_SELECTOR`, `DAST_BROWSER_AUTH_VERIFICATION_LOGIN_FORM`, `DAST_BROWSER_AUTH_REPORT`,
-`DAST_INCLUDE_ALPHA_VULNERABILITIES`, `DAST_PATHS_FILE`, `DAST_PATHS`, `DAST_ZAP_CLI_OPTIONS`, and `DAST_ZAP_LOG_CONFIGURATION` are also compatible with browser-based crawler scans.
-
+`DAST_INCLUDE_ALPHA_VULNERABILITIES`, `DAST_PATHS_FILE`, `DAST_PATHS`, `DAST_ZAP_CLI_OPTIONS`, and `DAST_ZAP_LOG_CONFIGURATION` are also compatible with browser-based crawler scans.
+
## Vulnerability detection
While the browser-based crawler crawls modern web applications efficiently, vulnerability detection is still managed by the standard DAST/Zed Attack Proxy (ZAP) solution.
diff --git a/doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png b/doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png
index 132c9f9c991..3369956a5ed 100644
--- a/doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png
+++ b/doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png
Binary files differ
diff --git a/doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png b/doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png
index 4e1dca626bc..34e7a2e4ab4 100644
--- a/doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png
+++ b/doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png
Binary files differ
diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md
index 675d01373d4..4b10f03fec3 100644
--- a/doc/user/application_security/dast/index.md
+++ b/doc/user/application_security/dast/index.md
@@ -50,7 +50,7 @@ results. On failure, the analyzer outputs an
## Prerequisites
-- [GitLab Runner](../../../ci/runners/README.md) available, with the
+- [GitLab Runner](../../../ci/runners/index.md) available, with the
[`docker` executor](https://docs.gitlab.com/runner/executors/docker.html).
- Target application deployed. For more details, read [Deployment options](#deployment-options).
@@ -145,6 +145,7 @@ To enable DAST to run automatically, either:
by [Auto DevOps](../../../topics/autodevops/index.md)).
- [Include the DAST template](#include-the-dast-template) in your existing
`.gitlab-ci.yml` file.
+- [Configure DAST using the UI](#configure-dast-using-the-ui).
### DAST job order
@@ -202,7 +203,7 @@ To include the DAST template:
1. Add the template to GitLab, based on your version of GitLab:
- - In GitLab 11.9 and later, [include](../../../ci/yaml/README.md#includetemplate)
+ - In GitLab 11.9 and later, [include](../../../ci/yaml/index.md#includetemplate)
the template by adding the following to your `.gitlab-ci.yml` file:
```yaml
@@ -218,7 +219,7 @@ To include the DAST template:
1. Define the URL to be scanned by DAST by using one of these methods:
- - Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/README.md#variables).
+ - Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/index.md#variables).
If set, this value takes precedence.
- Add the URL in an `environment_url.txt` file at the root of your project. This is
@@ -247,10 +248,10 @@ 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/yaml/README.md#artifactsreportsdast)
+[DAST report artifact](../../../ci/yaml/index.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)
+[GitLab DAST Docker image](https://gitlab.com/security-products/dast)
is used to run the tests on the specified URL and scan it for possible
vulnerabilities.
@@ -262,9 +263,31 @@ image. Using the `DAST_VERSION` variable, you can choose how DAST updates:
- 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)
+Find the latest DAST versions on the [Releases](https://gitlab.com/security-products/dast/-/releases)
page.
+#### Configure DAST using the UI
+
+You can enable or configure DAST settings using the UI. The generated settings are formatted so they
+can be conveniently pasted into the `.gitlab-ci.yml` file.
+
+1. From the project's home page, go to **Security & Compliance > Configuration**.
+1. In the **Dynamic Application Security Testing (DAST)** section, select **Enable DAST** or
+ **Configure DAST**.
+1. Select the desired **Scanner profile**, or select **Create scanner profile** and save a
+ scanner profile. For more details, see [scanner profiles](#scanner-profile).
+1. Select the desired **Site profile**, or select **Create site profile** and save a site
+ profile. For more details, see [site profiles](#site-profile).
+1. Select **Generate code snippet**. A modal opens with the YAML snippet corresponding to the
+ options you selected.
+1. Do one of the following:
+ 1. Select **Copy code only** to copy the snippet to your clipboard.
+ 1. Select **Copy code and open `.gitlab-ci.yml` file** to copy the snippet to your clipboard. The
+ CI/CD Editor then opens.
+ 1. Paste the snippet into the `.gitlab-ci.yml` file.
+ 1. Select the **Lint** tab to confirm the edited `.gitlab-ci.yml` file is valid.
+ 1. Select **Commit changes**.
+
#### Crawling web applications dependent on JavaScript
GitLab has released a new browser-based crawler, an add-on to DAST that uses a browser to crawl web applications for content. This crawler replaces the standard DAST Spider and Ajax Crawler, and uses the same authentication mechanisms as a normal DAST scan.
@@ -487,11 +510,11 @@ To view details of vulnerabilities detected by DAST:
### Customizing the DAST settings
WARNING:
-Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except)
-is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead.
+Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except)
+is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead.
The DAST settings can be changed through CI/CD variables by using the
-[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
+[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`.
These variables are documented in [available variables](#available-cicd-variables).
For example:
@@ -505,7 +528,7 @@ variables:
DAST_SPIDER_MINS: 120
```
-Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline
+Because the template is [evaluated before](../../../ci/yaml/index.md#include) the pipeline
configuration, the last mention of the variable takes precedence.
#### Enabling and disabling rules
@@ -523,7 +546,7 @@ DAST scan with both configured exits with an error.
By default, several rules are disabled because they either take a long time to
run or frequently generate false positives. The complete list of disabled rules
-can be found in [exclude_rules.yml](https://gitlab.com/gitlab-org/security-products/dast/-/blob/master/src/config/exclude_rules.yml).
+can be found in [exclude_rules.yml](https://gitlab.com/gitlab-org/security-products/dast/-/blob/main/src/config/exclude_rules.yml).
### Hide sensitive information
@@ -550,7 +573,7 @@ you periodically confirm the scanner's authentication is still working, as this
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#custom-cicd-variables).
+To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/index.md#custom-cicd-variables).
The key of the username variable must be `DAST_USERNAME`,
and the key of the password variable must be `DAST_PASSWORD`.
@@ -570,6 +593,7 @@ dast:
variables:
DAST_WEBSITE: "https://example.com"
DAST_AUTH_URL: "https://login.example.com/"
+ DAST_BROWSER_PATH_TO_LOGIN_FORM: "css:.navigation-menu,css:.login-menu-item" # optional list of selectors that should be clicked on prior to attempting to input username/password into the sign-in HTML form
DAST_USERNAME: "admin"
DAST_PASSWORD: "P@55w0rd!"
DAST_USERNAME_FIELD: "name:username" # a selector describing the element containing the username field at the sign-in HTML form
@@ -646,7 +670,7 @@ dast:
DAST_WEBSITE: "https://example.com"
...
DAST_AUTH_VERIFICATION_URL: "https://example.com/user/welcome"
-```
+```
#### Verify based on presence of an element
@@ -664,7 +688,7 @@ dast:
DAST_WEBSITE: "https://example.com"
...
DAST_AUTH_VERIFICATION_SELECTOR: "css:.welcome-user"
-```
+```
#### Verify based on presence of a login form
@@ -682,7 +706,38 @@ dast:
DAST_WEBSITE: "https://example.com"
...
DAST_AUTH_VERIFICATION_LOGIN_FORM: "true"
-```
+```
+
+### View the login form
+
+Many web applications show the user the login form in a pop-up (modal) window.
+For these applications, navigating to the form requires both:
+
+- A starting URL.
+- A list of elements to click to display the modal window.
+
+When `DAST_BROWSER_PATH_TO_LOGIN_FORM` is present, like in this example:
+
+```yaml
+include:
+ - template: DAST.gitlab-ci.yml
+
+dast:
+ variables:
+ DAST_WEBSITE: "https://my.site.com"
+ ...
+ DAST_AUTH_URL: "https://my.site.com/admin"
+ DAST_BROWSER_PATH_TO_LOGIN_FORM: "css:.navigation-menu,css:.login-menu-item"
+```
+
+DAST performs these actions:
+
+1. Load the `DAST_AUTH_URL` page, such as `https://my.site.com/admin`.
+1. After the page loads, DAST selects elements found by the selectors described
+ in `DAST_BROWSER_PATH_TO_LOGIN_FORM`. This example opens the navigation menu
+ and selects the login menu, to display the login modal window.
+1. To continue the authentication process, DAST fills in the username and password
+ on the login form.
### Configure the authentication debug output
@@ -702,55 +757,60 @@ dast:
DAST_AUTH_REPORT: "true"
artifacts:
paths: [gl-dast-debug-auth-report.html]
+ when: always
```
### Available CI/CD variables
-DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables.
-
-| CI/CD variable | Type | Description |
-|:--------------------------------------------|:--------------|:-----------------------------------|
-| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. |
-| `DAST_WEBSITE` (**1**) | URL | The URL of the website to scan. `DAST_API_OPENAPI` must be specified if this is omitted. |
-| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. |
-| `DAST_API_SPECIFICATION` (**1**) | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. |
-| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. |
-| `DAST_AUTH_URL` (**1**) | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. |
-| `DAST_AUTH_VERIFICATION_URL` (**1**) | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. |
-| `DAST_USERNAME` (**1**) | string | The username to enter into the username field on the sign-in HTML form. |
-| `DAST_PASSWORD` (**1**) | string | The password to enter into the password field on the sign-in HTML form. |
-| `DAST_USERNAME_FIELD` (**1**) | selector | A selector describing the username field on the sign-in HTML form. Example: `id:user` |
-| `DAST_PASSWORD_FIELD` (**1**) | selector | A selector describing the password field on the sign-in HTML form. Example: `css:.password-field` |
-| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. |
-| `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` (**1**) | 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` (**1**) | 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_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` (**1**) | 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://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. |
-| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. |
-| `DAST_REQUEST_HEADERS` (**1**) | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` |
-| `DAST_DEBUG` (**1**) | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
-| `DAST_TARGET_AVAILABILITY_TIMEOUT` (**1**) | number | Time limit in seconds to wait for target availability.
-| `DAST_SPIDER_MINS` (**1**) | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
-| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
-| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
-| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
-| `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` (**1**) | 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. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. |
-| `DAST_SUBMIT_FIELD` | selector | A selector describing the element that when clicked submits the login form, or the password form of a multi-page login process. Example: `xpath://input[@value='Login']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. |
-| `DAST_FIRST_SUBMIT_FIELD` | selector | A selector describing the element that when clicked submits the username form of a multi-page login process. Example: `.submit`. [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. |
-| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` |
-| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. |
-| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. |
-| `DAST_AUTH_REPORT` | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. |
-| `DAST_AUTH_VERIFICATION_SELECTOR` | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo` |
-| `DAST_AUTH_VERIFICATION_LOGIN_FORM` | boolean | Verifies successful authentication by checking for the lack of a login form once the login form has been submitted. |
-
-1. DAST CI/CD variable available to an on-demand scan.
+You can use CI/CD variables to customize DAST.
+
+| CI/CD variable | Type | Description |
+|:------------------------------------------------|:--------------|:-------------------------------|
+| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. |
+| `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. `DAST_API_OPENAPI` must be specified if this is omitted. |
+| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. |
+| `DAST_API_SPECIFICATION` <sup>1</sup> | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. |
+| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. |
+| `DAST_AUTH_URL` <sup>1</sup> | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. |
+| `DAST_BROWSER_PATH_TO_LOGIN_FORM` <sup>1</sup> | selector | Comma-separated list of selectors that will be clicked on prior to attempting to enter `DAST_USERNAME` and `DAST_PASSWORD` into the login form. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326633) in GitLab 14.1. |
+| `DAST_USERNAME` <sup>1</sup> | string | The username to authenticate to in the website. |
+| `DAST_PASSWORD` <sup>1</sup> | string | The password to authenticate to in the website. |
+| `DAST_USERNAME_FIELD` <sup>1</sup> | string | The name of username field at the sign-in HTML form. |
+| `DAST_PASSWORD_FIELD` <sup>1</sup> | string | The name of password field at the sign-in HTML form. |
+| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. |
+| `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` <sup>1</sup> | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. |
+| `DAST_FULL_SCAN_ENABLED` <sup>1</sup> | 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 | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/293595)** in GitLab 14.0. Set to `true` to require domain validation when running DAST full scans. Not supported for API scans. Default: `false` |
+| `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` <sup>1</sup> | 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://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. |
+| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. |
+| `DAST_REQUEST_HEADERS` <sup>1</sup> | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` |
+| `DAST_DEBUG` <sup>1</sup> | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
+| `DAST_TARGET_AVAILABILITY_TIMEOUT` <sup>1</sup> | number | Time limit in seconds to wait for target availability. |
+| `DAST_SPIDER_MINS` <sup>1</sup> | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
+| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
+| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
+| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. |
+| `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` <sup>1</sup> | 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. [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. |
+| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` |
+| `DAST_AUTH_EXCLUDE_URLS` | URLs | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289959)** in GitLab 14.0. Replaced by `DAST_EXCLUDE_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_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. |
+| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. |
+| `DAST_AUTH_REPORT` | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. |
+| `DAST_AUTH_VERIFICATION_URL` <sup>1</sup> | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. |
+| `DAST_AUTH_VERIFICATION_SELECTOR` | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo` |
+| `DAST_AUTH_VERIFICATION_LOGIN_FORM` | boolean | Verifies successful authentication by checking for the lack of a login form once the login form has been submitted. |
+| `DAST_ADVERTISE_SCAN` | boolean | Set to `true` to add a `Via` header to every request sent, advertising that the request was sent as part of a GitLab DAST scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/334947) in GitLab 14.1. |
+
+1. Available to an on-demand DAST scan.
#### Selectors
@@ -778,7 +838,8 @@ Chrome DevTools element selector tool is an effective way to find a selector.
![highlight](img/dast_auth_browser_scan_highlight.png)
1. Once highlighted, you can see the element's details, including attributes that would make a good candidate for a selector.
-In this example, the `id="user_login"` appears to be a good candidate. You can use this as a selector as the DAST username field by setting `DAST_USERNAME_FIELD: "css:[id=user_login]"`, or more simply, `DAST_USERNAME_FIELD: "id:user_login"`.
+In this example, the `id="user_login"` appears to be a good candidate. You can use this as a selector as the DAST username field by setting
+`DAST_USERNAME_FIELD: "id:user_login"`.
##### Choose the right selector
@@ -788,9 +849,9 @@ In order of preference, it is recommended to choose as selectors:
- `id` fields. These are generally unique on a page, and rarely change.
- `name` fields. These are generally unique on a page, and rarely change.
-- `class` values specific to the field, such as the selector `"css:.username"` for the `username` class on the username field.
+- `class` values specific to the field, such as the selector `"css:.username"` for the `username` class on the username field.
- Presence of field specific data attributes, such as the selector, `"css:[data-username]"` when the `data-username` field has any value on the username field.
-- Multiple `class` hierarchy values, such as the selector `"css:.login-form .username"` when there are multiple elements with class `username` but only one nested inside the element with the class `login-form`.
+- Multiple `class` hierarchy values, such as the selector `"css:.login-form .username"` when there are multiple elements with class `username` but only one nested inside the element with the class `login-form`.
When using selectors to locate specific fields we recommend you avoid searching on:
@@ -880,6 +941,8 @@ Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATIO
The following table outlines examples of values that can be set and the effect that they have on the output that is logged.
Multiple values can be specified, separated by semicolons.
+For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG`.
+
| Log configuration value | Effect |
|-------------------------------------------------- | ----------------------------------------------------------------- |
| `log4j.rootLogger=DEBUG` | Enable all debug logging statements. |
@@ -901,8 +964,8 @@ To use DAST in an offline environment, you need:
- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisites).
- 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).
+ [container image](https://gitlab.com/security-products/dast), found in the
+ [DAST container registry](https://gitlab.com/security-products/dast/container_registry).
Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
meaning the runner tries to pull Docker images from the GitLab container registry even if a local
@@ -915,7 +978,7 @@ enables the use of updated scanners in your CI/CD pipelines.
For DAST, import the following default DAST analyzer image from `registry.gitlab.com` to your [local Docker container registry](../../packages/container_registry/index.md):
-- `registry.gitlab.com/gitlab-org/security-products/dast:latest`
+- `registry.gitlab.com/security-products/dast:latest`
The process for importing Docker images into a local offline Docker registry depends on
**your network security policy**. Please consult your IT staff to find an accepted and approved
@@ -953,6 +1016,7 @@ Alternatively, you can use the CI/CD variable `SECURE_ANALYZERS_PREFIX` to overr
> - 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.
+> - Auditing for DAST profile management was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1.
An on-demand DAST scan runs outside the DevOps life cycle. Changes in your repository don't trigger
the scan. You must start it manually.
@@ -1276,6 +1340,13 @@ If a scanner profile is linked to a security policy, a user cannot delete the pr
page. See [Scan Policies](../policies/index.md)
for more information.
+### Auditing
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217872) in GitLab 14.1.
+
+The creation, updating, and deletion of DAST profiles, DAST scanner profiles,
+and DAST site profiles are included in the [audit log](../../../administration/audit_events.md).
+
## Reports
The DAST tool outputs a report file in JSON format by default. However, this tool can also generate reports in
diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md
index 9a6e1e73330..48a784e0d03 100644
--- a/doc/user/application_security/dast_api/index.md
+++ b/doc/user/application_security/dast_api/index.md
@@ -7,11 +7,11 @@ type: reference, howto
# DAST API **(ULTIMATE)**
-You can add dynamic application security testing of web APIs to your [GitLab CI/CD](../../../ci/README.md) pipelines.
+You can add dynamic application security testing of web APIs to your [GitLab CI/CD](../../../ci/index.md) pipelines.
This helps you discover bugs and potential security issues that other QA processes may miss.
We recommend that you use DAST API testing in addition to [GitLab Secure](../index.md)'s
-other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/README.md),
+other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md),
you can run DAST API tests as part your CI/CD workflow.
## Requirements
@@ -85,7 +85,7 @@ the body generation is limited to these body types:
Follow these steps to configure DAST API in GitLab with an OpenAPI specification:
-1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate)
+1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate)
the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml)
that's provided as part of your GitLab installation. Add the following to your
`.gitlab-ci.yml` file:
@@ -184,7 +184,7 @@ cookies. We recommend that you review the HAR file contents before adding them t
Follow these steps to configure DAST API to use a HAR file that provides information about the
target API to test:
-1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate)
+1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate)
the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml)
that's provided as part of your GitLab installation. To do so, add the following to your
`.gitlab-ci.yml` file:
@@ -284,7 +284,7 @@ them to a repository.
Follow these steps to configure DAST API to use a Postman Collection file that provides
information about the target API to test:
-1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate)
+1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate)
the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml)
that's provided as part of your GitLab installation. To do so, add the following to your
`.gitlab-ci.yml` file:
@@ -435,7 +435,7 @@ To use HTTP basic authentication, two CI/CD variables are added to your `.gitlab
- `DAST_API_HTTP_USERNAME`: The username for authentication.
- `DAST_API_HTTP_PASSWORD`: The password for authentication.
-For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/README.md#custom-cicd-variables)
+For the password, we recommended that you [create a CI/CD variable](../../../ci/variables/index.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 `DAST_API_HTTP_PASSWORD`:
@@ -473,7 +473,7 @@ outgoing HTTP requests.
Follow these steps to provide the bearer token with `DAST_API_OVERRIDES_ENV`:
-1. [Create a CI/CD variable](../../../ci/variables/README.md#custom-cicd-variables),
+1. [Create a CI/CD variable](../../../ci/variables/index.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
@@ -849,7 +849,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#add-a-cicd-variable-to-an-instance):
+[group or instance level CI/CD variable defined in the UI](../../../ci/variables/index.md#add-a-cicd-variable-to-an-instance):
```yaml
stages:
diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md
index fcefba943ad..9fc90c427c5 100644
--- a/doc/user/application_security/dependency_list/index.md
+++ b/doc/user/application_security/dependency_list/index.md
@@ -13,7 +13,7 @@ Use the dependency list to review your project's dependencies and key
details about those dependencies, including their known vulnerabilities. It is a collection of dependencies in your project, including existing and new findings. To see the dependency list, go to your project and select **Security & Compliance > Dependency List**.
This information is sometimes referred to as a Software Bill of Materials or SBoM / BOM.
-The dependency list only shows the results of the last successful pipeline to run on the default branch. This is why we recommend not changing the default behavior of allowing the secure jobs to fail.
+The dependency list only shows the results of the last successful pipeline to run on the default branch. This is why we recommend not changing the default behavior of allowing the secure jobs to fail.
## Prerequisites
diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md
index 96fc085e7c6..76a14aae715 100644
--- a/doc/user/application_security/dependency_scanning/index.md
+++ b/doc/user/application_security/dependency_scanning/index.md
@@ -16,7 +16,7 @@ vulnerable. You can then take action to protect your application.
## Overview
-If you're using [GitLab CI/CD](../../../ci/README.md), you can use dependency scanning to analyze
+If you're using [GitLab CI/CD](../../../ci/index.md), you can use dependency scanning to analyze
your dependencies for known vulnerabilities. GitLab scans all dependencies, including transitive
dependencies (also known as nested dependencies). You can take advantage of dependency scanning by
either:
@@ -55,7 +55,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae
## Supported languages and package managers
-GitLab relies on [`rules`](../../../ci/yaml/README.md#rules) to start relevant analyzers depending on the languages detected in the repository.
+GitLab relies on [`rules`](../../../ci/yaml/index.md#rules) to start relevant analyzers depending on the languages detected in the repository.
The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or `api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`.
The following languages and dependency managers are supported:
@@ -90,7 +90,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md)
## Configuration
To enable dependency scanning for GitLab 11.9 and later, you must
-[include](../../../ci/yaml/README.md#includetemplate) the
+[include](../../../ci/yaml/index.md#includetemplate) the
[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml)
that is provided as a part of your GitLab installation.
For GitLab versions earlier than 11.9, you can copy and use the job as defined
@@ -106,14 +106,39 @@ 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/yaml/README.md#artifactsreportsdependency_scanning)
+[dependency scanning report artifact](../../../ci/yaml/index.md#artifactsreportsdependency_scanning)
that you can later download and analyze. Due to implementation limitations, we
always take the latest dependency scanning artifact available.
+### Enable Dependency Scanning via an automatic merge request
+
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4908) in GitLab 14.1.
+> - [Deployed behind a feature flag](../../../user/feature_flags.md), enabled by default.
+> - Enabled on GitLab.com.
+> - Recommended for production use.
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-configure-dependency-scanning-via-a-merge-request). **(ULTIMATE SELF)**
+
+WARNING:
+This feature might not be available to you. Check the **version history** note above for details.
+
+There can be
+[risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features).
+Refer to this feature's version history for more details.
+
+To enable Dependency Scanning in a project, you can create a merge request
+from the Security Configuration page.
+
+1. In the project where you want to enable Dependency Scanning, navigate to
+ **Security & Compliance > Configuration**.
+1. In the **Dependency Scanning** row, select **Configure via Merge Request**.
+
+This automatically creates a merge request with the changes necessary to enable Dependency Scanning
+that you can review and merge to complete the configuration.
+
### Customizing the dependency scanning settings
The dependency scanning settings can be changed through [CI/CD variables](#available-cicd-variables) by using the
-[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
+[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`.
For example:
```yaml
@@ -124,14 +149,14 @@ variables:
SECURE_LOG_LEVEL: error
```
-Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline
+Because template is [evaluated before](../../../ci/yaml/index.md#include) the pipeline
configuration, the last mention of the variable takes precedence.
### Overriding dependency scanning jobs
WARNING:
-Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except)
-is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead.
+Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except)
+is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead.
To override a job definition (for example, to change properties like `variables` or `dependencies`),
declare a new job with the same name as the one to override. Place this new job after the template
@@ -189,12 +214,12 @@ The following variables are used for configuring specific analyzers (used for a
| `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`, `15`, `16`. Maven and Gradle use the Java version specified by this value (Dependency Scanning for Gradle does not currently support Java `16`). |
+| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`, `16`. |
| `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`. |
| `PIP_INDEX_URL` | `gemnasium-python` | `https://pypi.org/simple` | Base URL of Python Package Index. |
-| `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. |
+| `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. **Warning:** Please read [the following security consideration](#python-projects) when using this environment variable. |
| `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. |
| `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) |
| `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) |
@@ -217,7 +242,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#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.
+The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.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
@@ -552,6 +577,18 @@ gemnasium-dependency_scanning:
- tar -xzf gemnasium_db.tar.gz -C $GEMNASIUM_DB_LOCAL_PATH
```
+## Warnings
+
+### Python projects
+
+Extra care needs to be taken when using the [`PIP_EXTRA_INDEX_URL`](https://pipenv.pypa.io/en/latest/cli/#envvar-PIP_EXTRA_INDEX_URL)
+environment variable due to a possible exploit documented by [CVE-2018-20225](https://nvd.nist.gov/vuln/detail/CVE-2018-20225):
+
+> An issue was discovered in pip (all versions) because it installs the version with the highest version number, even if the user had
+intended to obtain a private package from a private index. This only affects use of the `PIP_EXTRA_INDEX_URL` option, and exploitation
+requires that the package does not already exist in the public index (and thus the attacker can put the package there with an arbitrary
+version number).
+
## Limitations
### Referencing local dependencies using a path in JavaScript projects
@@ -584,7 +621,7 @@ Generally, the approach is the following:
1. Define a dedicated converter job in your `.gitlab-ci.yml` file.
Use a suitable Docker image, script, or both to facilitate the conversion.
1. Let that job upload the converted, supported file as an artifact.
-1. Add [`dependencies: [<your-converter-job>]`](../../../ci/yaml/README.md#dependencies)
+1. Add [`dependencies: [<your-converter-job>]`](../../../ci/yaml/index.md#dependencies)
to your `dependency_scanning` job to make use of the converted definitions files.
For example, the currently unsupported `poetry.lock` file can be
@@ -631,7 +668,7 @@ For information on this, see the [general Application Security troubleshooting s
### Limitation when using rules:exists
The [dependency scanning CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml)
-uses the [`rules:exists`](../../../ci/yaml/README.md#rulesexists)
+uses the [`rules:exists`](../../../ci/yaml/index.md#rulesexists)
syntax. This directive is limited to 10000 checks and always returns `true` after reaching this
number. Because of this, and depending on the number of files in your repository, a dependency
scanning job might be triggered even if the scanner doesn't support your project.
@@ -644,3 +681,22 @@ with a dependency on this version of Python should use `retire.js` version 2.10.
### Error: `dependency_scanning is used for configuration only, and its script should not be executed`
For information on this, see the [GitLab Secure troubleshooting section](../index.md#error-job-is-used-for-configuration-only-and-its-script-should-not-be-executed).
+
+### Enable or disable Configure Dependency Scanning via a Merge Request
+
+Configure Dependency Scanning via a Merge Request 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 disable it:
+
+```ruby
+Feature.disable(:sec_dependency_scanning_ui_enable)
+```
+
+To enable it:
+
+```ruby
+Feature.enable(:sec_dependency_scanning_ui_enable)
+```
diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md
index bf812b25b5f..616d2f8c790 100644
--- a/doc/user/application_security/index.md
+++ b/doc/user/application_security/index.md
@@ -33,16 +33,17 @@ GitLab uses the following tools to scan and report known vulnerabilities found i
| Secure scanning tool | Description |
|:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------|
-| [Container Scanning](container_scanning/index.md) **(ULTIMATE)** | Scan Docker containers for known vulnerabilities. |
-| [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. |
-| [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. |
-| [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. |
-| [DAST API](dast_api/index.md) **(ULTIMATE)** | Analyze running web APIs for known vulnerabilities. |
-| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. |
-| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. |
-| [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. |
-| [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. |
-| [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. |
+| [Container Scanning](container_scanning/index.md) **(ULTIMATE)** | Scan Docker containers for known vulnerabilities. |
+| [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. |
+| [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. |
+| [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. |
+| [DAST API](dast_api/index.md) **(ULTIMATE)** | Analyze running web APIs for known vulnerabilities. |
+| [API fuzzing](api_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities in web APIs with fuzzing. |
+| [Secret Detection](secret_detection/index.md) | Analyze Git history for leaked secrets. |
+| [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. |
+| [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. |
+| [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. |
+| [Cluster Image Scanning](cluster_image_scanning/index.md) **(ULTIMATE)** | Scan Kubernetes clusters for known vulnerabilities. |
## Security scanning with Auto DevOps
@@ -99,7 +100,7 @@ the container-scanning analyzer which uses
### Use security scanning tools with Pipelines for Merge Requests
By default, the application security jobs are configured to run for branch pipelines only.
-To use them with [pipelines for merge requests](../../ci/merge_request_pipelines/index.md),
+To use them with [pipelines for merge requests](../../ci/pipelines/merge_request_pipelines.md),
you may need to override the default `rules:` configuration to add:
```yaml
@@ -129,7 +130,7 @@ All jobs are permitted to fail by default. This means that if they fail it do no
If you want to prevent vulnerabilities from being merged, you should do this by adding [Security Approvals in Merge Requests](#security-approvals-in-merge-requests) which prevents unknown, high or critical findings from being merged without an approval from a specific group of people that you choose.
-We do not recommend changing the job [`allow_failure` setting](../../ci/yaml/README.md#allow_failure) as that fails the entire pipeline.
+We do not recommend changing the job [`allow_failure` setting](../../ci/yaml/index.md#allow_failure) as that fails the entire pipeline.
### JSON Artifact
@@ -209,7 +210,6 @@ request contains a denied license. For more details, see [Enabling license appro
Prerequisites:
-- At least one [security scanner job](#security-scanning-tools) must be enabled.
- Maintainer or Owner [role](../permissions.md#project-members-permissions).
For this approval group, you must set the number of approvals required to greater than zero.
@@ -238,7 +238,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#custom-cicd-variables)
+[set the following variable](../../ci/variables/index.md#custom-cicd-variables)
under your project's settings:
| Type | Key | Value |
@@ -358,7 +358,7 @@ You can do it quickly by following the hyperlink given to run a new pipeline.
### Getting error message `sast job: stage parameter should be [some stage name here]`
-When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template
+When [including](../../ci/yaml/index.md#includetemplate) a `.gitlab-ci.yml` template
like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml),
the following error may occur, depending on your GitLab CI/CD configuration:
@@ -406,12 +406,12 @@ This is often followed by the [error `No files to upload`](../../ci/pipelines/jo
and preceded by other errors or warnings that indicate why the JSON report wasn't generated. Please
check the entire job log for such messages. If you don't find these messages, retry the failed job
after setting `SECURE_LOG_LEVEL: "debug"` as a
-[custom CI/CD variable](../../ci/variables/README.md#custom-cicd-variables).
+[custom CI/CD variable](../../ci/variables/index.md#custom-cicd-variables).
This provides useful information to investigate further.
### Getting error message `sast job: config key may not be used with 'rules': only/except`
-When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template
+When [including](../../ci/yaml/index.md#includetemplate) a `.gitlab-ci.yml` template
like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml),
the following error may occur, depending on your GitLab CI/CD configuration:
@@ -422,7 +422,7 @@ Found errors in your .gitlab-ci.yml:
```
This error appears when the included job's `rules` configuration has been [overridden](sast/index.md#overriding-sast-jobs)
-with [the deprecated `only` or `except` syntax.](../../ci/yaml/README.md#only--except)
+with [the deprecated `only` or `except` syntax.](../../ci/yaml/index.md#only--except)
To fix this issue, you must either:
- [Transition your `only/except` syntax to `rules`](#transitioning-your-onlyexcept-syntax-to-rules).
@@ -433,8 +433,8 @@ To fix this issue, you must either:
#### Transitioning your `only/except` syntax to `rules`
When overriding the template to control job execution, previous instances of
-[`only` or `except`](../../ci/yaml/README.md#only--except) are no longer compatible
-and must be transitioned to [the `rules` syntax](../../ci/yaml/README.md#rules).
+[`only` or `except`](../../ci/yaml/index.md#only--except) are no longer compatible
+and must be transitioned to [the `rules` syntax](../../ci/yaml/index.md#rules).
If your override is aimed at limiting jobs to only run on `master`, the previous syntax
would look similar to:
@@ -490,11 +490,11 @@ spotbugs-sast:
- if: $CI_COMMIT_TAG == null
```
-[Learn more on the usage of `rules`](../../ci/yaml/README.md#rules).
+[Learn more on the usage of `rules`](../../ci/yaml/index.md#rules).
#### Pin your templates to the deprecated versions
-To ensure the latest support, we **strongly** recommend that you migrate to [`rules`](../../ci/yaml/README.md#rules).
+To ensure the latest support, we **strongly** recommend that you migrate to [`rules`](../../ci/yaml/index.md#rules).
If you're unable to immediately update your CI configuration, there are several workarounds that
involve pinning to the previous template versions, for example:
diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md
index 77a15a37c55..d87da15b4b0 100644
--- a/doc/user/application_security/offline_deployments/index.md
+++ b/doc/user/application_security/offline_deployments/index.md
@@ -108,7 +108,7 @@ example of such a transfer:
### Using the official GitLab template
-GitLab provides a [vendored template](../../../ci/yaml/README.md#includetemplate)
+GitLab provides a [vendored template](../../../ci/yaml/index.md#includetemplate)
to ease this process.
This template should be used in a new, empty project, with a `gitlab-ci.yml` file containing:
@@ -149,7 +149,7 @@ GitLab.com. To do so, set the CI/CD variable `SECURE_ANALYZERS_PREFIX` with the
project [container registry](../../packages/container_registry/index.md).
You can set this variable in the projects' `.gitlab-ci.yml`, or
-in the GitLab UI at the project or group level. See the [GitLab CI/CD variables page](../../../ci/variables/README.md#custom-cicd-variables)
+in the GitLab UI at the project or group level. See the [GitLab CI/CD variables page](../../../ci/variables/index.md#custom-cicd-variables)
for more information.
#### Variables
diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md
index 92f0d6924b3..076872c9864 100644
--- a/doc/user/application_security/policies/index.md
+++ b/doc/user/application_security/policies/index.md
@@ -191,6 +191,10 @@ changes.
You can always change the **Security policy project** by navigating to your project's
**Security & Compliance > Policies** and modifying the selected project.
+NOTE:
+Only project Owners have the [permissions](../../permissions.md#project-members-permissions)
+to select Security Policy Project.
+
## Roadmap
See the [Category Direction page](https://about.gitlab.com/direction/protect/container_network_security/)
diff --git a/doc/user/application_security/sast/img/sast_results_in_mr_v14_0.png b/doc/user/application_security/sast/img/sast_results_in_mr_v14_0.png
new file mode 100644
index 00000000000..17edc30fa0f
--- /dev/null
+++ b/doc/user/application_security/sast/img/sast_results_in_mr_v14_0.png
Binary files differ
diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md
index e80807b31bf..c64df616925 100644
--- a/doc/user/application_security/sast/index.md
+++ b/doc/user/application_security/sast/index.md
@@ -15,13 +15,15 @@ The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.
explains how 4 of the top 6 attacks were application based. Download it to learn how to protect your
organization.
-If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known
-vulnerabilities using Static Application Security Testing (SAST). GitLab checks the SAST report and
-compares the found vulnerabilities between the source and target branches.
+If you're using [GitLab CI/CD](../../../ci/index.md), you can use Static Application Security
+Testing (SAST) to check your source code for known vulnerabilities. When a pipeline completes,
+the results of the SAST analysis are processed and shown in the pipeline's Security tab. If the
+pipeline is associated with a merge request, the SAST analysis is compared with the results of
+the target branch's analysis (if available). The results of that comparison are shown in the merge
+request. **(ULTIMATE)** If the pipeline is running from the default branch, the results of the SAST
+analysis are available in the [security dashboards](../security_dashboard/index.md).
-Details of the vulnerabilities found are included in the merge request. **(ULTIMATE)**
-
-![SAST Widget](img/sast_v13_2.png)
+![SAST results shown in the MR widget](img/sast_results_in_mr_v14_0.png)
The results are sorted by the priority of the vulnerability:
@@ -160,7 +162,7 @@ To configure SAST for a project you can:
### Configure SAST manually
-For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/README.md#includetemplate)
+For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/index.md#includetemplate)
the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml)
provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you
can copy and use the job as defined that template.
@@ -176,7 +178,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/yaml/README.md#artifactsreportssast)
+[SAST report artifact](../../../ci/yaml/index.md#artifactsreportssast)
that you can later download and analyze. Due to implementation limitations, we
always take the latest SAST artifact available.
@@ -204,7 +206,7 @@ page:
The SAST settings can be changed through [CI/CD variables](#available-cicd-variables)
by using the
-[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
+[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`.
In the following example, we include the SAST template and at the same time we
set the `SAST_GOSEC_LEVEL` variable to `2`:
@@ -216,14 +218,14 @@ variables:
SAST_GOSEC_LEVEL: 2
```
-Because the template is [evaluated before](../../../ci/yaml/README.md#include)
+Because the template is [evaluated before](../../../ci/yaml/index.md#include)
the pipeline configuration, the last mention of the variable takes precedence.
### Overriding SAST jobs
WARNING:
-Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except)
-is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead.
+Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except)
+is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead.
To override a job definition, (for example, change properties like `variables` or `dependencies`),
declare a job with the same name as the SAST job to override. Place this new job after the template
@@ -463,7 +465,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#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.
+The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.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
@@ -497,7 +499,7 @@ Some analyzers can be customized with CI/CD variables.
| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. |
| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` uses to generate a Kubernetes manifest that `kubesec` scans. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. |
| `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. |
-| `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. |
+| `COMPILE` | Gosec, SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced for `SpotBugs`](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) analyzer in GitLab 13.1 and [`Gosec`](https://gitlab.com/gitlab-org/gitlab/-/issues/330678) analyzer in GitLab 14.0. |
| `ANT_HOME` | SpotBugs | The `ANT_HOME` variable. |
| `ANT_PATH` | SpotBugs | Path to the `ant` executable. |
| `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. |
@@ -510,8 +512,8 @@ Some analyzers can be customized with CI/CD variables.
| `SBT_PATH` | SpotBugs | Path to the `sbt` executable. |
| `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. |
| `SAST_GOSEC_CONFIG` | Gosec | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328301)** in GitLab 14.0 - use custom rulesets instead. Path to configuration for Gosec (optional). |
-| `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. |
-| `SAST_DISABLE_BABEL` | NodeJsScan | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64025)** in GitLab 13.5 |
+| `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. |
+| `SAST_DISABLE_BABEL` | NodeJsScan | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64025)** in GitLab 13.5 |
| `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://r2c.dev/). Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330565) in GitLab 14.0. |
#### Custom CI/CD variables
@@ -519,7 +521,7 @@ Some analyzers can be customized with CI/CD variables.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18193) in GitLab Ultimate 12.5.
In addition to the aforementioned SAST configuration CI/CD variables,
-all [custom variables](../../../ci/variables/README.md#custom-cicd-variables) are propagated
+all [custom variables](../../../ci/variables/index.md#custom-cicd-variables) are propagated
to the underlying SAST analyzer images if
[the SAST vendored template](#configuration) is used.
@@ -554,7 +556,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/yaml/README.md#artifactspaths) 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/index.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md).
Here's an example SAST report:
@@ -763,7 +765,7 @@ uses the `rules:exists` parameter. For performance reasons, a maximum number of
against the given glob pattern. If the number of matches exceeds the maximum, the `rules:exists`
parameter returns `true`. Depending on the number of files in your repository, a SAST job might be
triggered even if the scanner doesn't support your project. For more details about this issue, see
-the [`rules:exists` documentation](../../../ci/yaml/README.md#rulesexists).
+the [`rules:exists` documentation](../../../ci/yaml/index.md#rulesexists).
### SpotBugs UTF-8 unmappable character errors
@@ -789,7 +791,7 @@ For Maven builds, add the following to your `pom.xml` file:
### Flawfinder encoding error
-This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/README.md#before_script) feature.
+This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/index.md#before_script) feature.
### Semgrep slowness, unexpected results, or other errors
diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md
index f4aa9dc2787..938bd3b41d5 100644
--- a/doc/user/application_security/secret_detection/index.md
+++ b/doc/user/application_security/secret_detection/index.md
@@ -133,24 +133,14 @@ 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/yaml/README.md#artifactsreportssecret_detection)
+[Secret Detection report artifact](../../../ci/yaml/index.md#artifactsreportssecret_detection)
that you can later download and analyze. Due to implementation limitations, we
always take the latest Secret Detection artifact available.
### Enable Secret Detection via an automatic merge request **(ULTIMATE SELF)**
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11.
-> - [Deployed behind a feature flag](../../../user/feature_flags.md), enabled by default.
-> - Enabled on GitLab.com.
-> - Recommended for production use.
-> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-configure-secret-detection-via-a-merge-request). **(ULTIMATE SELF)**
-
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
-
-There can be
-[risks when disabling released features](../../../user/feature_flags.md#risks-when-disabling-released-features).
-Refer to this feature's version history for more details.
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4496) in GitLab 13.11, behind a feature flag, enabled by default.
+> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/329886) in GitLab 14.1.
To enable Secret Detection in a project, you can create a merge request
from the Security Configuration page.
@@ -166,15 +156,15 @@ that you can review and merge to complete the configuration.
The Secret Detection scan settings can be changed through [CI/CD variables](#available-cicd-variables)
by using the
-[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
+[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`.
To override a job definition, (for example, change properties like `variables` or `dependencies`),
declare a job with the same name as the SAST job to override. Place this new job after the template
inclusion and specify any additional keys under it.
WARNING:
-Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except)
-is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead.
+Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except)
+is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead.
#### GIT_DEPTH
@@ -197,7 +187,7 @@ secret_detection:
SECRET_DETECTION_HISTORIC_SCAN: "true"
```
-Because the template is [evaluated before](../../../ci/yaml/README.md#include)
+Because the template is [evaluated before](../../../ci/yaml/index.md#include)
the pipeline configuration, the last mention of the variable takes precedence.
#### Available CI/CD variables
@@ -285,7 +275,7 @@ Post-processing is currently limited to a project's default branch, see the abov
sequenceDiagram
autonumber
Rails->>+Sidekiq: gl-secret-detection-report.json
- Sidekiq-->+Sidekiq: BuildFinishedWorker
+ Sidekiq-->+Sidekiq: Ci::BuildFinishedWorker
Sidekiq-->+RevocationAPI: GET revocable keys types
RevocationAPI-->>-Sidekiq: OK
Sidekiq->>+RevocationAPI: POST revoke revocable keys
@@ -360,6 +350,21 @@ Support for custom certificate authorities was introduced in the following versi
| -------- | ------- |
| secrets | [v3.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/releases/v3.0.0) |
+To trust a custom Certificate Authority, set the `ADDITIONAL_CA_CERT_BUNDLE` variable to the bundle
+of CA certs that you want to trust in the SAST environment. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following:
+
+```yaml
+variables:
+ ADDITIONAL_CA_CERT_BUNDLE: |
+ -----BEGIN CERTIFICATE-----
+ MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
+ ...
+ jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
+ -----END CERTIFICATE-----
+```
+
+The `ADDITIONAL_CA_CERT_BUNDLE` value can also be configured as a [custom variable in the UI](../../../ci/variables/index.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.
+
### Set Secret Detection CI/CD variables to use local Secret Detection analyzer
Add the following configuration to your `.gitlab-ci.yml` file. You must replace
@@ -385,7 +390,7 @@ For information on this, see the [general Application Security troubleshooting s
### Error: `Couldn't run the gitleaks command: exit status 2`
If a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` variable
-is set to 50 (a [project default](../../../ci/pipelines/settings.md#git-shallow-clone)),
+is set to 50 (a [project default](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone)),
the Secret Detection job fails as the clone is not deep enough to contain all of the
relevant commits.
@@ -409,22 +414,3 @@ secret_detection:
variables:
GIT_DEPTH: 100
```
-
-### Enable or disable Configure Secret Detection via a Merge Request
-
-Configure Secret Detection via a Merge Request 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(:sec_secret_detection_ui_enable)
-```
-
-To disable it:
-
-```ruby
-Feature.disable(:sec_secret_detection_ui_enable)
-```
diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md
index 01de066367c..806bc03e30e 100644
--- a/doc/user/application_security/security_dashboard/index.md
+++ b/doc/user/application_security/security_dashboard/index.md
@@ -33,13 +33,14 @@ The security dashboard and vulnerability report displays information about vulne
- [Dynamic Application Security Testing](../dast/index.md)
- [Dependency Scanning](../dependency_scanning/index.md)
- [Static Application Security Testing](../sast/index.md)
+- [Cluster Image Scanning](../cluster_image_scanning/index.md)
- And [others](../index.md#security-scanning-tools)!
## Prerequisites
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/yaml/README.md#artifactsreports).
+1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/index.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.
@@ -76,7 +77,7 @@ CSV file containing details of the resources scanned.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285477) in GitLab 13.11, date range slider to visualize data between given dates.
A project's Security Dashboard displays a chart with the total number of vulnerabilities
-over time. It updates daily with up to 365 days of historical data. By default,
+over time with up to 365 days of historical data. Data is refreshed daily at 1:15am UTC. By default,
it shows statistics for all vulnerability severities.
To access the dashboard, from your project's home page go to **Security & Compliance > Security Dashboard**.
diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md
index ce30accfb4d..c96497e9233 100644
--- a/doc/user/application_security/terminology/index.md
+++ b/doc/user/application_security/terminology/index.md
@@ -118,6 +118,7 @@ The type of scan. This must be one of the following:
- `dependency_scanning`
- `dast`
- `sast`
+- `cluster_image_scanning`
### Scanner
diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md
index e1200c60419..8cecb9c5929 100644
--- a/doc/user/application_security/threat_monitoring/index.md
+++ b/doc/user/application_security/threat_monitoring/index.md
@@ -27,20 +27,19 @@ your application's Kubernetes namespace. This section has the following
prerequisites:
- Your project contains at least one [environment](../../../ci/environments/index.md)
-- You've [installed Cilium](../../clusters/applications.md#install-cilium-using-gitlab-cicd)
+- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium)
- You've configured the [Prometheus service](../../project/integrations/prometheus.md#enabling-prometheus-integration)
If you're using custom Helm values for Cilium, you must enable Hubble
with flow metrics for each namespace by adding the following lines to
-your [Cilium values](../../clusters/applications.md#install-cilium-using-gitlab-cicd):
+your [Cilium values](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium):
```yaml
-global:
- hubble:
- enabled: true
- metrics:
- enabled:
- - 'flow:sourceContext=namespace;destinationContext=namespace'
+hubble:
+ enabled: true
+ metrics:
+ enabled:
+ - 'flow:sourceContext=namespace;destinationContext=namespace'
```
The **Container Network Policy** section displays the following information
@@ -54,7 +53,11 @@ about your packet flow:
If a significant percentage of packets is dropped, you should
investigate it for potential threats by
-[examining the Cilium logs](../../clusters/applications.md#install-cilium-using-gitlab-cicd).
+examining the Cilium logs:
+
+```shell
+kubectl -n gitlab-managed-apps logs -l k8s-app=cilium -c cilium-monitor
+```
## Container Network Policy management
@@ -67,7 +70,7 @@ status, and create and edit deployed policies. This section has the
following prerequisites:
- Your project contains at least one [environment](../../../ci/environments/index.md)
-- You've [installed Cilium](../../clusters/applications.md#install-cilium-using-gitlab-cicd)
+- You've [installed Cilium](../../project/clusters/protect/container_network_security/quick_start_guide.md#use-the-cluster-management-template-to-install-cilium)
Network policies are fetched directly from the selected environment's
deployment platform. Changes performed outside of this tab are
diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md
index 9866709bacc..6437f2325e8 100644
--- a/doc/user/application_security/vulnerabilities/index.md
+++ b/doc/user/application_security/vulnerabilities/index.md
@@ -164,7 +164,7 @@ The following vulnerability scanners and their databases are regularly updated:
|:----------------------------------------------------------------|----------------------------------|
| [Container Scanning](../container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. |
| [Dependency Scanning](../dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). |
-| [Dynamic Application Security Testing (DAST)](../dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/master/Dockerfile#L1). The scanning rules are downloaded at scan runtime. |
+| [Dynamic Application Security Testing (DAST)](../dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L1). The scanning rules are downloaded at scan runtime. |
| [Static Application Security Testing (SAST)](../sast/index.md) | Relies exclusively on [the tools GitLab wraps](../sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. |
You do not have to update GitLab to benefit from the latest vulnerabilities definitions.
diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md
index 07025d193af..da59c0fbe79 100644
--- a/doc/user/application_security/vulnerability_report/index.md
+++ b/doc/user/application_security/vulnerability_report/index.md
@@ -128,11 +128,11 @@ 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.
-Hover over an **Activity** entry and select a link go to that issue. The status of whether the issue is open or closed also displays in the hover menu.
+Hover over an **Activity** entry and select a link go to that issue. The status of whether the issue is open or closed also displays in the hover menu.
![Display attached issues](img/vulnerability_list_table_v13_9.png)
-If Jira issue support is enabled, the issue link found in the Activity entry links out to the issue in Jira. Unlike GitLab issues, the status of whether a Jira issue is Open or Closed does not display in the GitLab UI.
+If Jira issue support is enabled, the issue link found in the Activity entry links out to the issue in Jira. Unlike GitLab issues, the status of whether a Jira issue is Open or Closed does not display in the GitLab UI.
## Change status of vulnerabilities