diff options
Diffstat (limited to 'doc/user/application_security')
21 files changed, 579 insertions, 578 deletions
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 696446599c8..7b631a5a1cd 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Container Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672) @@ -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). @@ -47,7 +51,7 @@ To enable Container Scanning in your pipeline, you need: 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 ``` @@ -55,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: +## Configuration -- 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. +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. -### 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). - -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. - -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: @@ -89,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 @@ -106,95 +94,36 @@ 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). +## Example -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `container_scanning` -job can be added: +The following is a sample `.gitlab-ci.yml` that will build your Docker Image, push it to the container registry and run Container Scanning. ```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 -``` +variables: + DOCKER_DRIVER: overlay2 -### Manual job definition for GitLab 11.4 and earlier (deprecated) +services: + - docker:stable-dind -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. +stages: + - build + - test -For GitLab 11.4 and earlier, the Container Scanning job should look like: +include: + - template: Container-Scanning.gitlab-ci.yml -```yaml -container_scanning: +build: image: docker:stable + stage: build 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 + IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA 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] + - docker info + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker build -t $IMAGE . + - docker push $IMAGE ``` -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 @@ -219,11 +148,11 @@ 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"). +[issue #10241](https://gitlab.com/gitlab-org/gitlab-ee/issues/10241 "Investigate why Container Scanning is not working with NFS mounts").
\ No newline at end of file diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 936703cce32..fa84f995e58 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -1,8 +1,17 @@ +--- +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 @@ -264,3 +208,15 @@ Once a vulnerability is found, you can interact with it. Read more on how to 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/index.md b/doc/user/application_security/dependency_scanning/index.md index 2fe8a6f9029..b40392e12d5 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Dependency Scanning **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105) @@ -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). @@ -48,14 +52,15 @@ The following languages and dependency managers are supported. | 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) | -| Java ([Maven](https://maven.apache.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| PHP ([Composer](https://getcomposer.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | -| Python ([poetry](https://poetry.eustace.io/)) | no ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/7006 "Support Poetry in Dependency Scanning")) | not available | -| Python ([Pipfile](https://docs.pipenv.org/en/latest/basics/)) | no ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/11756 "Pipfile.lock support for Dependency Scanning"))| not available | -| Go ([Golang](https://golang.org/)) | no ([issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/7132 "Dependency Scanning for Go")) | not available | ## Remote checks @@ -74,31 +79,16 @@ The Gemnasium client does **NOT** send the exact package versions your project r 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`. -## Configuring Dependency Scanning - -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). - -This can be done in two ways: - -- 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. +## Configuration -### Including the provided template +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. -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). - -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. - -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: @@ -108,12 +98,12 @@ 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. -#### Customizing the Dependency Scanning settings +### Customizing the Dependency Scanning settings 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`. @@ -131,7 +121,7 @@ variables: 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 @@ -146,99 +136,27 @@ dependency_scanning: CI_DEBUG_TRACE: "true" ``` -#### Available variables +### 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_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`. | - -### 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](#available-variables) -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] -``` +| Environment variable | Description | Example usage | +|-------------------------------- |-------------| | +| `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_EXCLUDED_PATHS=doc,spec` | +| `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 @@ -358,8 +276,8 @@ it highlighted: Here is the description of the report file structure nodes and their meaning. All fields are mandatory to be present in the report JSON unless stated otherwise. Presence of optional fields depends on the underlying analyzers being used. -| Report JSON node | Function | -|------------------------------------------------------|----------| +| Report JSON node | Description | +|------------------------------------------------------|-------------| | `version` | Report syntax version used to generate this JSON. | | `vulnerabilities` | Array of vulnerability objects. | | `vulnerabilities[].category` | Where this vulnerability belongs (SAST, Dependency Scanning etc.). For Dependency Scanning, it will always be `dependency_scanning`. | @@ -409,16 +327,11 @@ Once a vulnerability is found, you can interact with it. Read more on how to For more information about the vulnerabilities database update, check the [maintenance table](../index.md#maintenance-and-update-of-the-vulnerabilities-database). -## Dependency List - -> [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. This list can be generated only for -[languages and package managers](#supported-languages-and-package-managers) -supported by Gemnasium. - -To see the generated dependency list, navigate to your project's **Project > Dependency List**. +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). ## Versioning and release process @@ -429,3 +342,15 @@ Please check the [Release Process documentation](https://gitlab.com/gitlab-org/s 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). + +<!-- ## 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 91e79f6c23b..fcd683ca2db 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,10 +1,22 @@ +--- +type: reference, howto +--- + # 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. +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 @@ -13,9 +25,10 @@ GitLab can scan and report any vulnerabilities found in your project. | Secure scanning tool | Description | |:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------| | [Container Scanning](container_scanning/index.md) **(ULTIMATE)** | Scan Docker containers for known vulnerabilities. | +| [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | | [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | -| [License Management](license_management/index.md) **(ULTIMATE)** | Search your project's dependencies for their licenses. | +| [License Compliance](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. | @@ -54,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. @@ -115,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 @@ -135,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 differindex 1e1a698515b..c9a5dc14c57 100644 --- 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 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 differindex 7b6006cef9d..b3ffd8d95a1 100644 --- a/doc/user/application_security/license_management/img/license_management_search.png +++ 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 1a2bfa78a03..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 8eb231f8359..44b2671930e 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 Compliance **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. @@ -6,18 +10,18 @@ in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. ## Overview If you are using [GitLab CI/CD](../../../ci/README.md), you can search your project dependencies for their licenses -using License Management. +using License Compliance. -You can take advantage of License Management by either [including the job](#configuring-license-management) +You can take advantage of License Compliance 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) +[Auto License Compliance](../../../topics/autodevops/index.md#auto-license-compliance-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). -GitLab checks the License Management report, compares the licenses between the +GitLab checks the License Compliance report, compares the licenses between the source and target branches, and shows the information right on the merge request. Blacklisted licenses will be clearly visible with an `x` red icon next to them as well as new licenses which need a decision from you. In addition, you can -[manually approve or blacklist](#project-policies-for-license-management) +[manually approve or blacklist](#project-policies-for-license-compliance) licenses in your project's settings. NOTE: **Note:** @@ -27,7 +31,7 @@ will be displayed in the merge request area. That is the case when you add the Consecutive merge requests will have something to compare to and the license management report will be shown properly. - + If you are a project or group Maintainer, you can click on a license to be given the choice to approve it or blacklist it. @@ -62,36 +66,19 @@ The following languages and package managers are supported. ## Requirements -To run a License Management scanning job, you need GitLab Runner with the +To run a License Compliance 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: +## Configuration -- 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. +For GitLab 11.9 and later, to enable License Compliance, 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. -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). - -### Including the provided 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: @@ -101,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 -[License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate) +The results will be saved as a +[License Compliance 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) +always take the latest License Compliance artifact available. Behind the scenes, the +[GitLab License Compliance 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 Compliance 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 Compliance 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. @@ -136,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 @@ -151,9 +141,9 @@ 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 License Compliance 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. Feel free to use it for the customization of Maven execution. For example: @@ -179,9 +169,9 @@ If you still need to run tests during `mvn install`, add `-DskipTests=false` to > [Introduced](https://gitlab.com/gitlab-org/security-products/license-management/merge_requests/36) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -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`. +License Compliance uses Python 3.5 and pip 19.1 by default. +If your project requires Python 2, you can switch to Python 2.7 and pip 10.0 +by setting the `LM_PYTHON_VERSION` environment variable to `2`. ```yaml include: @@ -189,71 +179,10 @@ include: license_management: variables: - LM_PYTHON_VERSION: 3 -``` - -### Manual job definition for GitLab 11.5 and later - -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `license_management` -job can be added: - -```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: - -```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: - -```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] + LM_PYTHON_VERSION: 2 ``` -## Project policies for License Management +## Project policies for License Compliance > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5940) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. @@ -267,35 +196,32 @@ To approve or blacklist a license: 1. Either use the **Manage licenses** button in the merge request widget, or navigate to the project's **Settings > CI/CD** and expand the - **License Management** section. + **License Compliance** 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. +1. In the **License Compliance** 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 +## License Compliance report under pipelines > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2. @@ -304,4 +230,16 @@ From your project's left sidebar, navigate to **CI/CD > Pipelines** and click on pipeline ID that has a `license_management` job to see the Licenses tab with the listed 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..a1bd00f34e3 --- /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 84b45cbe6e6..3eead6ccd3f 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Static Application Security Testing (SAST) **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3775) @@ -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,77 +140,61 @@ 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] -``` +| Environment variable | Default value | Description | Example usage | +|----------------------|---------------|-------------|---| +| `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. | `SAST_EXCLUDED_PATHS=doc,spec` | + +### Timeouts + +The following variables configure timeouts. + +| Environment variable | Default value | Description | +|----------------------|---------------|-------------| +| `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 @@ -368,3 +343,15 @@ Once a vulnerability is found, you can interact with it. Read more on how to 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 3b01fe66e03..ac8c1ac0354 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # GitLab Security Dashboard **(ULTIMATE)** The Security Dashboard is a good place to get an overview of all the security @@ -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. --> |
