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
path: root/doc
diff options
context:
space:
mode:
authorGitLab Bot <gitlab-bot@gitlab.com>2020-05-06 06:09:33 +0300
committerGitLab Bot <gitlab-bot@gitlab.com>2020-05-06 06:09:33 +0300
commit6c005ae9783ad6752e3082d05e1053d20d8da92a (patch)
treed99b44427d04388442363deca27c7f6b4fd0af77 /doc
parentde088a681f5db1fd2f4be56bf59925312705bb72 (diff)
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r--doc/.vale/gitlab/spelling-exceptions.txt6
-rw-r--r--doc/administration/gitaly/praefect.md72
-rw-r--r--doc/api/graphql/reference/gitlab_schema.graphql28
-rw-r--r--doc/api/graphql/reference/gitlab_schema.json94
-rw-r--r--doc/api/graphql/reference/index.md8
-rw-r--r--doc/user/application_security/dast/index.md188
-rw-r--r--doc/user/application_security/dependency_scanning/index.md115
7 files changed, 253 insertions, 258 deletions
diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt
index bbbb0ae0dad..bf78eaaee8c 100644
--- a/doc/.vale/gitlab/spelling-exceptions.txt
+++ b/doc/.vale/gitlab/spelling-exceptions.txt
@@ -201,6 +201,7 @@ namespaced
namespaces
Nanoc
NGINX
+npm
Nurtch
OAuth
Okta
@@ -214,6 +215,8 @@ Packagist
parallelization
parallelizations
performant
+Pipfile
+Pipfiles
Piwik
PgBouncer
plaintext
@@ -259,6 +262,7 @@ reindexed
reindexes
reindexing
relicensing
+remediations
Repmgr
Repmgrd
requeue
@@ -286,6 +290,7 @@ runtime
runtimes
Salesforce
SAML
+sbt
Sendmail
Sentry
serverless
@@ -301,6 +306,7 @@ Slack
Slony
SMTP
Sourcegraph
+spidering
Splunk
SSH
storable
diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md
index 50a8255a792..3d09291d9b5 100644
--- a/doc/administration/gitaly/praefect.md
+++ b/doc/administration/gitaly/praefect.md
@@ -46,7 +46,7 @@ A minimum highly available configuration requires:
- 1 highly available load balancer
- 1 highly available PostgreSQL server (PostgreSQL 9.6 or newer)
-- 2 Praefect nodes
+- 3 Praefect nodes
- 3 Gitaly nodes (1 primary, 2 secondary)
![Architecture diagram](img/praefect_architecture_v12_10.png)
@@ -214,16 +214,12 @@ application server, or a Gitaly node.
1. Configure **Praefect** to listen on network interfaces by editing
`/etc/gitlab/gitlab.rb`:
- You will need to replace:
-
- - `PRAEFECT_HOST` with the IP address or hostname of the Praefect node
-
```ruby
- praefect['listen_addr'] = 'PRAEFECT_HOST:2305'
+ praefect['listen_addr'] = '0.0.0.0:2305'
# Enable Prometheus metrics access to Praefect. You must use firewalls
# to restrict access to this address/port.
- praefect['prometheus_listen_addr'] = 'PRAEFECT_HOST:9652'
+ praefect['prometheus_listen_addr'] = '0.0.0.0:9652'
```
1. Configure a strong `auth_token` for **Praefect** by editing
@@ -340,12 +336,21 @@ application server, or a Gitaly node.
will be an option to favor consistency by marking [out-of-date repositories
read-only](https://gitlab.com/gitlab-org/gitaly/-/issues/2630).
-1. Save the changes to `/etc/gitlab/gitlab.rb` and [reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure):
+1. Save the changes to `/etc/gitlab/gitlab.rb` and [reconfigure
+ Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure):
```shell
gitlab-ctl reconfigure
```
+1. To ensure that Praefect [has updated its Prometheus listen
+ address](https://gitlab.com/gitlab-org/gitaly/-/issues/2734), [restart
+ Gitaly](../restart_gitlab.md#omnibus-gitlab-restart):
+
+ ```shell
+ gitlab-ctl restart praefect
+ ```
+
1. Verify that Praefect can reach PostgreSQL:
```shell
@@ -356,6 +361,8 @@ application server, or a Gitaly node.
edit `/etc/gitlab/gitlab.rb`, remember to run `sudo gitlab-ctl reconfigure`
again before trying the `sql-ping` command.
+**The steps above must be completed for each Praefect node!**
+
### Gitaly
NOTE: **Note:** Complete these steps for **each** Gitaly node.
@@ -421,18 +428,14 @@ documentation](index.md#3-gitaly-server-configuration).
1. Configure **Gitaly** to listen on network interfaces by editing
`/etc/gitlab/gitlab.rb`:
- You will need to replace:
-
- - `GITALY_HOST` with the IP address or hostname of the Gitaly node
-
```ruby
# Make Gitaly accept connections on all network interfaces.
# Use firewalls to restrict access to this address/port.
- gitaly['listen_addr'] = 'GITALY_HOST:8075'
+ gitaly['listen_addr'] = '0.0.0.0:8075'
# Enable Prometheus metrics access to Gitaly. You must use firewalls
# to restrict access to this address/port.
- gitaly['prometheus_listen_addr'] = 'GITALY_HOST:9236'
+ gitaly['prometheus_listen_addr'] = '0.0.0.0:9236'
```
1. Configure a strong `auth_token` for **Gitaly** by editing
@@ -486,13 +489,16 @@ documentation](index.md#3-gitaly-server-configuration).
})
```
-1. Save the changes to `/etc/gitlab/gitlab.rb` and [reconfigure Gitaly](../restart_gitlab.md#omnibus-gitlab-reconfigure):
+1. Save the changes to `/etc/gitlab/gitlab.rb` and [reconfigure
+ Gitaly](../restart_gitlab.md#omnibus-gitlab-reconfigure):
```shell
gitlab-ctl reconfigure
```
-1. To ensure that Gitaly [has updated its Prometheus listen address](https://gitlab.com/gitlab-org/gitaly/-/issues/2521), [restart Gitaly](../restart_gitlab.md#omnibus-gitlab-restart):
+1. To ensure that Gitaly [has updated its Prometheus listen
+ address](https://gitlab.com/gitlab-org/gitaly/-/issues/2734), [restart
+ Gitaly](../restart_gitlab.md#omnibus-gitlab-restart):
```shell
gitlab-ctl restart gitaly
@@ -551,6 +557,16 @@ Particular attention should be shown to:
sudo -i
```
+1. Configure the `external_url` so that files could be served by GitLab
+ by proper endpoint access by editing `/etc/gitlab/gitlab.rb`:
+
+ You will need to replace `GITLAB_SERVER_URL` with the real external facing
+ URL on which current GitLab instance is serving:
+
+ ```ruby
+ external_url 'GITLAB_SERVER_URL'
+ ```
+
1. Add the Praefect cluster as a storage location by editing
`/etc/gitlab/gitlab.rb`.
@@ -577,7 +593,7 @@ Particular attention should be shown to:
`/etc/gitlab/gitlab.rb`
```ruby
- gitaly['listen_addr'] = 'GITLAB_HOST:8075'
+ gitaly['listen_addr'] = '0.0.0.0:8075'
```
1. Configure the `gitlab_shell['secret_token']` so that callbacks from Gitaly
@@ -590,16 +606,6 @@ Particular attention should be shown to:
gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN'
```
-1. Configure the `external_url` so that files could be served by GitLab
- by proper endpoint access by editing `/etc/gitlab/gitlab.rb`:
-
- You will need to replace `GITLAB_SERVER_URL` with the real external facing URL on which
- current GitLab instance is serving:
-
- ```ruby
- external_url 'GITLAB_SERVER_URL'
- ```
-
1. Add Prometheus monitoring settings by editing `/etc/gitlab/gitlab.rb`.
You will need to replace:
@@ -613,7 +619,9 @@ Particular attention should be shown to:
'job_name' => 'praefect',
'static_configs' => [
'targets' => [
- 'PRAEFECT_HOST:9652' # praefect
+ 'PRAEFECT_HOST:9652', # praefect-1
+ 'PRAEFECT_HOST:9652', # praefect-2
+ 'PRAEFECT_HOST:9652', # praefect-3
]
]
},
@@ -636,6 +644,14 @@ Particular attention should be shown to:
gitlab-ctl reconfigure
```
+1. To ensure that Gitaly [has updated its Prometheus listen
+ address](https://gitlab.com/gitlab-org/gitaly/-/issues/2734), [restart
+ Gitaly](../restart_gitlab.md#omnibus-gitlab-restart):
+
+ ```shell
+ gitlab-ctl restart gitaly
+ ```
+
1. Verify each `gitlab-shell` on each Gitaly instance can reach GitLab. On each Gitaly instance run:
```shell
diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql
index f9868ccb5b2..b4cfd50422a 100644
--- a/doc/api/graphql/reference/gitlab_schema.graphql
+++ b/doc/api/graphql/reference/gitlab_schema.graphql
@@ -39,48 +39,38 @@ type AddAwardEmojiPayload {
}
"""
-Autogenerated input type of AddProjectsToSecurityDashboard
+Autogenerated input type of AddProjectToSecurityDashboard
"""
-input AddProjectsToSecurityDashboardInput {
+input AddProjectToSecurityDashboardInput {
"""
A unique identifier for the client performing the mutation.
"""
clientMutationId: String
"""
- IDs of projects to be added to Instance Security Dashboard
+ ID of the project to be added to Instance Security Dashboard
"""
- projectIds: [ID!]!
+ id: ID!
}
"""
-Autogenerated return type of AddProjectsToSecurityDashboard
+Autogenerated return type of AddProjectToSecurityDashboard
"""
-type AddProjectsToSecurityDashboardPayload {
- """
- IDs of projects that were added to the Instance Security Dashboard
- """
- addedProjectIds: [ID!]
-
+type AddProjectToSecurityDashboardPayload {
"""
A unique identifier for the client performing the mutation.
"""
clientMutationId: String
"""
- IDs of projects that are already added to the Instance Security Dashboard
- """
- duplicatedProjectIds: [ID!]
-
- """
Reasons why the mutation failed.
"""
errors: [String!]!
"""
- IDs of projects that were not added to the Instance Security Dashboard
+ Project that was added to the Instance Security Dashboard
"""
- invalidProjectIds: [ID!]
+ project: Project
}
"""
@@ -6049,7 +6039,7 @@ enum MoveType {
type Mutation {
addAwardEmoji(input: AddAwardEmojiInput!): AddAwardEmojiPayload
- addProjectsToSecurityDashboard(input: AddProjectsToSecurityDashboardInput!): AddProjectsToSecurityDashboardPayload
+ addProjectToSecurityDashboard(input: AddProjectToSecurityDashboardInput!): AddProjectToSecurityDashboardPayload
adminSidekiqQueuesDeleteJobs(input: AdminSidekiqQueuesDeleteJobsInput!): AdminSidekiqQueuesDeleteJobsPayload
boardListUpdateLimitMetrics(input: BoardListUpdateLimitMetricsInput!): BoardListUpdateLimitMetricsPayload
createBranch(input: CreateBranchInput!): CreateBranchPayload
diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json
index e5bb8d94eeb..7a4bc3f6360 100644
--- a/doc/api/graphql/reference/gitlab_schema.json
+++ b/doc/api/graphql/reference/gitlab_schema.json
@@ -127,28 +127,20 @@
},
{
"kind": "INPUT_OBJECT",
- "name": "AddProjectsToSecurityDashboardInput",
- "description": "Autogenerated input type of AddProjectsToSecurityDashboard",
+ "name": "AddProjectToSecurityDashboardInput",
+ "description": "Autogenerated input type of AddProjectToSecurityDashboard",
"fields": null,
"inputFields": [
{
- "name": "projectIds",
- "description": "IDs of projects to be added to Instance Security Dashboard",
+ "name": "id",
+ "description": "ID of the project to be added to Instance Security Dashboard",
"type": {
"kind": "NON_NULL",
"name": null,
"ofType": {
- "kind": "LIST",
- "name": null,
- "ofType": {
- "kind": "NON_NULL",
- "name": null,
- "ofType": {
- "kind": "SCALAR",
- "name": "ID",
- "ofType": null
- }
- }
+ "kind": "SCALAR",
+ "name": "ID",
+ "ofType": null
}
},
"defaultValue": null
@@ -170,32 +162,10 @@
},
{
"kind": "OBJECT",
- "name": "AddProjectsToSecurityDashboardPayload",
- "description": "Autogenerated return type of AddProjectsToSecurityDashboard",
+ "name": "AddProjectToSecurityDashboardPayload",
+ "description": "Autogenerated return type of AddProjectToSecurityDashboard",
"fields": [
{
- "name": "addedProjectIds",
- "description": "IDs of projects that were added to the Instance Security Dashboard",
- "args": [
-
- ],
- "type": {
- "kind": "LIST",
- "name": null,
- "ofType": {
- "kind": "NON_NULL",
- "name": null,
- "ofType": {
- "kind": "SCALAR",
- "name": "ID",
- "ofType": null
- }
- }
- },
- "isDeprecated": false,
- "deprecationReason": null
- },
- {
"name": "clientMutationId",
"description": "A unique identifier for the client performing the mutation.",
"args": [
@@ -210,28 +180,6 @@
"deprecationReason": null
},
{
- "name": "duplicatedProjectIds",
- "description": "IDs of projects that are already added to the Instance Security Dashboard",
- "args": [
-
- ],
- "type": {
- "kind": "LIST",
- "name": null,
- "ofType": {
- "kind": "NON_NULL",
- "name": null,
- "ofType": {
- "kind": "SCALAR",
- "name": "ID",
- "ofType": null
- }
- }
- },
- "isDeprecated": false,
- "deprecationReason": null
- },
- {
"name": "errors",
"description": "Reasons why the mutation failed.",
"args": [
@@ -258,23 +206,15 @@
"deprecationReason": null
},
{
- "name": "invalidProjectIds",
- "description": "IDs of projects that were not added to the Instance Security Dashboard",
+ "name": "project",
+ "description": "Project that was added to the Instance Security Dashboard",
"args": [
],
"type": {
- "kind": "LIST",
- "name": null,
- "ofType": {
- "kind": "NON_NULL",
- "name": null,
- "ofType": {
- "kind": "SCALAR",
- "name": "ID",
- "ofType": null
- }
- }
+ "kind": "OBJECT",
+ "name": "Project",
+ "ofType": null
},
"isDeprecated": false,
"deprecationReason": null
@@ -17245,7 +17185,7 @@
"deprecationReason": null
},
{
- "name": "addProjectsToSecurityDashboard",
+ "name": "addProjectToSecurityDashboard",
"description": null,
"args": [
{
@@ -17256,7 +17196,7 @@
"name": null,
"ofType": {
"kind": "INPUT_OBJECT",
- "name": "AddProjectsToSecurityDashboardInput",
+ "name": "AddProjectToSecurityDashboardInput",
"ofType": null
}
},
@@ -17265,7 +17205,7 @@
],
"type": {
"kind": "OBJECT",
- "name": "AddProjectsToSecurityDashboardPayload",
+ "name": "AddProjectToSecurityDashboardPayload",
"ofType": null
},
"isDeprecated": false,
diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md
index 700aa510919..8b47fbda02e 100644
--- a/doc/api/graphql/reference/index.md
+++ b/doc/api/graphql/reference/index.md
@@ -26,17 +26,15 @@ Autogenerated return type of AddAwardEmoji
| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
| `errors` | String! => Array | Reasons why the mutation failed. |
-## AddProjectsToSecurityDashboardPayload
+## AddProjectToSecurityDashboardPayload
-Autogenerated return type of AddProjectsToSecurityDashboard
+Autogenerated return type of AddProjectToSecurityDashboard
| Name | Type | Description |
| --- | ---- | ---------- |
-| `addedProjectIds` | ID! => Array | IDs of projects that were added to the Instance Security Dashboard |
| `clientMutationId` | String | A unique identifier for the client performing the mutation. |
-| `duplicatedProjectIds` | ID! => Array | IDs of projects that are already added to the Instance Security Dashboard |
| `errors` | String! => Array | Reasons why the mutation failed. |
-| `invalidProjectIds` | ID! => Array | IDs of projects that were not added to the Instance Security Dashboard |
+| `project` | Project | Project that was added to the Instance Security Dashboard |
## AdminSidekiqQueuesDeleteJobsPayload
diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md
index 550e6e2b4d2..cd4c0b5241f 100644
--- a/doc/user/application_security/dast/index.md
+++ b/doc/user/application_security/dast/index.md
@@ -19,16 +19,15 @@ Dynamic Application Security Testing (DAST) comes into place.
## Overview
-If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web application(s)
+If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web applications
for known vulnerabilities using Dynamic Application Security Testing (DAST).
-
You can take advantage of DAST by either [including the CI job](#configuration) in
your existing `.gitlab-ci.yml` file or by implicitly using
-[Auto DAST](../../../topics/autodevops/stages.md#auto-dast-ultimate)
-that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
+[Auto DAST](../../../topics/autodevops/stages.md#auto-dast-ultimate),
+provided by [Auto DevOps](../../../topics/autodevops/index.md).
GitLab checks the DAST report, compares the found vulnerabilities between the source and target
-branches, and shows the information right on the merge request.
+branches, and shows the information on the merge request.
NOTE: **Note:**
This comparison logic uses only the latest pipeline executed for the target branch's base commit.
@@ -36,28 +35,32 @@ Running the pipeline on any other commit has no effect on the merge request.
![DAST Widget](img/dast_all_v12_9.png)
-By clicking on one of the detected linked vulnerabilities, you will be able to
+By clicking on one of the detected linked vulnerabilities, you can
see the details and the URL(s) affected.
![DAST Widget Clicked](img/dast_single_v12_9.png)
[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_Application_Security_Testing)
-is using the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy)
+uses the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy)
to perform an analysis on your running web application.
-By default, DAST executes [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan) and will perform passive scanning only. It will not actively attack your application.
-
+By default, DAST executes [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan)
+and performs passive scanning only. It won't actively attack your application.
However, DAST can be [configured](#full-scan)
-to also perform a so-called "active scan". That is, attack your application and produce a more extensive security report.
+to also perform an *active scan*: attack your application and produce a more extensive security report.
It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md).
NOTE: **Note:**
-A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show DAST scanner output. For example, if the DAST job finishes but the SAST job fails, the security dashboard will not show DAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure.
+A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any
+job fails to finish for any reason, the security dashboard won't show DAST scanner
+output. For example, if the DAST job finishes but the SAST job fails, the security
+dashboard won't show DAST results. The analyzer will output an
+[exit code](../../../development/integrations/secure.md#exit-code) on failure.
## Use cases
It helps you automatically find security vulnerabilities in your running web
-applications while you are developing and testing your applications.
+applications while you're developing and testing your applications.
## Requirements
@@ -69,9 +72,8 @@ To run a DAST job, you need GitLab Runner with the
For GitLab 11.9 and later, to enable DAST, you must
[include](../../../ci/yaml/README.md#includetemplate) the
[`DAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml)
-that's provided as a part of your GitLab installation.
-For GitLab versions earlier than 11.9, you can copy and use the job as defined
-in that template.
+that's provided as a part of your GitLab installation. For GitLab versions earlier
+than 11.9, you can copy and use the job as defined in that template.
Add the following to your `.gitlab-ci.yml` file:
@@ -88,32 +90,39 @@ There are two ways to define the URL to be scanned by DAST:
1. Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables).
1. Add it in an `environment_url.txt` file at the root of your project.
- This is great for testing in dynamic environments. In order to run DAST against
- an app that is dynamically created during a GitLab CI/CD pipeline, have the app
- persist its domain in an `environment_url.txt` file, and DAST will
- automatically parse that file to find its scan target.
- You can see an [example](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml)
- of this in our Auto DevOps CI YML.
+ This is great for testing in dynamic environments. In order to run DAST against
+ an app dynamically created during a GitLab CI/CD pipeline, have the app
+ persist its domain in an `environment_url.txt` file, and DAST
+ automatically parses that file to find its scan target.
+ You can see an [example](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml)
+ of this in our Auto DevOps CI YML.
-If both values are set, the `DAST_WEBSITE` value will take precedence.
+If both values are set, the `DAST_WEBSITE` value takes precedence.
-The included template will create a `dast` job in your CI/CD pipeline and scan
+The included template creates a `dast` job in your CI/CD pipeline and scan
your project's source code for possible vulnerabilities.
-The results will be saved as a
+The results are saved as a
[DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast-ultimate)
that you can later download and analyze. Due to implementation limitations we
always take the latest DAST artifact available. Behind the scenes, the
[GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast)
is used to run the tests on the specified URL and scan it for possible vulnerabilities.
-By default, the DAST template will use the latest major version of the DAST Docker image. Using the `DAST_VERSION` variable,
-you can choose to automatically update DAST with new features and fixes by pinning to a major version (e.g. 1), only update fixes by pinning to a minor version (e.g. 1.6) or prevent all updates by pinning to a specific version (e.g. 1.6.4).
+By default, the DAST template will use the latest major version of the DAST Docker
+image. Using the `DAST_VERSION` variable, you can choose how DAST updates:
+
+- Automatically update DAST with new features and fixes by pinning to a major version (such as `1`).
+- Only update fixes by pinning to a minor version (such as `1.6`).
+- Prevent all updates by pinning to a specific version (such as `1.6.4`).
+
Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page.
### When DAST scans run
-When using `DAST.gitlab-ci.yml` template, the `dast` job is run last as shown in the example below. To ensure DAST is scanning the latest code, your CI pipeline should deploy changes to the web server in one of the jobs preceeding the `dast` job.
+When using `DAST.gitlab-ci.yml` template, the `dast` job is run last as shown in
+the example below. To ensure DAST is scanning the latest code, your CI pipeline
+should deploy changes to the web server in one of the jobs preceding the `dast` job.
```yaml
stages:
@@ -123,9 +132,12 @@ stages:
- dast
```
-Be aware that if your pipeline is configured to deploy to the same webserver in each run, running a pipeline while another is still running, could cause a race condition
-where one pipeline overwrites the code from another pipeline. The site to be scanned should be excluded from changes for the duration of a DAST scan.
-The only changes to the site should be from the DAST scanner. Be aware that any changes that users, scheduled tasks, database or code changes, other pipelines, or other scanners make to
+Be aware that if your pipeline is configured to deploy to the same webserver in
+each run, running a pipeline while another is still running, could cause a race condition
+where one pipeline overwrites the code from another pipeline. The site to be scanned
+should be excluded from changes for the duration of a DAST scan.
+The only changes to the site should be from the DAST scanner. Be aware that any
+changes that users, scheduled tasks, database changes, code changes, other pipelines, or other scanners make to
the site during a scan could lead to inaccurate results.
### Authenticated scan
@@ -152,7 +164,10 @@ that you can later download and analyze.
Due to implementation limitations, we always take the latest DAST artifact available.
DANGER: **Danger:**
-**DO NOT** run an authenticated scan against a production server. When an authenticated scan is run, it may perform *any* function that the authenticated user can. This includes modifying and deleting data, submitting forms, following links, and so on. Only run an authenticated scan against a test server.
+**NEVER** run an authenticated scan against a production server. When an authenticated
+scan is run, it may perform *any* function that the authenticated user can. This
+includes actions like modifying and deleting data, submitting forms, and following links.
+Only run an authenticated scan against a test server.
### Full scan
@@ -173,7 +188,8 @@ The DAST job can be run anywhere, which means you can accidentally hit live web
and potentially damage them. You could even take down your production environment.
For that reason, you should use domain validation.
-Domain validation is not required by default. It can be required by setting the [environment variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to true.
+Domain validation is not required by default. It can be required by setting the
+[environment variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to `"true"`.
```yaml
include:
@@ -184,19 +200,23 @@ variables:
DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED: "true"
```
-Since ZAP full scan actively attacks the target application, DAST sends a ping to the target (normally defined in `DAST_WEBSITE` or `environment_url.txt`) beforehand.
-
-If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is false or unset, the scan will _proceed_ unless the response to the ping
-includes a `Gitlab-DAST-Permission` header with a value of `deny`.
+Since ZAP full scan actively attacks the target application, DAST sends a ping
+to the target (normally defined in `DAST_WEBSITE` or `environment_url.txt`) beforehand.
-If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is true, the scan will _exit_ unless the response to the ping
-includes a `Gitlab-DAST-Permission` header with a value of `allow`.
+- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `false` or unset, the scan will
+ proceed unless the response to the ping includes a `Gitlab-DAST-Permission`
+ header with a value of `deny`.
+- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `true`, the scan will exit
+ unless the response to the ping includes a `Gitlab-DAST-Permission` header with
+ a value of `allow`.
-Here are some examples of adding the `Gitlab-DAST-Permission` header to a response in Rails, Django, and Node (with Express).
+Here are some examples of adding the `Gitlab-DAST-Permission` header to a response
+in Rails, Django, and Node (with Express).
##### Ruby on Rails
-Here's how you would add a [custom header in Ruby on Rails](https://guides.rubyonrails.org/action_controller_overview.html#setting-custom-headers):
+Here's how you would add a
+[custom header in Ruby on Rails](https://guides.rubyonrails.org/action_controller_overview.html#setting-custom-headers):
```ruby
class DastWebsiteTargetController < ActionController::Base
@@ -210,7 +230,8 @@ end
##### Django
-Here's how you would add a [custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields):
+Here's how you would add a
+[custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields):
```python
class DastWebsiteTargetView(View):
@@ -223,7 +244,8 @@ class DastWebsiteTargetView(View):
##### Node (with Express)
-Here's how you would add a [custom header in Node (with Express)](http://expressjs.com/en/5x/api.html#res.append):
+Here's how you would add a
+[custom header in Node (with Express)](http://expressjs.com/en/5x/api.html#res.append):
```javascript
app.get('/dast-website-target', function(req, res) {
@@ -238,7 +260,8 @@ It's also possible to add the `Gitlab-DAST-Permission` header via a proxy.
###### NGINX
-The following config allows NGINX to act as a reverse proxy and add the `Gitlab-DAST-Permission` [header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header):
+The following configuration allows NGINX to act as a reverse proxy and add the
+`Gitlab-DAST-Permission` [header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header):
```nginx
# default.conf
@@ -290,7 +313,7 @@ API scans support OpenAPI V2 and OpenAPI V3 specifications. You can define these
#### Import API specification from a URL
If your API specification is accessible at a URL, you can pass that URL in directly as the target.
-The specification doesn't have to be hosted on the same host as the API being tested.
+The specification does not have to be hosted on the same host as the API being tested.
```yml
include:
@@ -302,9 +325,11 @@ variables:
#### Import API specification from a file
-If your API specification is in your repository, you can provide the specification's filename directly as the target. The specification file is expected to be in the `/zap/wrk` directory.
+If your API specification is in your repository, you can provide the specification's
+filename directly as the target. The specification file is expected to be in the
+`/zap/wrk` directory.
-```yml
+```yaml
dast:
script:
- mkdir -p /zap/wrk
@@ -317,23 +342,27 @@ dast:
#### Full scan
-API scans support full scanning, which can be enabled by using the `DAST_FULL_SCAN_ENABLED` environment variable. Domain validation isn't supported for full API scans.
+API scans support full scanning, which can be enabled by using the `DAST_FULL_SCAN_ENABLED`
+environment variable. Domain validation is not supported for full API scans.
#### Host override
-Specifications often define a host, which contains a domain name and a port. The host referenced may be different than the host of the API's review instance.
-This can cause incorrect URLs to be imported, or a scan on an incorrect host. Use the `DAST_API_HOST_OVERRIDE` environment variable to override these values.
+Specifications often define a host, which contains a domain name and a port. The
+host referenced may be different than the host of the API's review instance.
+This can cause incorrect URLs to be imported, or a scan on an incorrect host.
+Use the `DAST_API_HOST_OVERRIDE` environment variable to override these values.
For example, with a OpenAPI V3 specification containing:
-```yml
+```yaml
servers:
- url: https://api.host.com
```
-If the test version of the API is running at `https://api-test.host.com`, then the following DAST configuration can be used:
+If the test version of the API is running at `https://api-test.host.com`, then
+the following DAST configuration can be used:
-```yml
+```yaml
include:
- template: DAST.gitlab-ci.yml
@@ -346,9 +375,11 @@ Note that `DAST_API_HOST_OVERRIDE` is only applied to specifications imported by
#### Authentication using headers
-Tokens in request headers are often used as a way to authenticate API requests. You can achieve this by using the `DAST_REQUEST_HEADERS` environment variable. Headers are applied to every request DAST makes.
+Tokens in request headers are often used as a way to authenticate API requests.
+You can achieve this by using the `DAST_REQUEST_HEADERS` environment variable.
+Headers are applied to every request DAST makes.
-```yml
+```yaml
include:
- template: DAST.gitlab-ci.yml
@@ -426,7 +457,8 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia
### DAST command-line options
-Not all DAST configuration is available via environment variables. To find out all possible options, run the following configuration.
+Not all DAST configuration is available via environment variables. To find out all
+possible options, run the following configuration.
Available command-line options will be printed to the job log:
```yaml
@@ -438,7 +470,8 @@ dast:
- /analyze --help
```
-You must then overwrite the `script` command to pass in the appropriate argument. For example, AJAX spidering can be enabled by using `-j`, as shown in the following configuration:
+You must then overwrite the `script` command to pass in the appropriate argument.
+For example, AJAX spidering can be enabled by using `-j`, as shown in the following configuration:
```yaml
include:
@@ -453,8 +486,10 @@ dast:
### Custom ZAProxy configuration
The ZAProxy server contains many [useful configurable values](https://gitlab.com/gitlab-org/gitlab/issues/36437#note_245801885).
-Many key/values for `-config` remain undocumented, but there is an untested list of [possible keys](https://gitlab.com/gitlab-org/gitlab/issues/36437#note_244981023).
-Note that these options are not supported by DAST, and may break the DAST scan when used. An example of how to rewrite the Authorization header value with `TOKEN` follows:
+Many key/values for `-config` remain undocumented, but there is an untested list of
+[possible keys](https://gitlab.com/gitlab-org/gitlab/issues/36437#note_244981023).
+Note that these options are not supported by DAST, and may break the DAST scan
+when used. An example of how to rewrite the Authorization header value with `TOKEN` follows:
```yaml
include:
@@ -482,7 +517,9 @@ successfully run. For more information, see [Offline environments](../offline_de
To use DAST in an offline environment, you need:
- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements).
-- 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).
+- 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).
NOTE: **Note:**
GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
@@ -499,12 +536,15 @@ registry:
The process for importing Docker images into a local offline Docker registry depends on
**your network security policy**. Please consult your IT staff to find an accepted and approved
-process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
-with new definitions, so consider if you are able to make periodic updates yourself.
+process by which external resources can be imported or temporarily accessed. Note
+that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
+with new definitions, so consider if you're able to make periodic updates yourself.
For details on saving and transporting Docker images as a file, see Docker's documentation on
-[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/),
-[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/).
+[`docker save`](https://docs.docker.com/engine/reference/commandline/save/),
+[`docker load`](https://docs.docker.com/engine/reference/commandline/load/),
+[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and
+[`docker import`](https://docs.docker.com/engine/reference/commandline/import/).
### Set DAST CI job variables to use local DAST analyzers
@@ -530,7 +570,8 @@ The DAST job can emit various reports.
### List of URLs scanned
-When DAST completes scanning, the merge request page states the number of URLs that were scanned. Click **View details** to view the web console output which includes the list of scanned URLs.
+When DAST completes scanning, the merge request page states the number of URLs scanned.
+Click **View details** to view the web console output which includes the list of scanned URLs.
![DAST Widget](img/dast_urls_scanned_v12_10.png)
@@ -539,9 +580,13 @@ When DAST completes scanning, the merge request page states the number of URLs t
CAUTION: **Caution:**
The JSON report artifacts are not a public API of DAST and their format is expected to change in the future.
-The DAST tool always emits a JSON report file called `gl-dast-report.json` and sample reports can be found in the [DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/master/test/end-to-end/expect).
+The DAST tool always emits a JSON report file called `gl-dast-report.json` and
+sample reports can be found in the
+[DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/master/test/end-to-end/expect).
-There are two formats of data in the JSON report that are used side by side: the proprietary ZAP format which will be eventually deprecated, and a "common" format which will be the default in the future.
+There are two formats of data in the JSON report that are used side by side: the
+proprietary ZAP format which will be eventually deprecated, and a "common" format
+which will be the default in the future.
### Other formats
@@ -574,7 +619,9 @@ vulnerabilities in your groups, projects and pipelines. Read more about the
## Bleeding-edge vulnerability definitions
-ZAProxy first creates rules in the `alpha` class. After a testing period with the community, they are promoted to `beta`. DAST uses `beta` definitions by default. To request `alpha` definitions, use `-a` as shown in the following configuration:
+ZAProxy first creates rules in the `alpha` class. After a testing period with the
+community, they are promoted to `beta`. DAST uses `beta` definitions by default.
+To request `alpha` definitions, use `-a` as shown in the following configuration:
```yaml
include:
@@ -612,7 +659,8 @@ but commented out to help encourage others to add to it in the future. -->
By default, DAST will download all artifacts defined by previous jobs in the pipeline. If
your DAST job does not rely on `environment_url.txt` to define the URL under test or any other files created
-in previous jobs, we recommend you don't download artifacts. To avoid downloading artifacts, add the following to your `gitlab-ci.yml` file:
+in previous jobs, we recommend you don't download artifacts. To avoid downloading
+artifacts, add the following to your `gitlab-ci.yml` file:
```json
dast:
@@ -626,14 +674,14 @@ dast:
By default, ZAProxy, which DAST relies on, is allocated memory that sums to 25%
of the total memory on the host.
Since it keeps most of its information in memory during a scan,
-it is possible for DAST to run out of memory while scanning large applications.
+it's possible for DAST to run out of memory while scanning large applications.
This results in the following error:
```plaintext
[zap.out] java.lang.OutOfMemoryError: Java heap space
```
-Fortunately, it is straightforward to increase the amount of memory available
+Fortunately, it's straightforward to increase the amount of memory available
for DAST by overwriting the `script` key in the DAST template:
```yaml
diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md
index 0bd444f55c6..be9c8c9d129 100644
--- a/doc/user/application_security/dependency_scanning/index.md
+++ b/doc/user/application_security/dependency_scanning/index.md
@@ -7,19 +7,18 @@ type: reference, howto
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7.
Dependency Scanning helps to automatically find security vulnerabilities in your dependencies
-while you are developing and testing your applications, for example when your
+while you're developing and testing your applications, such as when your
application is using an external (open source) library which is known to be vulnerable.
## Overview
-If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your dependencies for known
+If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your dependencies for known
vulnerabilities using Dependency Scanning.
All dependencies are scanned, including the transitive dependencies (also known as nested dependencies).
-
You can take advantage of Dependency Scanning by either [including the Dependency Scanning template](#configuration)
in your existing `.gitlab-ci.yml` file or by implicitly using
-[Auto Dependency Scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning-ultimate)
-that is provided by [Auto DevOps](../../../topics/autodevops/index.md).
+the [Auto Dependency Scanning](../../../topics/autodevops/stages.md#auto-dependency-scanning-ultimate)
+provided by [Auto DevOps](../../../topics/autodevops/index.md).
GitLab checks the Dependency Scanning report, compares the found vulnerabilities
between the source and target branches, and shows the information on the
@@ -45,7 +44,7 @@ executor running in privileged mode. If you're using the shared Runners on GitLa
this is enabled by default.
CAUTION: **Caution:**
-If you use your own Runners, make sure that the Docker version you have installed
+If you use your own Runners, make sure your installed version of Docker
is **not** `19.03.0`. See [troubleshooting information](#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details.
Privileged mode is not necessary if you've [disabled Docker in Docker for Dependency Scanning](#disabling-docker-in-docker-for-dependency-scanning)
@@ -56,16 +55,16 @@ The following languages and dependency managers are supported.
| Language (package managers) | Supported | Scan tool(s) |
|----------------------------- | --------- | ------------ |
-| Java ([Gradle](https://gradle.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
-| Java ([Maven](https://maven.apache.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
-| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) |
-| PHP ([Composer](https://getcomposer.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
-| Python ([pip](https://pip.pypa.io/en/stable/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
+| Java ([Gradle](https://gradle.org/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
+| Java ([Maven](https://maven.apache.org/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
+| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) |
+| PHP ([Composer](https://getcomposer.org/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
+| Python ([pip](https://pip.pypa.io/en/stable/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
| Python ([Pipfile](https://pipenv.kennethreitz.org/en/latest/basics/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab/issues/11756 "Pipfile.lock support for Dependency Scanning"))| not available |
| Python ([poetry](https://python-poetry.org/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab/issues/7006 "Support Poetry in Dependency Scanning")) | not available |
-| Ruby ([gem](https://rubygems.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) |
-| Scala ([sbt](https://www.scala-sbt.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
-| Go ([Go Modules](https://github.com/golang/go/wiki/Modules)) | yes ([alpha](https://gitlab.com/gitlab-org/gitlab/issues/7132)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
+| Ruby ([gem](https://rubygems.org/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) |
+| Scala ([sbt](https://www.scala-sbt.org/)) | yes | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
+| Go ([Go Modules](https://github.com/golang/go/wiki/Modules)) | yes ([alpha](https://gitlab.com/gitlab-org/gitlab/issues/7132)) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) |
## Contribute your scanner
@@ -73,7 +72,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md)
## Configuration
-For GitLab 11.9 and later, to enable Dependency Scanning, you must
+To enable Dependency Scanning for GitLab 11.9 and later, you must
[include](../../../ci/yaml/README.md#includetemplate) the
[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml)
that's provided as a part of your GitLab installation.
@@ -89,7 +88,6 @@ include:
The included template will create a `dependency_scanning` job in your CI/CD
pipeline and scan your project's source code for possible vulnerabilities.
-
The results will be saved as a
[Dependency Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning-ultimate)
that you can later download and analyze. Due to implementation limitations, we
@@ -99,7 +97,6 @@ always take the latest Dependency Scanning artifact available.
The Dependency Scanning settings can be changed through [environment variables](#available-variables) by using the
[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
-
For example:
```yaml
@@ -119,9 +116,9 @@ CAUTION: **Deprecation:**
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead.
-If you want to override the job definition (for example, change properties like
-`variables` or `dependencies`), you need to declare a `dependency_scanning` job
-after the template inclusion and specify any additional keys under it. For example:
+If you want to override the job definition, such as changing properties like
+`variables` or `dependencies`, you must declare a `dependency_scanning` job
+after the template inclusion, and specify any additional keys under it. For example:
```yaml
include:
@@ -155,7 +152,7 @@ The following variables configure the Docker-in-Docker orchestrator.
| Environment variable | Default | Description |
| --------------------------------------- | ----------- | ----------- |
-| `DS_ANALYZER_IMAGES` | | Comma separated list of custom images. The official default images are still enabled. Read more about [customizing analyzers](analyzers.md). |
+| `DS_ANALYZER_IMAGES` | | Comma-separated list of custom images. The official default images are still enabled. Read more about [customizing analyzers](analyzers.md). |
| `DS_ANALYZER_IMAGE_TAG` | | Override the Docker tag of the official default images. Read more about [customizing analyzers](analyzers.md). |
| `DS_PULL_ANALYZER_IMAGES` | | Pull the images from the Docker registry (set to `0` to disable). |
| `DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, or `h`. For example, `300ms`, `1.5h`, or `2h45m`. |
@@ -168,17 +165,17 @@ The following variables are used for configuring specific analyzers (used for a
| Environment variable | Analyzer | Default | Description |
| --------------------------------------- | ------------------ | ---------------------------- |------------ |
-| `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local gemnasium database. |
-| `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the gemnasium database. |
+| `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local Gemnasium database. |
+| `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the Gemnasium database. |
| `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. |
| `DS_REMEDIATE` | `gemnasium` | `"true"` | Enable automatic remediation of vulnerable dependencies. |
| `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. |
| `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) |
| `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12296) in GitLab 12.1)|
-| `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that will be passed to `maven` by the analyzer. See an example for [using private repos](../index.md#using-private-maven-repos). |
+| `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that will be passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repos). |
| `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that will be passed to `gradle` by the analyzer. |
| `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer will pass to `sbt`. |
| `BUNDLER_AUDIT_UPDATE_DISABLED` | `bundler-audit` | `"false"` | Disable automatic updates for the `bundler-audit` analyzer. Useful if you're running Dependency Scanning in an offline, air-gapped environment.|
@@ -190,10 +187,10 @@ The following variables are used for configuring specific analyzers (used for a
### Using private Maven repos
-If you have a private Maven repository which requires login credentials,
+If your private Maven repository requires login credentials,
you can use the `MAVEN_CLI_OPTS` environment variable.
-Read more on [how to use private Maven repos](../index.md#using-private-maven-repos).
+Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos).
### Disabling Docker in Docker for Dependency Scanning
@@ -221,7 +218,7 @@ looks for `*.java` files to spin up the [gemnasium-maven](https://gitlab.com/git
image, while orchestrator only looks for the existence of `pom.xml` or `build.gradle`. GitLab uses
Linguist to detect new file types in the default branch. This means that when introducing files or
dependencies for a new language or package manager, the corresponding scans won't be triggered in
-the MR and will only run on the default branch once the MR is merged. This will be addressed by
+the merge request, and will only run on the default branch once the merge request is merged. This will be addressed by
[#211702](https://gitlab.com/gitlab-org/gitlab/-/issues/211702).
## Interacting with the vulnerabilities
@@ -232,9 +229,8 @@ Once a vulnerability is found, you can interact with it. Read more on how to
## Solutions for vulnerabilities (auto-remediation)
Some vulnerabilities can be fixed by applying the solution that GitLab
-automatically generates.
-
-Read more about the [solutions for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation).
+automatically generates. Read more about the
+[solutions for vulnerabilities](../index.md#solutions-for-vulnerabilities-auto-remediation).
## Security Dashboard
@@ -371,33 +367,33 @@ it highlighted:
CAUTION: **Deprecation:**
Beginning with GitLab 12.9, dependency scanning no longer reports `undefined` severity and confidence levels.
-Here is the description of the report file structure nodes and their meaning. All fields are mandatory to be present in
-the report JSON unless stated otherwise. Presence of optional fields depends on the underlying analyzers being used.
+This table describes the report file structure nodes and their meaning. All fields are mandatory to be present in
+the report JSON, unless stated otherwise. The presence of optional fields depends on the underlying analyzers used.
| Report JSON node | Description |
|------------------------------------------------------|-------------|
| `version` | Report syntax version used to generate this JSON. |
| `vulnerabilities` | Array of vulnerability objects. |
| `vulnerabilities[].id` | Unique identifier of the vulnerability. |
-| `vulnerabilities[].category` | Where this vulnerability belongs (SAST, Dependency Scanning etc.). For Dependency Scanning, it will always be `dependency_scanning`. |
-| `vulnerabilities[].name` | Name of the vulnerability, this must not include the occurrence's specific information. Optional. |
-| `vulnerabilities[].message` | A short text that describes the vulnerability, it may include occurrence's specific information. Optional. |
+| `vulnerabilities[].category` | Where this vulnerability belongs, such as SAST or Dependency Scanning. For Dependency Scanning, it will always be `dependency_scanning`. |
+| `vulnerabilities[].name` | Name of the vulnerability. Must not include the occurrence's specific information. Optional. |
+| `vulnerabilities[].message` | A short text that describes the vulnerability. May include occurrence's specific information. Optional. |
| `vulnerabilities[].description` | A long text that describes the vulnerability. Optional. |
-| `vulnerabilities[].cve` | (**DEPRECATED - use `vulnerabilities[].id` instead**) A fingerprint string value that represents a concrete occurrence of the vulnerability. It's used to determine whether two vulnerability occurrences are same or different. May not be 100% accurate. **This is NOT a [CVE](https://cve.mitre.org/)**. |
+| `vulnerabilities[].cve` | (**DEPRECATED - use `vulnerabilities[].id` instead**) A fingerprint string value that represents a concrete occurrence of the vulnerability. Used to determine whether two vulnerability occurrences are same or different. May not be 100% accurate. **This is NOT a [CVE](https://cve.mitre.org/)**. |
| `vulnerabilities[].severity` | How much the vulnerability impacts the software. Possible values: `Info`, `Unknown`, `Low`, `Medium`, `High`, `Critical`. |
| `vulnerabilities[].confidence` | How reliable the vulnerability's assessment is. Possible values: `Ignore`, `Unknown`, `Experimental`, `Low`, `Medium`, `High`, `Confirmed`. |
| `vulnerabilities[].solution` | Explanation of how to fix the vulnerability. Optional. |
| `vulnerabilities[].scanner` | A node that describes the analyzer used to find this vulnerability. |
-| `vulnerabilities[].scanner.id` | Id of the scanner as a snake_case string. |
+| `vulnerabilities[].scanner.id` | ID of the scanner as a `snake_case` string. |
| `vulnerabilities[].scanner.name` | Name of the scanner, for display purposes. |
| `vulnerabilities[].location` | A node that tells where the vulnerability is located. |
-| `vulnerabilities[].location.file` | Path to the dependencies file (e.g., `yarn.lock`). Optional. |
+| `vulnerabilities[].location.file` | Path to the dependencies file (such as `yarn.lock`). Optional. |
| `vulnerabilities[].location.dependency` | A node that describes the dependency of a project where the vulnerability is located. |
| `vulnerabilities[].location.dependency.package` | A node that provides the information on the package where the vulnerability is located. |
| `vulnerabilities[].location.dependency.package.name` | Name of the package where the vulnerability is located. Optional. |
| `vulnerabilities[].location.dependency.version` | Version of the vulnerable package. Optional. |
| `vulnerabilities[].identifiers` | An ordered array of references that identify a vulnerability on internal or external DBs. |
-| `vulnerabilities[].identifiers[].type` | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (e.g. `gemnasium` for [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/)). |
+| `vulnerabilities[].identifiers[].type` | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (such as `gemnasium` for [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/)). |
| `vulnerabilities[].identifiers[].name` | Name of the identifier for display purpose. |
| `vulnerabilities[].identifiers[].value` | Value of the identifier for matching purpose. |
| `vulnerabilities[].identifiers[].url` | URL to identifier's documentation. Optional. |
@@ -406,10 +402,10 @@ the report JSON unless stated otherwise. Presence of optional fields depends on
| `vulnerabilities[].links[].url` | URL of the vulnerability details document. Optional. |
| `remediations` | An array of objects containing information on cured vulnerabilities along with patch diffs to apply. Empty if no remediations provided by an underlying analyzer. |
| `remediations[].fixes` | An array of strings that represent references to vulnerabilities fixed by this particular remediation. |
-| `remediations[].fixes[].id` | The id of a fixed vulnerability. |
+| `remediations[].fixes[].id` | The ID of a fixed vulnerability. |
| `remediations[].fixes[].cve` | (**DEPRECATED - use `remediations[].fixes[].id` instead**) A string value that describes a fixed vulnerability in the same format as `vulnerabilities[].cve`. |
| `remediations[].summary` | Overview of how the vulnerabilities have been fixed. |
-| `remediations[].diff` | base64-encoded remediation code diff, compatible with [`git apply`](https://git-scm.com/docs/git-format-patch#_discussion). |
+| `remediations[].diff` | Base64-encoded remediation code diff, compatible with [`git apply`](https://git-scm.com/docs/git-format-patch#_discussion). |
## Versioning and release process
@@ -424,13 +420,13 @@ You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security
## Running Dependency Scanning in an offline environment
For self-managed GitLab instances in an environment with limited, restricted, or intermittent access
-to external resources through the internet, some adjustments are required for dependency scannings jobs to run successfully. For more information, see [Offline environments](../offline_deployments/index.md).
+to external resources through the internet, some adjustments are required for dependency scanning jobs to run successfully. For more information, see [Offline environments](../offline_deployments/index.md).
### Requirements for offline Dependency Scanning
-Here are the requirements for using Dependency Scanning in an offline environment:
+The requirements for using Dependency Scanning in an offline environment are:
-- [Disable Docker-In-Docker](#disabling-docker-in-docker-for-dependency-scanning)
+- [Disable Docker-In-Docker](#disabling-docker-in-docker-for-dependency-scanning).
- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements).
- Docker Container Registry with locally available copies of dependency scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images.
- Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/)
@@ -441,15 +437,15 @@ NOTE: **Note:**
GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy),
meaning the runner will try to pull Docker images from the GitLab container registry even if a local
copy is available. GitLab Runner's [`pull_policy` can be set to `if-not-present`](https://docs.gitlab.com/runner/executors/docker.html#using-the-if-not-present-pull-policy)
-in an offline environment if you prefer using only locally available Docker images. However, we
+in an offline environment, if you prefer using only locally available Docker images. However, we
recommend keeping the pull policy setting to `always` as it will better enable updated scanners to
be utilized within your CI/CD pipelines.
### Make GitLab Dependency Scanning analyzer images available inside your Docker registry
-For Dependency Scanning, import docker images ([supported languages and frameworks](#supported-languages-and-package-managers))
-from `registry.gitlab.com` to your offline docker registry. The Dependency Scanning analyzer
-docker images are:
+For Dependency Scanning, import Docker images ([supported languages and frameworks](#supported-languages-and-package-managers))
+from `registry.gitlab.com` to your offline Docker registry. The Dependency Scanning analyzer
+Docker images are:
```plaintext
registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium:2
@@ -461,8 +457,9 @@ registry.gitlab.com/gitlab-org/security-products/analyzers/bundler-audit:2
The process for importing Docker images into a local offline Docker registry depends on
**your network security policy**. Please consult your IT staff to find an accepted and approved
-process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
-with new definitions, so consider if you are able to make periodic updates yourself.
+process by which external resources can be imported or temporarily accessed.
+Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database)
+with new definitions, so consider if you can make periodic updates yourself.
For details on saving and transporting Docker images as a file, see Docker's documentation on
[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/),
@@ -470,8 +467,8 @@ For details on saving and transporting Docker images as a file, see Docker's doc
### Set Dependency Scanning CI config for "offline" use
-Below is a general `.gitlab-ci.yml` template to configure your environment for running Dependency
-Scanning offline:
+Below is a general `.gitlab-ci.yml` template to configure your environment for running
+Dependency Scanning offline:
```yaml
include:
@@ -535,7 +532,7 @@ gemnasium-maven-dependency_scanning:
- keytool -importcert -file /tmp/internal.crt -cacerts -storepass changeit -noprompt
```
-This adds the self-signed certificates of your maven repository to the Java Key Store of the analyzer's docker image.
+This adds the self-signed certificates of your Maven repository to the Java KeyStore of the analyzer's Docker image.
#### Scala (sbt) projects
@@ -548,7 +545,7 @@ gemnasium-maven-dependency_scanning:
- keytool -importcert -file /tmp/internal.crt -cacerts -storepass changeit -noprompt
```
-This adds the self-signed certificates of your maven repository to the Java Key Store of the analyzer's docker image.
+This adds the self-signed certificates of your Maven repository to the Java KeyStore of the analyzer's Docker image.
#### Python (pip) and Python (Pipfile) projects
@@ -572,11 +569,11 @@ gemnasium-python-dependency_scanning:
#### Python (setuptools)
-When using self-signed certificates for your private PyPi repo no extra job configuration (aside
+When using self-signed certificates for your private PyPi repository, no extra job configuration (aside
from the template `.gitlab-ci.yml` above) is needed. However, you must update your `setup.py` to
-ensure that it can reach your private repo. Here is an example configuration:
+ensure that it can reach your private repository. Here is an example configuration:
-1. Update `setup.py` to create a `dependency_links` attribute pointing at your private repo for each
+1. Update `setup.py` to create a `dependency_links` attribute pointing at your private repository for each
dependency in the `install_requires` list:
```python
@@ -602,6 +599,6 @@ ensure that it can reach your private repo. Here is an example configuration:
### Error response from daemon: error processing tar file: docker-tar: relocation error
This error occurs when the Docker version used to run the SAST job is `19.03.0`.
-You are advised to update to Docker `19.03.1` or greater. Older versions are not
+Consider updating to Docker `19.03.1` or greater. Older versions are not
affected. Read more in
[this issue](https://gitlab.com/gitlab-org/gitlab/issues/13830#note_211354992 "Current SAST container fails").