diff options
Diffstat (limited to 'doc/user/application_security')
23 files changed, 1411 insertions, 0 deletions
diff --git a/doc/user/application_security/container_scanning/img/container_scanning.png b/doc/user/application_security/container_scanning/img/container_scanning.png Binary files differnew file mode 100644 index 00000000000..e47f62acd9d --- /dev/null +++ b/doc/user/application_security/container_scanning/img/container_scanning.png diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md new file mode 100644 index 00000000000..ce86ade3c1a --- /dev/null +++ b/doc/user/application_security/container_scanning/index.md @@ -0,0 +1,202 @@ +# Container Scanning **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3672) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can check your Docker +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 +your existing `.gitlab-ci.yml` file or by implicitly using +[Auto Container Scanning](../../../topics/autodevops/index.md#auto-container-scanning) +that is provided by [Auto DevOps](../../../topics/autodevops/index.md). + +GitLab checks the Container Scanning report, compares the found vulnerabilities +between the source and target branches, and shows the information right on the +merge request. + + + +## Use cases + +If you distribute your application with Docker, then there's a great chance +that your image is based on other Docker images that may in turn contain some +known vulnerabilities that could be exploited. + +Having an extra job in your pipeline that checks for those vulnerabilities, +and the fact that they are displayed inside a merge request, makes it very easy +to perform audits for your Docker-based apps. + +## Requirements + +To enable Container Scanning in your pipeline, you need: + +- A GitLab Runner with the + [`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or + [`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. +- 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: + + ``` + $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA + ``` + + The variables above can be found in the + [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). + +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: + +```yaml +include: + template: Container-Scanning.gitlab-ci.yml +``` + +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. + +The report 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 +artifact available. Behind the scenes, the +[GitLab Container Scanning analyzer](https://gitlab.com/gitlab-org/security-products/container-scanning) +is used and runs the scans. + +If you want to whitelist some specific vulnerabilities, you can do so by defining +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/#predefined-environment-variables + CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG + CI_APPLICATION_TAG: $CI_COMMIT_SHA + 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:v2.0.6 + - 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/#predefined-environment-variables + CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG + CI_APPLICATION_TAG: $CI_COMMIT_SHA + 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:v2.0.6 + - 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 +vulnerabilities in your groups and projects. Read more about the +[Security Dashboard](../security_dashboard/index.md). + +## Interacting with the vulnerabilities + +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). diff --git a/doc/user/application_security/dast/img/dast_all.png b/doc/user/application_security/dast/img/dast_all.png Binary files differnew file mode 100644 index 00000000000..b6edc928dc3 --- /dev/null +++ b/doc/user/application_security/dast/img/dast_all.png diff --git a/doc/user/application_security/dast/img/dast_single.png b/doc/user/application_security/dast/img/dast_single.png Binary files differnew file mode 100644 index 00000000000..26ca4bde786 --- /dev/null +++ b/doc/user/application_security/dast/img/dast_single.png diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md new file mode 100644 index 00000000000..904c9e8fefe --- /dev/null +++ b/doc/user/application_security/dast/index.md @@ -0,0 +1,262 @@ +# 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. + +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, +such as cross-site scripting or broken authentication flaws. This is where +Dynamic Application Security Testing (DAST) comes into place. + +## Overview + +If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web application(s) +for known vulnerabilities using Dynamic Application Security Testing (DAST). + +You can take advantage of DAST by either [including the CI job](#configuring-dast) 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). + +GitLab checks the DAST report, compares the found vulnerabilities between the source and target +branches, and shows the information right on the merge request. + + + +By clicking on one of the detected linked vulnerabilities, you will be able to +see the details and the URL(s) affected. + + + +[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_Application_Security_Testing) +is using the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy) +to perform an analysis on your running web application. + +By default, DAST executes [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan) and will perform passive scanning only. It will not actively attack your application. + +However, DAST can be [configured](#full-scan) +to also perform a so-called "active scan". That is, attack your application and produce a more extensive security report. +It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md). + +## Use cases + +It helps you automatically find security vulnerabilities in your running web +applications while you are developing and testing your applications. + +## Requirements + +To run a DAST job, you need GitLab Runner with the +[`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or +[`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. + +## 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 + +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). + +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: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_WEBSITE: https://example.com +``` + +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 +[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 + +It's also possible to authenticate the user before performing the DAST checks: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_WEBSITE: https://example.com + DAST_AUTH_URL: https://example.com/sign-in + DAST_USERNAME: john.doe@example.com + DAST_PASSWORD: john-doe-password + DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form + DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form + 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 +[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 + +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: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_FULL_SCAN_ENABLED: "true" +``` + +#### Customizing the DAST settings + +The SAST 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 [DAST README](https://gitlab.com/gitlab-org/security-products/dast#settings). + +For example: + +```yaml +include: + template: DAST.gitlab-ci.yml + +variables: + DAST_WEBSITE: https://example.com + DAST_TARGET_AVAILABILITY_TIMEOUT: 120 +``` + +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 + +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 +template inclusion and specify any additional keys under it. For example: + +```yaml +include: + template: DAST.gitlab-ci.yml + +dast: + stage: dast # IMPORTANT: don't forget to add this + variables: + DAST_WEBSITE: https://example.com + CI_DEBUG_TRACE: "true" +``` + +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] +``` + +## Security Dashboard + +The Security Dashboard is a good place to get an overview of all the security +vulnerabilities in your groups and projects. Read more about the +[Security Dashboard](../security_dashboard/index.md). + +## Interacting with the vulnerabilities + +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). diff --git a/doc/user/application_security/dependency_scanning/img/dependency_scanning.png b/doc/user/application_security/dependency_scanning/img/dependency_scanning.png Binary files differnew file mode 100644 index 00000000000..18df356f846 --- /dev/null +++ b/doc/user/application_security/dependency_scanning/img/dependency_scanning.png diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md new file mode 100644 index 00000000000..29db6fc8958 --- /dev/null +++ b/doc/user/application_security/dependency_scanning/index.md @@ -0,0 +1,224 @@ +# Dependency Scanning **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5105) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. + +## Overview + +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) +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). + +GitLab checks the Dependency Scanning report, compares the found vulnerabilities +between the source and target branches, and shows the information right on the +merge request. + + + +The results are sorted by the priority of the vulnerability: + +1. High +1. Medium +1. Low +1. Unknown +1. Everything else + +## Use cases + +It helps to automatically find security vulnerabilities in your dependencies +while you are developing and testing your applications. For example when your +application is using an external (open source) library which is known to be vulnerable. + +## Requirements + +To run a Dependency Scanning job, you need GitLab Runner with the +[`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or +[`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. + +## Supported languages and package managers + +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). + +## 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. + +### Including the provided 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: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml +``` + +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 +[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 + +The Dependency Scanning 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 +[Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings). + +For example: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DEP_SCAN_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 + +If you want to override the job definition (for example, change properties like +`variables` or `dependencies`), you need to declare a `dependency_scanning` job +after the template inclusion and specify any additional keys under it. For example: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +dependency_scanning: + variables: + 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 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] +``` + +## Security Dashboard + +The Security Dashboard is a good place to get an overview of all the security +vulnerabilities in your groups and projects. Read more about the +[Security Dashboard](../security_dashboard/index.md). + +## Interacting with the vulnerabilities + +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). 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 differnew file mode 100644 index 00000000000..7d70e8299f5 --- /dev/null +++ b/doc/user/application_security/img/create_issue_with_list_hover.png diff --git a/doc/user/application_security/img/interactive_reports.png b/doc/user/application_security/img/interactive_reports.png Binary files differnew file mode 100644 index 00000000000..9f9812dc69d --- /dev/null +++ b/doc/user/application_security/img/interactive_reports.png diff --git a/doc/user/application_security/img/issue.png b/doc/user/application_security/img/issue.png Binary files differnew file mode 100644 index 00000000000..6467201df3f --- /dev/null +++ b/doc/user/application_security/img/issue.png diff --git a/doc/user/application_security/img/vulnerability_solution.png b/doc/user/application_security/img/vulnerability_solution.png Binary files differnew file mode 100644 index 00000000000..7443b9b6eea --- /dev/null +++ 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 new file mode 100644 index 00000000000..64e72fab198 --- /dev/null +++ b/doc/user/application_security/index.md @@ -0,0 +1,104 @@ +# 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. + +## Security scanning tools + +GitLab can scan and report any vulnerabilities found in your project. + +| Secure scanning tools | 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. | + +## Interacting with the vulnerabilities + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.8. + +CAUTION: **Warning:** +This feature is currently [Alpha](https://about.gitlab.com/handbook/product/#alpha-beta-ga) and while you can start using it, it may receive important changes in the future. + +Each security vulnerability in the merge request report or the +[Security Dashboard](security_dashboard/index.md) is actionable. Clicking on an +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. +- [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. +- [Solution](#solutions-for-vulnerabilities): For some vulnerabilities + ([Dependency Scanning](dependency_scanning/index.md) and [Container Scanning](container_scanning/index.md)) + a solution is provided for how to fix the vulnerability. + + + +### Dismissing a vulnerability + +You can dismiss vulnerabilities by clicking the **Dismiss vulnerability** button. +This will dismiss the vulnerability and re-render it to reflect its dismissed state. +If you wish to undo this dismissal, you can click the **Undo dismiss** button. + +### Creating an issue for a vulnerability + +You can create an issue for a vulnerability by selecting the **Create issue** +button from within the vulnerability modal or using the action buttons to the right of +a vulnerability row when in the group security dashboard. + +This will create a [confidential issue](../project/issues/confidential_issues.md) +on the project this vulnerability came from and pre-fill it with some useful +information taken from the vulnerability report. Once the issue is created, you +will be redirected to it so you can edit, assign, or comment on it. + +Upon returning to the group security dashboard, you'll see that +the vulnerability will now have an associated issue next to the name. + + + +### Solutions for vulnerabilities + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.7. + +CAUTION: **Warning:** +Automatic Patch creation is only available for a subset of +[Dependency Scanning](dependency_scanning/index.md). At the moment only Node.JS +projects managed with yarn are supported. + +Some vulnerabilities can be fixed by applying the solution that GitLab +automatically generates. + +#### Manually applying the suggested patch + +Some vulnerabilities can be fixed by applying a patch that is automatically +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. + + + +#### 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. + +In certain cases, GitLab will allow you to create a merge request that will +automatically remediate the vulnerability. Any vulnerability that has a +[solution](#solutions-for-vulnerabilities) can have a merge request created to +automatically solve the issue. + +If this action is available there will be a **Create merge request** button in the vulnerability modal. +Clicking on this button will create a merge request to apply the solution onto the source branch. + + diff --git a/doc/user/application_security/license_management/img/license_management.png b/doc/user/application_security/license_management/img/license_management.png Binary files differnew file mode 100644 index 00000000000..cdce6b5fe38 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management.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 differnew file mode 100644 index 00000000000..0763130c375 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management_decision.png diff --git a/doc/user/application_security/license_management/img/license_management_pipeline_tab.png b/doc/user/application_security/license_management/img/license_management_pipeline_tab.png Binary files differnew file mode 100644 index 00000000000..80ffca815b9 --- /dev/null +++ b/doc/user/application_security/license_management/img/license_management_pipeline_tab.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 differnew file mode 100644 index 00000000000..b5490e59074 --- /dev/null +++ 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 new file mode 100644 index 00000000000..8b75995c377 --- /dev/null +++ b/doc/user/application_security/license_management/index.md @@ -0,0 +1,264 @@ +# License Management **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5483) +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. + +You can take advantage of License Management by either [including the job](#configuring-license-management) +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). + +GitLab checks the License Management 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) +licenses in your project's settings. + +NOTE: **Note:** +If the license management report doesn't have anything to compare to, no information +will be displayed in the merge request area. That is the case when you add the +`license_management` job in your `.gitlab-ci.yml` for the first time. +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. + + + +## Use cases + +It helps you find what licenses your project uses in its dependencies, and decide for each of then +whether to allow it or forbid it. For example, your application is using an external (open source) +library whose license is incompatible with yours. + +## Supported languages and package managers + +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/) | + +## 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. + +### 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: + +```yaml +include: + template: License-Management.gitlab-ci.yml +``` + +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) +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 + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. + +The `license_management` image already embeds many auto-detection scripts, languages, +and packages. Nevertheless, it's almost impossible to cover all cases for all projects. +That's why sometimes it's necessary to install extra packages, or to have extra steps +in the project automated setup, like the download and installation of a certificate. +For that, a `LICENSE_MANAGEMENT_SETUP_CMD` environment variable can be passed to the container, +with the required commands to run before the license detection. + +If present, this variable will override the setup step necessary to install all the packages +of your application (e.g.: for a project with a `Gemfile`, the setup step could be +`bundle install`). + +For example: + +```yaml +include: + template: License-Management.gitlab-ci.yml + +variables: + LICENSE_MANAGEMENT_SETUP_CMD: sh my-custom-install-script.sh +``` + +In this example, `my-custom-install-script.sh` is a shell script at the root +directory of your project. + +#### 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 +after the template inclusion and specify any additional keys under it. For example: + +```yaml +include: + template: License-Management.gitlab-ci.yml + +license_management: + variables: + CI_DEBUG_TRACE: "true" +``` + +#### 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. +Feel free to use it for the customization of Maven execution. For example: + +```yaml +include: + template: License-Management.gitlab-ci.yml + +license_management: + variables: + MAVEN_CLI_OPTS: --debug +``` + +`mvn install` runs through all of the [build life cycle](http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html) +stages prior to `install`, including `test`. Running unit tests is not directly +necessary for the license scanning purposes and consumes time, so it's skipped +by having the default value of `MAVEN_CLI_OPTS` as `-DskipTests`. If you want +to supply custom `MAVEN_CLI_OPTS` and skip tests at the same time, don't forget +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 + +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] +``` + +## Project policies for License Management + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5940) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. + +From the project's settings: + +- The list of licenses and their status can be managed. +- Licenses can be manually approved or blacklisted. + +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. +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. +1. Select the **Approve** or **Blacklist** radio button to approve or blacklist respectively + the selected license. + +  + +## License Management report under pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2. + +From your project's left sidebar, navigate to **CI/CD > Pipelines** and click on the +pipeline ID that has a `license_management` job to see the Licenses tab with the listed +licenses (if any). + + diff --git a/doc/user/application_security/sast/img/sast.png b/doc/user/application_security/sast/img/sast.png Binary files differnew file mode 100644 index 00000000000..2c75592c32a --- /dev/null +++ b/doc/user/application_security/sast/img/sast.png diff --git a/doc/user/application_security/sast/img/security_report.png b/doc/user/application_security/sast/img/security_report.png Binary files differnew file mode 100644 index 00000000000..ba41b707238 --- /dev/null +++ b/doc/user/application_security/sast/img/security_report.png diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md new file mode 100644 index 00000000000..377d218321a --- /dev/null +++ b/doc/user/application_security/sast/index.md @@ -0,0 +1,252 @@ +# 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. + +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. + +## Overview + +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 +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). + +GitLab checks the SAST report, compares the found vulnerabilities between the +source and target branches, and shows the information right on the merge request. + + + +The results are sorted by the priority of the vulnerability: + +1. Critical +1. High +1. Medium +1. Low +1. Unknown +1. Everything else + +## Use cases + +- Your code has a potentially dangerous attribute in a class, or unsafe code + that can lead to unintended code execution. +- Your application is vulnerable to cross-site scripting (XSS) attacks that can + be leveraged to unauthorized access to session data. + +## Requirements + +To run a SAST job, you need GitLab Runner with the +[`docker`](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) or +[`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. + +## Supported languages and frameworks + +The following table shows which languages, package managers and frameworks are supported and which tools are used. + +| Language (package managers) / framework | Scan tool | Introduced in GitLab Version | +|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------| +| .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 | +| 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 | +| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | +| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | +| Javascript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8 | +| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1 | +| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | +| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/openstack/bandit) | 10.3 | +| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3 | +| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | +| Typescript | [TSLint config security](https://github.com/webschik/tslint-config-security/) | 11.9 | + +NOTE: **Note:** +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). + +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. + +To enable SAST using the provided template, add the following to your `.gitlab-ci.yml` +file: + +```yaml +include: + template: SAST.gitlab-ci.yml +``` + +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 +[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 + +The SAST 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 +[SAST tool documentation](https://gitlab.com/gitlab-org/security-products/sast#settings). + +In the following example, we include the SAST template and at the same time we +set the `SAST_GOSEC_LEVEL` variable to `2`: + +```yaml +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_GOSEC_LEVEL: 2 +``` + +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 + +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 +template inclusion and specify any additional keys under it. For example: + +```yaml +include: + template: SAST.gitlab-ci.yml + +sast: + variables: + 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 `sast` +job can be added: + +```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_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 +``` + +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. + +## Manual job definition for GitLab 11.4 and earlier (deprecated) + +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. + +For GitLab 11.4 and earlier, the SAST job should look like: + +```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] +``` + +## Secret detection + +GitLab is also able to detect secrets and credentials that have been unintentionally pushed to the repository. +For example, an API key that allows write access to third-party deployment environments. + +This check is performed by a specific analyzer during the `sast` job. It runs regardless of the programming +language of your app, and you don't need to change anything to your +CI/CD configuration file to turn it on. Results are available in the SAST report. + +GitLab currently includes [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) checks. + +## Security report under pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/3776) +in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.6. + +Visit any pipeline page which has a `sast` job and you will be able to see +the security report tab with the listed vulnerabilities (if any). + + + +## Security Dashboard + +The Security Dashboard is a good place to get an overview of all the security +vulnerabilities in your groups and projects. Read more about the +[Security Dashboard](../security_dashboard/index.md). + +## Interacting with the vulnerabilities + +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). diff --git a/doc/user/application_security/security_dashboard/img/dashboard.png b/doc/user/application_security/security_dashboard/img/dashboard.png Binary files differnew file mode 100644 index 00000000000..d52a6dacdbf --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/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 differnew file mode 100644 index 00000000000..3294e59e943 --- /dev/null +++ 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 new file mode 100644 index 00000000000..ca31e15c65f --- /dev/null +++ b/doc/user/application_security/security_dashboard/index.md @@ -0,0 +1,103 @@ +# 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. + +You can also drill down into a vulnerability and get extra information, see which +project it comes from, the file it's in, and various metadata to help you analyze +the risk. You can also action these vulnerabilities by creating an issue for them, +or by dismissing them. + +To benefit from the Security Dashboard you must first configure one of the +[security reports](../index.md). + +## Supported reports + +The Security Dashboard supports the following reports: + +- [Container Scanning](../container_scanning/index.md) +- [DAST](../dast/index.md) +- [Dependency Scanning](../dependency_scanning/index.md) +- [SAST](../sast/index.md) + +## Requirements + +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. + If you're using the shared Runners on GitLab.com, this is already the case. + +## Project Security Dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6165) in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.1. + +At the project level, the Security Dashboard displays the latest security reports +for your project. Use it to find and fix vulnerabilities affecting the +[default branch](../../project/repository/branches/index.md#default-branch). + + + +## Group Security Dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6709) in + [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**. + +Once you're on the dashboard, at the top you should see a series of filters for: + +- Severity +- 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. +Underneath this overview is a timeline chart that shows how many open +vulnerabilities your projects had at various points in time. You can filter among 30, 60, and +90 days, with the default being 90. Hover over the chart to get more details about +the open vulnerabilities at a specific time. + +Finally, there is a list of all the vulnerabilities in the group, sorted by severity. +In that list, you can see the severity of the vulnerability, its name, its +confidence (likelihood of the vulnerability to be a positive one), and the project +it's from. + +If you hover over a row, there will appear some actions you can take: + +- "More info" +- "Create issue" +- "Dismiss vulnerability" + +Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). + +## Keeping the dashboards up to date + +The Security Dashboard displays information from the results of the most recent +security scan on the [default branch](../../project/repository/branches/index.md#default-branch), +which means that security scans are performed every time the branch is updated. + +If the default branch is updated infrequently, scans are run infrequently and the +information on the Security Dashboard can become outdated as new vulnerabilities +are discovered. + +To ensure the information on the Security Dashboard is regularly updated, +[configure a scheduled pipeline](../../project/pipelines/schedules.md) to run a +daily security scan. This will update the information displayed on the Security +Dashboard regardless of how often the default branch is updated. + +That way, reports are created even if no code change happens. + +## Security scans using Auto DevOps + +When using [Auto DevOps](../../../topics/autodevops/index.md), use +[special environment variables](../../../topics/autodevops/index.md#environment-variables) +to configure daily security scans. |
