diff options
Diffstat (limited to 'doc/user/application_security')
22 files changed, 810 insertions, 574 deletions
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index a24374dff1d..86491c7d74e 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,4 +1,8 @@ -# Container Scanning **[ULTIMATE]** +--- +type: reference, howto +--- + +# Container Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. @@ -10,7 +14,7 @@ images (or more precisely the containers) for known vulnerabilities by using [Clair](https://github.com/coreos/clair) and [clair-scanner](https://github.com/arminc/clair-scanner), two open source tools for Vulnerability Static Analysis for containers. -You can take advantage of Container Scanning by either [including the CI job](#including-the-provided-template) in +You can take advantage of Container Scanning by either [including the CI job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using [Auto Container Scanning](../../../topics/autodevops/index.md#auto-container-scanning-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -40,11 +44,14 @@ To enable Container Scanning in your pipeline, you need: [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners) executor running in privileged mode. If you're using the shared Runners on GitLab.com, this is enabled by default. +- Docker `18.09.03` or higher installed on the machine where the Runners are + running. If you're using the shared Runners on GitLab.com, this is already + the case. - To [build and push](../../../ci/docker/using_docker_build.md#container-registry-examples) your Docker image to your project's [Container Registry](../../project/container_registry.md). The name of the Docker image should match the following scheme: - ``` + ```text $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA ``` @@ -52,32 +59,16 @@ To enable Container Scanning in your pipeline, you need: [predefined environment variables](../../../ci/variables/predefined_variables.md) document. -## Configuring Container Scanning - -To enable Container Scanning in your project, define a job in your -`.gitlab-ci.yml` file that generates the -[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate). - -This can be done in two ways: - -- For GitLab 11.9 and later, including the provided - `Container-Scanning.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. - -### Including the provided template - -NOTE: **Note:** -The CI/CD Container Scanning template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). +## Configuration -A CI/CD [Container Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) -with the default Container Scanning job definition is provided as a part of your GitLab -installation that you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. +For GitLab 11.9 and later, to enable Container Scanning, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.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. -To enable Container Scanning using the provided template, add the following to -your `.gitlab-ci.yml` file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -86,12 +77,12 @@ include: The included template will: -- Create a `container_scanning` job in your CI/CD pipeline. -- Pull the already built Docker image from your project's - [Container Registry](../../project/container_registry.md) (see [requirements](#requirements)) - and scan it for possible vulnerabilities. +1. Create a `container_scanning` job in your CI/CD pipeline. +1. Pull the already built Docker image from your project's + [Container Registry](../../project/container_registry.md) (see [requirements](#requirements)) + and scan it for possible vulnerabilities. -The report will be saved as a +The results will be saved as a [Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest Container Scanning @@ -103,95 +94,6 @@ If you want to whitelist some specific vulnerabilities, you can do so by definin them in a YAML file named `clair-whitelist.yml`. Read more in the [Clair documentation](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file). -### Manual job definition for GitLab 11.5 and later - -CAUTION: **Caution:** -The job definition shown below is supported on GitLab 11.5 and later versions. -However, if you're using GitLab 11.9+, it's recommended to use -[the provided Container Scanning template](#including-the-provided-template). - -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `container_scanning` -job can be added: - -```yaml -container_scanning: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - ## Define two new variables based on GitLab's CI/CD predefined variables - ## https://docs.gitlab.com/ee/ci/variables/README.html#predefined-environment-variables - CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG - CI_APPLICATION_TAG: $CI_COMMIT_SHA - CLAIR_LOCAL_SCAN_VERSION: v2.0.8_fe9b059d930314b54c78f75afe265955faf4fdc1 - allow_failure: true - services: - - docker:stable-dind - script: - - docker run -d --name db arminc/clair-db:latest - - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:${CLAIR_LOCAL_SCAN_VERSION} - - apk add -U wget ca-certificates - - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} - - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64 - - mv clair-scanner_linux_amd64 clair-scanner - - chmod +x clair-scanner - - touch clair-whitelist.yml - - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done - - retries=0 - - echo "Waiting for clair daemon to start" - - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done - - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true - artifacts: - reports: - container_scanning: gl-container-scanning-report.json -``` - -### Manual job definition for GitLab 11.4 and earlier (deprecated) - -CAUTION: **Deprecated:** -Before GitLab 11.5, the Container Scanning job and artifact had to be named specifically -to automatically extract report data and show it in the merge request widget. -While these old job definitions are still maintained, they have been deprecated -and may be removed in the next major release, GitLab 12.0. You are strongly -advised to update your current `.gitlab-ci.yml` configuration to reflect that change. - -For GitLab 11.4 and earlier, the Container Scanning job should look like: - -```yaml -container_scanning: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - ## Define two new variables based on GitLab's CI/CD predefined variables - ## https://docs.gitlab.com/ee/ci/variables/README.html#predefined-environment-variables - CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG - CI_APPLICATION_TAG: $CI_COMMIT_SHA - CLAIR_LOCAL_SCAN_VERSION: v2.0.8_fe9b059d930314b54c78f75afe265955faf4fdc1 - allow_failure: true - services: - - docker:stable-dind - script: - - docker run -d --name db arminc/clair-db:latest - - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:${CLAIR_LOCAL_SCAN_VERSION} - - apk add -U wget ca-certificates - - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} - - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64 - - mv clair-scanner_linux_amd64 clair-scanner - - chmod +x clair-scanner - - touch clair-whitelist.yml - - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done - - retries=0 - - echo "Waiting for clair daemon to start" - - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done - - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true - artifacts: - paths: [gl-container-scanning-report.json] -``` - -Alternatively, the job name could be `sast:container` -and the artifact name could be `gl-sast-container-report.json`. -These names have been deprecated with GitLab 11.0 -and may be removed in the next major release, GitLab 12.0. - ## Security Dashboard The Security Dashboard is a good place to get an overview of all the security @@ -202,3 +104,25 @@ vulnerabilities in your groups and projects. Read more about the Once a vulnerability is found, you can interact with it. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). + +## Vulnerabilities database update + +For more information about the vulnerabilities database update, check the +[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). + +## Troubleshooting + +### docker: Error response from daemon: failed to copy xattrs + +When the GitLab Runner uses the Docker executor and NFS is used +(e.g., `/var/lib/docker` is on an NFS mount), Container Scanning might fail with +an error like the following: + +```text +docker: Error response from daemon: failed to copy xattrs: failed to set xattr "security.selinux" on /path/to/file: operation not supported. +``` + +This is a result of a bug in Docker which is now [fixed](https://github.com/containerd/continuity/pull/138 "fs: add WithAllowXAttrErrors CopyOpt"). +To prevent the error, ensure the Docker version that the Runner is using is +`18.09.03` or higher. For more information, see +[issue #10241](https://gitlab.com/gitlab-org/gitlab-ee/issues/10241 "Investigate why Container Scanning is not working with NFS mounts"). diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index a722aa88f9d..fa84f995e58 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,8 +1,17 @@ -# Dynamic Application Security Testing (DAST) **[ULTIMATE]** +--- +type: reference, howto +--- + +# Dynamic Application Security Testing (DAST) **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4348) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. +NOTE: **4 of the top 6 attacks were application based.** +Download our whitepaper, +["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) +to learn how to protect your organization. + Running [static checks](../sast/index.md) on your code is the first step to detect vulnerabilities that can put the security of your code at risk. Yet, once deployed, your application is exposed to a new category of possible attacks, @@ -14,7 +23,7 @@ Dynamic Application Security Testing (DAST) comes into place. If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web application(s) for known vulnerabilities using Dynamic Application Security Testing (DAST). -You can take advantage of DAST by either [including the CI job](#configuring-dast) in +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/index.md#auto-dast-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -51,30 +60,16 @@ applications while you are developing and testing your applications. To run a DAST job, you need GitLab Runner with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). -## Configuring DAST - -To enable DAST in your project, define a job in your `.gitlab-ci.yml` file that generates the -[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate). - -This can be done in two ways: - -- For GitLab 11.9 and later, including the provided `DAST.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. - -### Including the provided template +## Configuration -NOTE: **Note:** -The CI/CD DAST template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). +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-ee/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. -A CI/CD [DAST template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml) -with the default DAST job definition is provided as a part of your GitLab -installation which you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. - -To enable DAST using the provided template, add the following to your `.gitlab-ci.yml` -file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -84,22 +79,22 @@ variables: DAST_WEBSITE: https://example.com ``` +There are two ways to define the URL to be scanned by DAST: + +- Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables). +- Add it in an `environment_url.txt` file at the root of your project. + The included template will create a `dast` job in your CI/CD pipeline and scan your project's source code for possible vulnerabilities. -The report will be saved as a +The results will be saved as a [DAST report artifact](../../../ci/yaml/README.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. -There are two ways to define the URL to be scanned by DAST: - -- Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables). -- Add it in an `environment_url.txt` file at the root of your project. - -#### Authenticated scan +### Authenticated scan It's also possible to authenticate the user before performing the DAST checks: @@ -117,12 +112,12 @@ variables: DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between ``` -The report will be saved as a +The results will be saved as a [DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. -#### Full scan +### Full scan DAST can be configured to perform [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan), which includes both passive and active scanning against the same target website: @@ -135,7 +130,7 @@ variables: DAST_FULL_SCAN_ENABLED: "true" ``` -#### Customizing the DAST settings +### Customizing the DAST settings The DAST settings can be changed through environment variables by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. @@ -155,7 +150,7 @@ variables: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable will take precedence. -#### Overriding the DAST template +### Overriding the DAST template If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare a `dast` job after the @@ -176,78 +171,27 @@ As the DAST job belongs to a separate `dast` stage that runs after all [default stages](../../../ci/yaml/README.md#stages), don't forget to add `stage: dast` when you override the template job definition. -### Manual job definition for GitLab 11.5 and later - -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `dast` -job can be added: - -```yaml -dast: - image: registry.gitlab.com/gitlab-org/security-products/zaproxy - variables: - website: "https://example.com" - allow_failure: true - script: - - mkdir /zap/wrk/ - - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true - - cp /zap/wrk/gl-dast-report.json . - artifacts: - reports: - dast: gl-dast-report.json -``` - -Where the `website` variable holds the URL to run the tests against. - -For an authenticated scan, use the following definition: - -```yaml -dast: - image: registry.gitlab.com/gitlab-org/security-products/zaproxy - variables: - website: "https://example.com" - login_url: "https://example.com/sign-in" - username: "john.doe@example.com" - password: "john-doe-password" - allow_failure: true - script: - - mkdir /zap/wrk/ - - /zap/zap-baseline.py -J gl-dast-report.json -t $website - --auth-url $login_url - --auth-username $username - --auth-password $password || true - - cp /zap/wrk/gl-dast-report.json . - artifacts: - reports: - dast: gl-dast-report.json -``` - -See the [zaproxy documentation](https://gitlab.com/gitlab-org/security-products/zaproxy) -to learn more about the authentication settings. - -### Manual job definition for GitLab 11.4 and earlier (deprecated) - -CAUTION: **Caution:** -Before GitLab 11.5, DAST job and artifact had to be named specifically -to automatically extract report data and show it in the merge request widget. -While these old job definitions are still maintained they have been deprecated -and may be removed in next major release, GitLab 12.0. You are strongly advised -to update your current `.gitlab-ci.yml` configuration to reflect that change. - -For GitLab 11.4 and earlier, the job should look like: - -```yaml -dast: - image: registry.gitlab.com/gitlab-org/security-products/zaproxy - variables: - website: "https://example.com" - allow_failure: true - script: - - mkdir /zap/wrk/ - - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true - - cp /zap/wrk/gl-dast-report.json . - artifacts: - paths: [gl-dast-report.json] -``` +## Available variables + +DAST can be [configured](#customizing-the-dast-settings) using environment variables. +Since it's a wrapper around the ZAP scanning scripts +([baseline](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan) +or [full](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) scan), it +accepts all arguments those scripts recognize (the arguments are the same). +The choice of the scan type depends on the `DAST_FULL_SCAN_ENABLED` environment +variable value. + +| Environment variable | Required | Description | +|-----------------------------| ----------|--------------------------------------------------------------------------------| +| `DAST_WEBSITE` | yes | The URL of the website to scan. | +| `DAST_AUTH_URL` | no | The authentication URL of the website to scan. | +| `DAST_USERNAME` | no | The username to authenticate to in the website. | +| `DAST_PASSWORD` | no | The password to authenticate to in the website. | +| `DAST_USERNAME_FIELD` | no | The name of username field at the sign-in HTML form. | +| `DAST_PASSWORD_FIELD` | no | The name of password field at the sign-in HTML form. | +| `DAST_AUTH_EXCLUDE_URLS` | no | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. | +| `DAST_TARGET_AVAILABILITY_TIMEOUT` | no | Time limit in seconds to wait for target availability. Scan is attempted nevertheless if it runs out. Integer. Defaults to `60`. | +| `DAST_FULL_SCAN_ENABLED` | no | Switches the tool to execute [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | ## Security Dashboard @@ -259,3 +203,20 @@ vulnerabilities in your groups and projects. Read more about the Once a vulnerability is found, you can interact with it. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). + +## Vulnerabilities database update + +For more information about the vulnerabilities database update, check the +[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_2.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_2.png Binary files differnew file mode 100644 index 00000000000..af9cee08d71 --- /dev/null +++ b/doc/user/application_security/dependency_list/img/dependency_list_v12_2.png diff --git a/doc/user/application_security/dependency_list/index.md b/doc/user/application_security/dependency_list/index.md new file mode 100644 index 00000000000..38c38bbd8a9 --- /dev/null +++ b/doc/user/application_security/dependency_list/index.md @@ -0,0 +1,49 @@ +# Dependency List **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10075) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. + +The Dependency list allows you to see your project's dependencies, and key +details about them, including their known vulnerabilities. To see it, +navigate to **Security & Compliance > Dependency List** in your project's +sidebar. + +## Requirements + +1. The [Dependency Scanning](../dependency_scanning/index.md) CI job must be + configured for your project. +1. Your project uses at least one of the + [languages and package managers](../dependency_scanning/index.md#supported-languages-and-package-managers) + supported by Gemnasium. + +## Viewing dependencies + + + +Dependencies are displayed with the following information: + +| Field | Description | +| --------- | ----------- | +| Status | Displays whether or not the dependency has any known vulnerabilities | +| Component | The dependency's name | +| Version | The exact locked version of the dependency your project uses | +| Packager | The packager used to install the depedency | +| Location | A link to the packager-specific lockfile in your project that declared the dependency | + +Dependencies shown are initially sorted by their names. They can also be sorted +by the packager they were installed by, or by the severity of their known +vulnerabilities. + +There is a second list under the `Vulnerable components` tab displaying only +those dependencies with known vulnerabilities. If there are none, this tab is +disabled. + +### Vulnerabilities + +If a dependency has known vulnerabilities, they can be viewed by clicking on the +`Status` cell of that dependency. The severity and description of each +vulnerability will then be displayed below it. + +## Downloading the Dependency List + +Your project's full list of dependencies and their details can be downloaded in +`JSON` format by clicking on the download button. diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md new file mode 100644 index 00000000000..3b4b341739b --- /dev/null +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -0,0 +1,133 @@ +# Dependency Scanning Analyzers **(ULTIMATE)** + +Dependency Scanning relies on underlying third party tools that are wrapped into +what we call "Analyzers". An analyzer is a +[dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers) +that wraps a particular tool to: + +- Expose its detection logic. +- Handle its execution. +- Convert its output to the common format. + +This is achieved by implementing the [common API](https://gitlab.com/gitlab-org/security-products/analyzers/common). + +Dependency Scanning supports the following official analyzers: + +- [`bundler-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit) +- [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) +- [`gemnasium-maven`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven) +- [`gemnasium-python`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python) +- [`retire.js`](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) + +The analyzers are published as Docker images that Dependency Scanning will use +to launch dedicated containers for each analysis. + +Dependency Scanning is pre-configured with a set of **default images** that are +maintained by GitLab, but users can also integrate their own **custom images**. + +## Official default analyzers + +Any custom change to the official analyzers can be achieved by using an +[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-dependency-scanning-settings). + +### Using a custom Docker mirror + +You can switch to a custom Docker registry that provides the official analyzer +images under a different prefix. For instance, the following instructs Dependency +Scanning to pull `my-docker-registry/gl-images/gemnasium` +instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium`. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_ANALYZER_IMAGE_PREFIX: my-docker-registry/gl-images +``` + +This configuration requires that your custom registry provides images for all +the official analyzers. + +### Selecting specific analyzers + +You can select the official analyzers you want to run. Here's how to enable +`bundler-audit` and `gemnasium` while disabling all the other default ones. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DEFAULT_ANALYZERS: "bundler-audit,gemnasium" +``` + +`bundler-audit` runs first. When merging the reports, Dependency Scanning will +remove the duplicates and will keep the `bundler-audit` entries. + +### Disabling default analyzers + +Setting `DS_DEFAULT_ANALYZERS` to an empty string will disable all the official +default analyzers. In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DEFAULT_ANALYZERS: "" +``` + +That's needed when one totally relies on [custom analyzers](#custom-analyzers). + +## Custom analyzers + +You can provide your own analyzers as a comma separated list of Docker images. +Here's how to add `analyzers/nugget` and `analyzers/perl` to the default images. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_ANALYZER_IMAGES: "my-docker-registry/analyzers/nugget,amy-docker-registry/nalyzers/perl" +``` + +The values must be the full path to the container registry images, +like what you would feed to the `docker pull` command. + +NOTE: **Note:** +This configuration doesn't benefit from the integrated detection step. Dependency +Scanning has to fetch and spawn each Docker image to establish whether the +custom analyzer can scan the source code. + +## Analyzers data + +The following table lists the data available for each official analyzer. + +| Property \ Tool | Gemnasium | bundler-audit | Retire.js | +|---------------------------------------|:------------------:|:------------------:|:------------------:| +| Severity | ๐ | โ | โ | +| Title | โ | โ | โ | +| File | โ | โ | โ | +| Start line | ๐ | ๐ | ๐ | +| End line | ๐ | ๐ | ๐ | +| External ID (e.g., CVE) | โ | โ | โ | +| URLs | โ | โ | โ | +| Internal doc/explanation | โ | ๐ | ๐ | +| Solution | โ | โ | ๐ | +| Confidence | ๐ | ๐ | ๐ | +| Affected item (e.g. class or package) | โ | โ | โ | +| Source code extract | ๐ | ๐ | ๐ | +| Internal ID | โ | ๐ | ๐ | +| Date | โ | ๐ | ๐ | +| Credits | โ | ๐ | ๐ | + +- โ => we have that data +- โ => we have that data but it's partially reliable, or we need to extract that data from unstructured content +- ๐ => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. + +The values provided by these tools are heterogeneous so they are sometimes +normalized into common values (e.g., `severity`, `confidence`, etc). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index f3bf743ad03..3148ec63c79 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -1,4 +1,8 @@ -# Dependency Scanning **[ULTIMATE]** +--- +type: reference, howto +--- + +# Dependency Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. @@ -8,7 +12,7 @@ in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your dependencies for known vulnerabilities using Dependency Scanning. -You can take advantage of Dependency Scanning by either [including the CI job](#including-the-provided-template) +You can take advantage of Dependency Scanning by either [including the CI job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using [Auto Dependency Scanning](../../../topics/autodevops/index.md#auto-dependency-scanning-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -46,43 +50,45 @@ this is enabled by default. The following languages and dependency managers are supported. -| Language (package managers) | Scan tool | -|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| -| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [Retire.js](https://retirejs.github.io/retire.js) | -| Python ([pip](https://pip.pypa.io/en/stable/)) (only `requirements.txt` supported) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | -| Ruby ([gem](https://rubygems.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general), [bundler-audit](https://github.com/rubysec/bundler-audit) | -| Java ([Maven](https://maven.apache.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | -| PHP ([Composer](https://getcomposer.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | - -Some scanners require to send a list of project dependencies to GitLab's central -servers to check for vulnerabilities. To learn more about this or to disable it, -refer to the [GitLab Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks). +| Language (package managers) | Supported | Scan tool(s) | +|----------------------------- | --------- | ------------ | +| Java ([Gradle](https://gradle.org/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/13075 "Dependency Scanning for Gradle" )) | not available | +| Java ([Maven](https://maven.apache.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| JavaScript ([npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/en/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js) | +| Go ([Golang](https://golang.org/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/7132 "Dependency Scanning for Go")) | not available | +| PHP ([Composer](https://getcomposer.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| Python ([pip](https://pip.pypa.io/en/stable/)) (only `requirements.txt` supported) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| Python ([Pipfile](https://docs.pipenv.org/en/latest/basics/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/11756 "Pipfile.lock support for Dependency Scanning"))| not available | +| Python ([poetry](https://poetry.eustace.io/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab-ee/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) | -## Configuring Dependency Scanning +## Remote checks -To enable Dependency Scanning in your project, define a job in your `.gitlab-ci.yml` -file that generates the -[Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate). +While some tools pull a local database to check vulnerabilities, some others +like Gemnasium require sending data to GitLab central servers to analyze them: -This can be done in two ways: +1. Gemnasium scans the dependencies of your project locally and sends a list of + packages to GitLab central servers. +1. The servers return the list of known vulnerabilities for all versions of + these packages. +1. The client picks up the relevant vulnerabilities by comparing with the versions + of the packages that are used by the project. -- For GitLab 11.9 and later, including the provided `Dependency-Scanning.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. +The Gemnasium client does **NOT** send the exact package versions your project relies on. -### Including the provided template +You can disable the remote checks by [using](#customizing-the-dependency-scanning-settings) +the `DS_DISABLE_REMOTE_CHECKS` environment variable and setting it to `true`. -NOTE: **Note:** -The CI/CD Dependency Scanning template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). +## Configuration -A CI/CD [Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) -with the default Dependency Scanning job definition is provided as a part of your GitLab -installation which you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. +For GitLab 11.9 and later, to enable Dependency Scanning, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.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 +that template. -To enable Dependency Scanning using the provided template, add the following to -your `.gitlab-ci.yml` file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -92,22 +98,15 @@ 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 report will be saved as a +The results will be saved as a [Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest Dependency Scanning artifact available. -Some security scanners require to send a list of project dependencies to GitLab -central servers to check for vulnerabilities. To learn more about this or to -disable it, check the -[GitLab Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks). - -#### Customizing the Dependency Scanning settings +### Customizing the Dependency Scanning settings -The Dependency Scanning settings can be changed through environment variables by using the +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`. -These variables are documented in the -[Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings). For example: @@ -116,13 +115,13 @@ include: template: Dependency-Scanning.gitlab-ci.yml variables: - DEP_SCAN_DISABLE_REMOTE_CHECKS: true + DS_DISABLE_REMOTE_CHECKS: true ``` Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable will take precedence. -#### Overriding the Dependency Scanning template +### Overriding the Dependency Scanning template If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare a `dependency_scanning` job @@ -137,88 +136,34 @@ dependency_scanning: CI_DEBUG_TRACE: "true" ``` -### Manual job definition for GitLab 11.5 and later - -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `dependency_scanning` -job can be added: - -```yaml -dependency_scanning: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} - - | - docker run \ - --env DS_ANALYZER_IMAGES \ - --env DS_ANALYZER_IMAGE_PREFIX \ - --env DS_ANALYZER_IMAGE_TAG \ - --env DS_DEFAULT_ANALYZERS \ - --env DEP_SCAN_DISABLE_REMOTE_CHECKS \ - --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \ - --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \ - --env DS_RUN_ANALYZER_TIMEOUT \ - --volume "$PWD:/code" \ - --volume /var/run/docker.sock:/var/run/docker.sock \ - "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code - dependencies: [] - artifacts: - reports: - dependency_scanning: gl-dependency-scanning-report.json -``` - -You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings) -via `docker run --env` to customize your job execution. - -### Manual job definition for GitLab 11.4 and earlier (deprecated) - -CAUTION: **Caution:** -Before GitLab 11.5, the Dependency Scanning job and artifact had to be named specifically -to automatically extract the report data and show it in the merge request widget. -While these old job definitions are still maintained, they have been deprecated -and may be removed in the next major release, GitLab 12.0. You are strongly advised -to update your current `.gitlab-ci.yml` configuration to reflect that change. - -For GitLab 11.4 and earlier, the job should look like: - -```yaml -dependency_scanning: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} - - | - docker run \ - --env DS_ANALYZER_IMAGES \ - --env DS_ANALYZER_IMAGE_PREFIX \ - --env DS_ANALYZER_IMAGE_TAG \ - --env DS_DEFAULT_ANALYZERS \ - --env DS_EXCLUDED_PATHS \ - --env DEP_SCAN_DISABLE_REMOTE_CHECKS \ - --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \ - --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \ - --env DS_RUN_ANALYZER_TIMEOUT \ - --volume "$PWD:/code" \ - --volume /var/run/docker.sock:/var/run/docker.sock \ - "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code - artifacts: - paths: [gl-dependency-scanning-report.json] -``` +### Available variables + +Dependency Scanning can be [configured](#customizing-the-dependency-scanning-settings) +using environment variables. + +| Environment variable | Function | +|-------------------------------- |----------| +| `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_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). 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_PYTHON_VERSION` | 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-ee/issues/12296) in GitLab 12.1)| +| `DS_PIP_DEPENDENCY_PATH` | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12412) in GitLab 12.2) | +| `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | +| `DS_DISABLE_REMOTE_CHECKS` | Do not send any data to GitLab. Used in the [Gemnasium analyzer](#remote-checks). | +| `DS_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to `0` to disable). | +| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. | +| `DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 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`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | +| `DS_PULL_ANALYZER_IMAGE_TIMEOUT` | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `ยตs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | +| `DS_RUN_ANALYZER_TIMEOUT` | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `ยตs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | +| `PIP_INDEX_URL` | Base URL of Python Package Index (default `https://pypi.org/simple`). | +| `PIP_EXTRA_INDEX_URL` | 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. | ## Reports JSON format CAUTION: **Caution:** The JSON report artifacts are not a public API of Dependency Scanning and their format may change in future. -The Dependency Scanning tool emits a JSON report file. Here is an example of a structure for a report will all important parts of +The Dependency Scanning tool emits a JSON report file. Here is an example of the report structure with all important parts of it highlighted: ```json-doc @@ -343,10 +288,10 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].severity` | How much the vulnerability impacts the software. Possible values: `Undefined` (an analyzer has not provided this info), `Info`, `Unknown`, `Low`, `Medium`, `High`, `Critical`. | | `vulnerabilities[].confidence` | How reliable the vulnerability's assessment is. Possible values: `Undefined` (an analyzer has not provided this info), `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 find this vulnerability. | +| `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.name` | Name of the scanner, for display purposes. | -| `vulnerabilities[].location` | A node that tells which class and/or method is affected by the vulnerability. | +| `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.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. | @@ -360,7 +305,7 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].links` | An array of references to external documentation pieces or articles that describe the vulnerability further. Optional. | | `vulnerabilities[].links[].name` | Name of the vulnerability details link. Optional. | | `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. | +| `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[].cve` | A string value that describes a fixed vulnerability occurrence in the same format as `vulnerabilities[].cve`. | | `remediations[].summary` | Overview of how the vulnerabilities have been fixed. | @@ -377,19 +322,35 @@ vulnerabilities in your groups and projects. Read more about the Once a vulnerability is found, you can interact with it. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). -## Dependency List +## Vulnerabilities database update + +For more information about the vulnerabilities database update, check the +[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10075) -in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +## Dependency List **(ULTIMATE)** -An additional benefit of Dependency Scanning is the ability to get a list of your project's dependencies with their versions. +An additional benefit of Dependency Scanning is the ability to view your +project's dependencies and their known vulnerabilities. Read more about +the [Dependency List](../dependency_list/index.md). -This list can be generated only for [supported languages and package managers](#supported-languages-and-package-managers). +## Versioning and release process -To see the generated dependency list, navigate to the Dependency List page under your project's left sidebar menu **Project > Dependency List**. +Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md). ## Contributing to the vulnerability database You can search the [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project to find a vulnerability in the Gemnasium database. -You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md).
\ No newline at end of file +You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/img/create_issue_with_list_hover.png b/doc/user/application_security/img/create_issue_with_list_hover.png Binary files differindex 7d70e8299f5..4c38862e68f 100644 --- a/doc/user/application_security/img/create_issue_with_list_hover.png +++ b/doc/user/application_security/img/create_issue_with_list_hover.png diff --git a/doc/user/application_security/img/dismissed_info.png b/doc/user/application_security/img/dismissed_info.png Binary files differindex 64d5cf26ed2..b4470b664d2 100644 --- a/doc/user/application_security/img/dismissed_info.png +++ b/doc/user/application_security/img/dismissed_info.png diff --git a/doc/user/application_security/img/interactive_reports.png b/doc/user/application_security/img/interactive_reports.png Binary files differindex 373b39104db..1b2ef0d3da9 100644 --- a/doc/user/application_security/img/interactive_reports.png +++ b/doc/user/application_security/img/interactive_reports.png diff --git a/doc/user/application_security/img/vulnerability_solution.png b/doc/user/application_security/img/vulnerability_solution.png Binary files differindex 7443b9b6eea..d86b89a5f99 100644 --- a/doc/user/application_security/img/vulnerability_solution.png +++ b/doc/user/application_security/img/vulnerability_solution.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 679847b76d7..83ea0ea3386 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,23 +1,59 @@ -# GitLab Secure **[ULTIMATE]** +--- +type: reference, howto +--- -Check your application for security vulnerabilities that may lead to unauthorized access, -data leaks, and denial of services. GitLab will perform static and dynamic tests on the -code of your application, looking for known flaws and report them in the merge request -so you can fix them before merging. Security teams can use dashboards to get a -high-level view on projects and groups, and start remediation processes when needed. +# GitLab Secure **(ULTIMATE)** + +Check your application for security vulnerabilities that may lead to +unauthorized access, data leaks, and denial of services. + +GitLab will perform static and dynamic tests on the code of your application, +looking for known flaws and report them in the merge request so you can fix +them before merging. + +Security teams can use dashboards to get a high-level view on projects and +groups, and start remediation processes when needed. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview of application security with GitLab, see +[Security Deep Dive](https://www.youtube.com/watch?v=k4vEJnGYy84). ## Security scanning tools GitLab can scan and report any vulnerabilities found in your project. -| Secure scanning tools | Description | +| Secure scanning tool | Description | |:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------| -| [Container Scanning](container_scanning/index.md) **[ULTIMATE]** | Scan Docker containers for 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. | -| [License Management](license_management/index.md) **[ULTIMATE]** | Search your project's dependencies for their licenses. | -| [Security Dashboard](security_dashboard/index.md) **[ULTIMATE]** | View vulnerabilities in all your projects and groups. | -| [Static Application Security Testing (SAST)](sast/index.md) **[ULTIMATE]** | Analyze source code for known vulnerabilities. | +| [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. | +| [License Management](license_management/index.md) **(ULTIMATE)** | Search your project's dependencies for their licenses. | +| [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | +| [Static Application Security Testing (SAST)](sast/index.md) **(ULTIMATE)** | Analyze source code for known vulnerabilities. | + +## Maintenance and update of the vulnerabilities database + +The various scanning tools and the vulnerabilities database are updated regularly. + +| Secure scanning tool | Vulnerabilities database updates | +|:-------------------------------------------------------------|-------------------------------------------| +| [Container Scanning](container_scanning/index.md) | Uses `clair` underneath and the latest `clair-db` version is used for each job run by running the [`latest` docker image tag](https://gitlab.com/gitlab-org/gitlab-ee/blob/438a0a56dc0882f22bdd82e700554525f552d91b/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L37). The `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | +| [Dependency Scanning](dependency_scanning/index.md) | Relies on `bundler-audit` (for Rubygems), `retire.js` (for NPM packages) and `gemnasium` (GitLab's own tool for all libraries). `bundler-audit` and `retire.js` both 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. | +| [Dynamic Application Security Testing (DAST)](dast/index.md) | Updated weekly on Sundays. The underlying tool, `zaproxy`, downloads fresh rules at startup. | +| [Static Application Security Testing (SAST)](sast/index.md) | Relies exclusively on [the tools GitLab is wrapping](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 don't have to update GitLab to benefit from the latest vulnerabilities definitions, +but you may have to in the future. + +The security tools are released as Docker images, and the vendored job definitions +to enable them are using the `x-y-stable` image tags that get overridden each time a new +release of the tools is pushed. The Docker images are updated to match the +previous GitLab releases, so they automatically get the latest versions of the +scanning tools without the user having to do anything. + +This workflow comes with some drawbacks and there's a +[plan to change this](https://gitlab.com/gitlab-org/gitlab-ee/issues/9725). ## Interacting with the vulnerabilities @@ -31,7 +67,7 @@ Each security vulnerability in the merge request report or the entry, a detailed information will pop up with different possible options: - [Dismiss vulnerability](#dismissing-a-vulnerability): Dismissing a vulnerability - will place a <s>strikethrough</s> styling on it. + will place a ~~strikethrough~~ styling on it. - [Create issue](#creating-an-issue-for-a-vulnerability): The new issue will have the title and description pre-populated with the information from the vulnerability report and will be created as [confidential](../project/issues/confidential_issues.md) by default. @@ -92,16 +128,16 @@ generated by GitLab. To apply the fix: 1. Click on the vulnerability. 1. Download and review the patch file `remediation.patch`. -2. Ensure your local project has the same commit checked out that was used to generate the patch. -3. Run `git apply remediation.patch`. -4. Verify and commit the changes to your branch. +1. Ensure your local project has the same commit checked out that was used to generate the patch. +1. Run `git apply remediation.patch`. +1. Verify and commit the changes to your branch.  #### Creating a merge request from a vulnerability > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9224) in - [GitLab Ultimate](https://about.gitlab.com/pricing) 11.9. +> [GitLab Ultimate](https://about.gitlab.com/pricing) 11.9. In certain cases, GitLab will allow you to create a merge request that will automatically remediate the vulnerability. Any vulnerability that has a @@ -112,3 +148,47 @@ If this action is available there will be a **Create merge request** button in t Clicking on this button will create a merge request to apply the solution onto the source branch.  + +## Security approvals in merge requests **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing) 12.2. + +Merge Request Approvals can be configured to require approval from a member +of your security team when a vulnerability would be introduced by a merge request. + +This threshold is defined as `high`, `critical`, or `unknown` +severity. When any vulnerabilities are present within a merge request, an +approval will be required from the `Vulnerability-Check` approver group. + +### Enabling Security Approvals within a project + +To enable Security Approvals, a [project approval rule](../project/merge_requests/merge_request_approvals.md#multiple-approval-rules-premium) +must be created with the case-sensitive name `Vulnerability-Check`. This approval +group must be set with an "Approvals required" count greater than zero. + +Once this group has been added to your project, the approval rule will be enabled +for all Merge Requests. + +Any code changes made will cause the count of approvals required to reset. + +An approval will be required when a security report: + +- Contains a new vulnerability of `high`, `critical`, or `unknown` severity. +- Is not generated during pipeline execution. + +An approval will be optional when a security report: + +- Contains no new vulnerabilities. +- Contains only new vulnerabilities of `low` or `medium` severity. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/license_management/img/license_management_add_license.png b/doc/user/application_security/license_management/img/license_management_add_license.png Binary files differnew file mode 100644 index 00000000000..c9a5dc14c57 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management_add_license.png diff --git a/doc/user/application_security/license_management/img/license_management_decision.png b/doc/user/application_security/license_management/img/license_management_decision.png Binary files differindex 0763130c375..fbf90bec7fd 100644 --- a/doc/user/application_security/license_management/img/license_management_decision.png +++ b/doc/user/application_security/license_management/img/license_management_decision.png diff --git a/doc/user/application_security/license_management/img/license_management_search.png b/doc/user/application_security/license_management/img/license_management_search.png Binary files differnew file mode 100644 index 00000000000..b3ffd8d95a1 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management_search.png diff --git a/doc/user/application_security/license_management/img/license_management_settings.png b/doc/user/application_security/license_management/img/license_management_settings.png Binary files differindex b5490e59074..2e3e8888e93 100644 --- a/doc/user/application_security/license_management/img/license_management_settings.png +++ b/doc/user/application_security/license_management/img/license_management_settings.png diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md index 7878dc77084..c324848c703 100644 --- a/doc/user/application_security/license_management/index.md +++ b/doc/user/application_security/license_management/index.md @@ -1,4 +1,8 @@ -# License Management **[ULTIMATE]** +--- +type: reference, howto +--- + +# License Management **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. @@ -8,7 +12,7 @@ in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. If you are using [GitLab CI/CD](../../../ci/README.md), you can search your project dependencies for their licenses using License Management. -You can take advantage of License Management by either [including the job](#configuring-license-management) +You can take advantage of License Management by either [including the job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using [Auto License Management](../../../topics/autodevops/index.md#auto-license-management-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -44,44 +48,37 @@ library whose license is incompatible with yours. The following languages and package managers are supported. -| Language | Package managers | -|------------|-------------------------------------------------------------------| -| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) | -| Go | [Godep](https://github.com/tools/godep), go get | -| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | -| .NET | [Nuget](https://www.nuget.org/) | -| Python | [pip](https://pip.pypa.io/en/stable/) | -| Ruby | [gem](https://rubygems.org/) | +| Language | Package managers | Scan Tool | +|------------|-------------------------------------------------------------------|----------------------------------------------------------| +| JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Go | [Godep](https://github.com/tools/godep), go get ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), gvt ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), glide ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), dep ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), trash ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) and govendor ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)), [go mod](https://github.com/golang/go/wiki/Modules) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| .NET | [Nuget](https://www.nuget.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Python | [pip](https://pip.pypa.io/en/stable/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Ruby | [gem](https://rubygems.org/) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Erlang | [rebar](https://www.rebar3.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Objective-C, Swift | [Carthage](https://github.com/Carthage/Carthage) , [CocoaPods v0.39 and below](https://cocoapods.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| Elixir | [mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types)) |[License Finder](https://github.com/pivotal/LicenseFinder)| +| C++/C | [conan](https://conan.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Scala | [sbt](https://www.scala-sbt.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| Rust | [cargo](https://crates.io/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| +| PHP | [composer](https://getcomposer.org/) ([experimental support](https://github.com/pivotal/LicenseFinder#experimental-project-types))|[License Finder](https://github.com/pivotal/LicenseFinder)| ## Requirements To run a License Management scanning job, you need GitLab Runner with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). -## Configuring License Management - -To enable License Management in your project, define a job in your `.gitlab-ci.yml` -file that generates the [License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate). - -This can be done in two ways: - -- For GitLab 11.9 and later, including the provided `License-Management.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. +## Configuration -### Including the provided template +For GitLab 11.9 and later, to enable License Management, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/License-Management.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 +that template. -NOTE: **Note:** -The CI/CD License Management template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). - -A CI/CD [License Management template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml) -with the default License Management job definition is provided as a part of your GitLab -installation which you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. - -To enable License Management using the provided template, add the following to -your `.gitlab-ci.yml` file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -91,14 +88,17 @@ include: The included template will create a `license_management` job in your CI/CD pipeline and scan your dependencies to find their licenses. -The report will be saved as a +The results will be saved as a [License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest License Management artifact available. Behind the scenes, the [GitLab License Management Docker image](https://gitlab.com/gitlab-org/security-products/license-management) is used to detect the languages/frameworks and in turn analyzes the licenses. -#### Installing custom dependencies +The License Management settings can be changed through environment variables by using the +[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. These variables are documented in the [License Management documentation](https://gitlab.com/gitlab-org/security-products/license-management#settings). + +### Installing custom dependencies > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. @@ -126,7 +126,7 @@ variables: In this example, `my-custom-install-script.sh` is a shell script at the root directory of your project. -#### Overriding the template +### Overriding the template If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare a `license_management` job @@ -141,7 +141,7 @@ license_management: CI_DEBUG_TRACE: "true" ``` -#### Configuring Maven projects +### Configuring Maven projects The License Management tool provides a `MAVEN_CLI_OPTS` environment variable which can hold the command line arguments to pass to the `mvn install` command which is executed under the hood. @@ -165,65 +165,21 @@ to explicitly add `-DskipTests` to your options. If you still need to run tests during `mvn install`, add `-DskipTests=false` to `MAVEN_CLI_OPTS`. -### Manual job definition for GitLab 11.5 and later +### Selecting the version of Python -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `license_management` -job can be added: +> [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -```yaml -license_management: - image: - name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable" - entrypoint: [""] - stage: test - allow_failure: true - script: - - /run.sh analyze . - artifacts: - reports: - license_management: gl-license-management-report.json -``` - -If you want to install custom project dependencies via the `SETUP_CMD` variable: +License Management uses Python 2.7 and pip 10.0 by default. +If your project requires Python 3, you can switch to Python 3.5 and pip 19.1 +by setting the `LM_PYTHON_VERSION` environment variable to `3`. ```yaml -license_management: - image: - name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable" - entrypoint: [""] - stage: test - variables: - SETUP_CMD: ./my-custom-install-script.sh - allow_failure: true - script: - - /run.sh analyze . - artifacts: - reports: - license_management: gl-license-management-report.json -``` - -### Manual job definition for GitLab 11.4 and earlier (deprecated) - -CAUTION: **Caution:** -Before GitLab 11.5, the License Management job and artifact had to be named specifically -to automatically extract the report data and show it in the merge request widget. -While these old job definitions are still maintained, they have been deprecated -and may be removed in the next major release, GitLab 12.0. You are strongly advised -to update your current `.gitlab-ci.yml` configuration to reflect that change. - -For GitLab 11.4 and earlier, the job should look like: +include: + template: License-Management.gitlab-ci.yml -```yaml license_management: - image: - name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable" - entrypoint: [""] - stage: test - allow_failure: true - script: - - /run.sh analyze . - artifacts: - paths: [gl-license-management-report.json] + variables: + LM_PYTHON_VERSION: 3 ``` ## Project policies for License Management @@ -242,16 +198,29 @@ To approve or blacklist a license: navigate to the project's **Settings > CI/CD** and expand the **License Management** section. 1. Click the **Add a license** button. + +  + 1. In the **License name** dropdown, either: - - Select one of the available licenses. You can search for licenses in the field - at the top of the list. - - Enter arbitrary text in the field at the top of the list. This will cause the text to be - added as a license name to the list. + - Select one of the available licenses. You can search for licenses in the field + at the top of the list. + - Enter arbitrary text in the field at the top of the list. This will cause the text to be + added as a license name to the list. 1. Select the **Approve** or **Blacklist** radio button to approve or blacklist respectively the selected license. +To modify an existing license: + +1. In the **License Management** list, click the **Approved/Declined** dropdown to change it to the desired status. +  +Searching for Licenses: + +1. Use the **Search** box to search for a specific license. + +  + ## License Management report under pipelines > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491) @@ -262,3 +231,15 @@ pipeline ID that has a `license_management` job to see the Licenses tab with the licenses (if any).  + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md new file mode 100644 index 00000000000..f730a25a9fc --- /dev/null +++ b/doc/user/application_security/sast/analyzers.md @@ -0,0 +1,144 @@ +--- +table_display_block: true +--- + +# SAST Analyzers **(ULTIMATE)** + +SAST relies on underlying third party tools that are wrapped into what we call +"Analyzers". An analyzer is a +[dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers) +that wraps a particular tool to: + +- Expose its detection logic. +- Handle its execution. +- Convert its output to the common format. + +This is achieved by implementing the [common API](https://gitlab.com/gitlab-org/security-products/analyzers/common). + +SAST supports the following official analyzers: + +- [`bandit`](https://gitlab.com/gitlab-org/security-products/analyzers/bandit) (Bandit) +- [`brakeman`](https://gitlab.com/gitlab-org/security-products/analyzers/brakeman) (Brakeman) +- [`eslint`](https://gitlab.com/gitlab-org/security-products/analyzers/eslint) (ESLint (Javascript)) +- [`flawfinder`](https://gitlab.com/gitlab-org/security-products/analyzers/flawfinder) (Flawfinder) +- [`gosec`](https://gitlab.com/gitlab-org/security-products/analyzers/gosec) (Gosec) +- [`nodejs-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/nodejs-scan) (NodeJsScan) +- [`phpcs-security-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/phpcs-security-audit) (PHP CS security-audit) +- [`pmd-apex`](https://gitlab.com/gitlab-org/security-products/analyzers/pmd-apex) (PMD (Apex only)) +- [`secrets`](https://gitlab.com/gitlab-org/security-products/analyzers/secrets) (Secrets (Gitleaks, TruffleHog & Diffence secret detectors)) +- [`security-code-scan`](https://gitlab.com/gitlab-org/security-products/analyzers/security-code-scan) (Security Code Scan (.NET)) +- [`sobelow`](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow) (Sobelow (Elixir Phoenix)) +- [`spotbugs`](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) (SpotBugs with the Find Sec Bugs plugin (Ant, Gradle and wrapper, Grails, Maven and wrapper, SBT)) +- [`tslint`](https://gitlab.com/gitlab-org/security-products/analyzers/tslint) (TSLint (Typescript)) + +The analyzers are published as Docker images that SAST will use to launch +dedicated containers for each analysis. + +SAST is pre-configured with a set of **default images** that are maintained by +GitLab, but users can also integrate their own **custom images**. + +## Official default analyzers + +Any custom change to the official analyzers can be achieved by using an +[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-sast-settings). + +### Using a custom Docker mirror + +You can switch to a custom Docker registry that provides the official analyzer +images under a different prefix. For instance, the following instructs +SAST to pull `my-docker-registry/gl-images/bandit` +instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/bandit`. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_ANALYZER_IMAGE_PREFIX: my-docker-registry/gl-images +``` + +This configuration requires that your custom registry provides images for all +the official analyzers. + +### Selecting specific analyzers + +You can select the official analyzers you want to run. Here's how to enable +`bandit` and `flawfinder` while disabling all the other default ones. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_DEFAULT_ANALYZERS: "bandit,flawfinder" +``` + +`bandit` runs first. When merging the reports, SAST will +remove the duplicates and will keep the `bandit` entries. + +### Disabling default analyzers + +Setting `SAST_DEFAULT_ANALYZERS` to an empty string will disable all the official +default analyzers. In `.gitlab-ci.yml` define: + +```yaml +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_DEFAULT_ANALYZERS: "" +``` + +That's needed when one totally relies on [custom analyzers](#custom-analyzers). + +## Custom Analyzers + +You can provide your own analyzers as a comma separated list of Docker images. +Here's how to add `analyzers/csharp` and `analyzers/perl` to the default images: +In `.gitlab-ci.yml` define: + +```yaml +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_ANALYZER_IMAGES: "my-docker-registry/analyzers/csharp,amy-docker-registry/analyzers/perl" +``` + +The values must be the full path to the container registry images, +like what you would feed to the `docker pull` command. + +NOTE: **Note:** +This configuration doesn't benefit from the integrated detection step. +SAST has to fetch and spawn each Docker image to establish whether the +custom analyzer can scan the source code. + +## Analyzers Data + +| Property \ Tool | Apex | Bandit | Brakeman | ESLint security | Find Sec Bugs | Flawfinder | Go AST Scanner | NodeJsScan | Php CS Security Audit | Security code Scan (.NET) | TSLint Security | Sobelow | +| --------------------------------------- | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :------------------: | :---------------------: | :-------------------------: | :-------------: | :----------------: | +| Severity | โ | โ | ๐ | ๐ | โ | ๐ | โ | ๐ | โ | ๐ | โ | ๐ | +| Title | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Description | โ | ๐ | ๐ | โ | โ | ๐ | ๐ | โ | ๐ | ๐ | โ | โ | +| File | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| Start line | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | โ | +| End line | โ | โ | ๐ | โ | โ | ๐ | ๐ | ๐ | ๐ | ๐ | โ | ๐ | +| Start column | โ | ๐ | ๐ | โ | โ | โ | โ | ๐ | โ | โ | โ | ๐ | +| End column | โ | ๐ | ๐ | โ | โ | ๐ | ๐ | ๐ | ๐ | ๐ | โ | ๐ | +| External id (e.g. CVE) | ๐ | ๐ | โ | ๐ | โ | โ | ๐ | ๐ | ๐ | ๐ | ๐ | ๐ | +| URLs | โ | ๐ | โ | ๐ | โ | ๐ | ๐ | ๐ | ๐ | ๐ | ๐ | ๐ | +| Internal doc/explanation | โ | โ | โ | ๐ | โ | ๐ | ๐ | ๐ | ๐ | ๐ | ๐ | โ | +| Solution | โ | ๐ | ๐ | ๐ | โ | โ | ๐ | ๐ | ๐ | ๐ | ๐ | ๐ | +| Confidence | ๐ | โ | โ | ๐ | โ | โ | โ | ๐ | ๐ | ๐ | ๐ | โ | +| Affected item (e.g. class or package) | โ | ๐ | โ | ๐ | โ | โ | ๐ | ๐ | ๐ | ๐ | ๐ | ๐ | +| Source code extract | ๐ | โ | โ | โ | ๐ | โ | โ | ๐ | ๐ | ๐ | ๐ | ๐ | +| Internal ID | โ | โ | โ | โ | โ | โ | โ | ๐ | โ | โ | โ | โ | + +- โ => we have that data +- โ => we have that data but it's partially reliable, or we need to extract it from unstructured content +- ๐ => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. + +The values provided by these tools are heterogeneous so they are sometimes +normalized into common values (e.g., `severity`, `confidence`, etc). diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 11361f8ad89..2f15d997b5b 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,4 +1,8 @@ -# Static Application Security Testing (SAST) **[ULTIMATE]** +--- +type: reference, howto +--- + +# Static Application Security Testing (SAST) **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. @@ -13,7 +17,7 @@ to learn how to protect your organization. If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known vulnerabilities using Static Application Security Testing (SAST). -You can take advantage of SAST by either [including the CI job](#configuring-sast) in +You can take advantage of SAST by either [including the CI job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using [Auto SAST](../../../topics/autodevops/index.md#auto-sast-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -55,6 +59,7 @@ The following table shows which languages, package managers and frameworks are s |-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------| | .NET | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | | Any | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11.9 | +| Apex (Salesforce) | [pmd](https://pmd.github.io/pmd/index.html) | 12.1 | | C/C++ | [Flawfinder](https://www.dwheeler.com/flawfinder/) | 10.7 | | Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10 | | Go | [Gosec](https://github.com/securego/gosec) | 10.7 | @@ -73,30 +78,16 @@ The Java analyzers can also be used for variants like the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), [Grails](https://grails.org/) and the [Maven wrapper](https://github.com/takari/maven-wrapper). -## Configuring SAST - -To enable SAST in your project, define a job in your `.gitlab-ci.yml` file that generates the -[SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast-ultimate). - -This can be done in two ways: - -- For GitLab 11.9 and later, including the provided `SAST.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. - -### Including the provided template - -NOTE: **Note:** -The CI/CD SAST template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). +## Configuration -A CI/CD [SAST template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) -with the default SAST job definition is provided as a part of your GitLab -installation which you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. +For GitLab 11.9 and later, to enable SAST, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/SAST.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 +that template. -To enable SAST using the provided template, add the following to your `.gitlab-ci.yml` -file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -106,14 +97,14 @@ include: The included template will create a `sast` job in your CI/CD pipeline and scan your project's source code for possible vulnerabilities. -The report will be saved as a +The results will be saved as a [SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. Behind the scenes, the [GitLab SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) is used to detect the languages/frameworks and in turn runs the matching scan tools. -#### Customizing the SAST settings +### Customizing the SAST settings The SAST settings can be changed through environment variables by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. @@ -134,7 +125,7 @@ variables: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable will take precedence. -#### Overriding the SAST template +### Overriding the SAST template If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare a `sast` job after the @@ -149,84 +140,64 @@ sast: CI_DEBUG_TRACE: "true" ``` -### Manual job definition for GitLab 11.5 and later +### Available variables -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `sast` -job can be added: +SAST can be [configured](#customizing-the-sast-settings) using environment variables. -```yaml -sast: - stage: test - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} - - | - docker run \ - --env SAST_ANALYZER_IMAGES \ - --env SAST_ANALYZER_IMAGE_PREFIX \ - --env SAST_ANALYZER_IMAGE_TAG \ - --env SAST_DEFAULT_ANALYZERS \ - --env SAST_EXCLUDED_PATHS \ - --env SAST_BANDIT_EXCLUDED_PATHS \ - --env SAST_BRAKEMAN_LEVEL \ - --env SAST_GOSEC_LEVEL \ - --env SAST_FLAWFINDER_LEVEL \ - --env SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \ - --env SAST_PULL_ANALYZER_IMAGE_TIMEOUT \ - --env SAST_RUN_ANALYZER_TIMEOUT \ - --volume "$PWD:/code" \ - --volume /var/run/docker.sock:/var/run/docker.sock \ - "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code - dependencies: [] - artifacts: - reports: - sast: gl-sast-report.json -``` +#### Docker images -You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/sast#settings) -via `docker run --env` to customize your job execution. +The following are Docker image-related variables. -### Manual job definition for GitLab 11.4 and earlier (deprecated) +| Environment variable | Description | +|-------------------------------|--------------------------------------------------------------------------------| +| `SAST_ANALYZER_IMAGES` | Comma separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). | +| `SAST_ANALYZER_IMAGE_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | +| `SAST_ANALYZER_IMAGE_TAG` | Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | +| `SAST_DEFAULT_ANALYZERS` | Override the names of default images. Read more about [customizing analyzers](analyzers.md). | +| `SAST_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). | -CAUTION: **Deprecated:** -Before GitLab 11.5, the SAST job and artifact had to be named specifically -to automatically extract report data and show it in the merge request widget. -While these old job definitions are still maintained, they have been deprecated -and may be removed in the next major release, GitLab 12.0. You are strongly -advised to update your current `.gitlab-ci.yml` configuration to reflect that change. +### Vulnerability filters -For GitLab 11.4 and earlier, the SAST job should look like: +Some analyzers make it possible to filter out vulnerabilities under a given threshold. -```yaml -sast: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} - - docker run - --env SAST_CONFIDENCE_LEVEL="${SAST_CONFIDENCE_LEVEL:-3}" - --volume "$PWD:/code" - --volume /var/run/docker.sock:/var/run/docker.sock - "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code - artifacts: - paths: [gl-sast-report.json] -``` +| `SAST_BANDIT_EXCLUDED_PATHS` | - | comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html) | +| `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | +| `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | +| `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. | +| `SAST_GOSEC_LEVEL` | 0 | Ignore gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | +| `SAST_EXCLUDED_PATHS` | - | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. | + +### Timeouts + +The following variables configure timeouts. + +| `SAST_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", "h". For example, "300ms", "1.5h" or "2h45m". | +| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "ยตs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m". | +| `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are "ns", "us" (or "ยตs"), "ms", "s", "m", "h". For example, "300ms", "1.5h" or "2h45m".| + +### Analyzer settings + +Some analyzers can be customized with environment variables. + +| Environment variable | Analyzer | Description | +|-------------------------|----------|----------| +| `ANT_HOME` | spotbugs | The `ANT_HOME` environment variable. | +| `ANT_PATH` | spotbugs | Path to the `ant` executable. | +| `GRADLE_PATH` | spotbugs | Path to the `gradle` executable. | +| `JAVA_OPTS` | spotbugs | Additional arguments for the `java` executable. | +| `JAVA_PATH` | spotbugs | Path to the `java` executable. | +| `MAVEN_CLI_OPTS` | spotbugs | Additional arguments for the `mvn` or `mvnw` executable. | +| `MAVEN_PATH` | spotbugs | Path to the `mvn` executable. | +| `MAVEN_REPO_PATH` | spotbugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). | +| `SBT_PATH` | spotbugs | Path to the `sbt` executable. | +| `FAIL_NEVER` | spotbugs | Set to `1` to ignore compilation failure. | ## Reports JSON format CAUTION: **Caution:** The JSON report artifacts are not a public API of SAST and their format may change in the future. -The SAST tool emits a JSON report report file. Here is an example of a structure for a report will all important parts of +The SAST tool emits a JSON report report file. Here is an example of the report structure with all important parts of it highlighted: ```json-doc @@ -269,10 +240,9 @@ it highlighted: "url": "https://cwe.mitre.org/data/definitions/330.html" } ] - }, + }, { "category": "sast", - // "name" may be omitted because it could be not reported by a particular analyzer "message": "Probable insecure usage of temp file/directory.", "cve": "python/hardcoded/hardcoded-tmp.py:4ad6d4c40a8c263fc265f3384724014e0a4f8dd6200af83e51ff120420038031:B108", "severity": "Medium", @@ -297,7 +267,7 @@ it highlighted: "url": "https://docs.openstack.org/bandit/latest/plugins/b108_hardcoded_tmp_directory.html" } ] - }, + }, ], "remediations": [] } @@ -318,10 +288,10 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].severity` | How much the vulnerability impacts the software. Possible values: `Undefined` (an analyzer has not provided this info), `Info`, `Unknown`, `Low`, `Medium`, `High`, `Critical`. | | `vulnerabilities[].confidence` | How reliable the vulnerability's assessment is. Possible values: `Undefined` (an analyzer has not provided this info), `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 find this vulnerability. | +| `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.name` | Name of the scanner, for display purposes. | -| `vulnerabilities[].location` | A node that tells which class and/or method is affected by the vulnerability. | +| `vulnerabilities[].location` | A node that tells where the vulnerability is located. | | `vulnerabilities[].location.file` | Path to the file where the vulnerability is located. Optional. | | `vulnerabilities[].location.start_line` | The first line of the code affected by the vulnerability. Optional. | | `vulnerabilities[].location.end_line` | The last line of the code affected by the vulnerability. Optional. | @@ -331,7 +301,7 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].identifiers[].type` | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`) or analyzer-dependent ones (e.g., `bandit_test_id` for [Bandit analyzer](https://wiki.openstack.org/wiki/Security/Projects/Bandit)). | | `vulnerabilities[].identifiers[].name` | Name of the identifier for display purposes. | | `vulnerabilities[].identifiers[].value` | Value of the identifier for matching purposes. | -| `vulnerabilities[].identifiers[].url` | URL to identifier's documentation. Optional. | +| `vulnerabilities[].identifiers[].url` | URL to identifier's documentation. Optional. | ## Secret detection @@ -364,3 +334,20 @@ vulnerabilities in your groups and projects. Read more about the Once a vulnerability is found, you can interact with it. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). + +## Vulnerabilities database update + +For more information about the vulnerabilities database update, check the +[maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/application_security/security_dashboard/img/dashboard.png b/doc/user/application_security/security_dashboard/img/dashboard.png Binary files differdeleted file mode 100644 index a75168b1ce4..00000000000 --- a/doc/user/application_security/security_dashboard/img/dashboard.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard.png Binary files differnew file mode 100644 index 00000000000..85ab124f74c --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard.png diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png Binary files differindex f0dad6c54d0..baa136fd885 100644 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 19eeb06a259..ac8c1ac0354 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -1,4 +1,8 @@ -# GitLab Security Dashboard **[ULTIMATE]** +--- +type: reference, howto +--- + +# GitLab Security Dashboard **(ULTIMATE)** The Security Dashboard is a good place to get an overview of all the security vulnerabilities in your groups and projects. @@ -16,9 +20,9 @@ To benefit from the Security Dashboard you must first configure one of the The Security Dashboard supports the following reports: - [Container Scanning](../container_scanning/index.md) -- [DAST](../dast/index.md) +- [Dynamic Application Security Testing](../dast/index.md) - [Dependency Scanning](../dependency_scanning/index.md) -- [SAST](../sast/index.md) +- [Static Application Security Testing](../sast/index.md) ## Requirements @@ -26,8 +30,8 @@ To use the project or group security dashboard: 1. At least one project inside a group must be configured with at least one of the [supported reports](#supported-reports). -2. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports). -3. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used. +1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports). +1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used. If you're using the shared Runners on GitLab.com, this is already the case. ## Project Security Dashboard @@ -43,13 +47,13 @@ for your project. Use it to find and fix vulnerabilities affecting the ## Group Security Dashboard > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6709) in - [GitLab Ultimate](https://about.gitlab.com/pricing) 11.5. +> [GitLab Ultimate](https://about.gitlab.com/pricing) 11.5. The group Security Dashboard gives an overview of the vulnerabilities of all the projects in a group and its subgroups. First, navigate to the Security Dashboard found under your group's -**Overview > Security Dashboard**. +**Security** tab. Once you're on the dashboard, at the top you should see a series of filters for: @@ -58,7 +62,7 @@ Once you're on the dashboard, at the top you should see a series of filters for: - Report type - Project - + Selecting one or more filters will filter the results in this page. The first section is an overview of all the vulnerabilities, grouped by severity. @@ -102,3 +106,15 @@ That way, reports are created even if no code change happens. When using [Auto DevOps](../../../topics/autodevops/index.md), use [special environment variables](../../../topics/autodevops/index.md#environment-variables) to configure daily security scans. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> |
