Commit 59ad8019 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis 🚀

Redirect Container Scanning docs

Find and replace the old Container Scanning paths
parent 52477ff5
......@@ -351,15 +351,15 @@ high-level view on projects and groups, and start remediation processes when nee
The following documentation relates to the DevOps **Secure** stage:
| Monitor Topics | Description |
|:--------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------|
| [Container Scanning](user/project/merge_requests/container_scanning.md) **[ULTIMATE]** | Use Clair to scan docker images for known vulnerabilities. |
| [Dependency Scanning](user/project/merge_requests/dependency_scanning.md) **[ULTIMATE]** | Analyze your dependencies for known vulnerabilities. |
| [Dynamic Application Security Testing (DAST)](user/project/merge_requests/dast.md) **[ULTIMATE]** | Analyze running web applications for known vulnerabilities. |
| [Group Security Dashboard](user/group/security_dashboard/index.md) **[ULTIMATE]** | View vulnerabilities in all the projects in a group and its subgroups. |
| [License Management](user/project/merge_requests/license_management.md) **[ULTIMATE]** | Search your project's dependencies for their licenses. |
| [Project Security Dashboard](user/project/security_dashboard.md) **[ULTIMATE]** | View the latest security reports for your project. |
| [Static Application Security Testing (SAST)](user/project/merge_requests/sast.md) **[ULTIMATE]** | Analyze source code for known vulnerabilities. |
| Secure Topics | Description |
|:------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------|
| [Container Scanning](user/application_security/container_scanning/index.md) **[ULTIMATE]** | Use Clair to scan docker images for known vulnerabilities. |
| [Dependency Scanning](user/application_security/dependency_scanning/index.md) **[ULTIMATE]** | Analyze your dependencies for known vulnerabilities. |
| [Dynamic Application Security Testing (DAST)](user/application_security/dast/index.md) **[ULTIMATE]** | Analyze running web applications for known vulnerabilities. |
| [Group Security Dashboard](user/application_security/security_dashboard/index.md) **[ULTIMATE]** | View vulnerabilities in all the projects in a group and its subgroups. |
| [License Management](user/application_security/license_management/index.md) **[ULTIMATE]** | Search your project's dependencies for their licenses. |
| [Project Security Dashboard](user/application_security/security_dashboard/index.md) **[ULTIMATE]** | View the latest security reports for your project. |
| [Static Application Security Testing (SAST)](user/application_security/sast/index.md) **[ULTIMATE]** | Analyze source code for known vulnerabilities. |
## Subscribe to GitLab
......
# Container Scanning with GitLab CI/CD **[ULTIMATE]**
---
redirect_to: '../../user/application_security/container_scanning/index.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.
These examples show how to run Container Scanning on your Docker image by using GitLab CI/CD.
CAUTION: **Caution:**
Starting with GitLab 11.5, Container Scanning feature is licensed under the name `container_scanning`.
While the old name `sast_container` is still maintained, it has been deprecated with GitLab 11.5 and
may be removed in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml`
configuration to reflect that change if you are using the `$GITLAB_FEATURES` environment variable.
## Prerequisites
To run a Container Scanning job, you need:
- a GitLab Runner with
[docker-in-docker executor](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
- to [build and push](../../ci/docker/using_docker_build.md#container-registry-examples) your Docker image
using the [Container Registry](https://docs.gitlab.com/ee/user/project/container_registry.html) running within your GitLab installation.
## Configuring with templates
Since GitLab 11.9, a CI/CD template with the default Container Scanning job definition is provided as a part of your GitLab installation.
This section describes how to use it and customize its execution.
### Using job definition template
CAUTION: **Caution:**
The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
For earlier versions, use the [manual job definition](#manual-job-definition).
Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for Container Scanning:
```yaml
include:
template: Container-Scanning.gitlab-ci.yml
```
If you want to whitelist some specific vulnerabilities, you can do so by defining
them in a [YAML file](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file),
in our case its named `clair-whitelist.yml`.
### Scanning results
The above example will create a `container_scanning` job in your CI/CD pipeline, pull
the image from the [Container Registry](../../user/project/container_registry.md)
(whose name is defined from the two `CI_APPLICATION_` variables) and scan it
for possible vulnerabilities. The report will be saved as a
[Container Scanning report artifact](../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.
TIP: **Tip:**
For [GitLab Ultimate][ee] users, this information will
be automatically extracted and shown right in the merge request widget.
[Learn more on Container Scanning in merge requests](../../user/project/merge_requests/container_scanning.html).
## Manual job definition
CAUTION: **Caution:**
The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use
[the job definition template](#using-job-definition-template) since 11.9)_.
It also requires the GitLab Runner 11.5 or later.
For earlier versions, use the [previous job definitions](#previous-job-definitions).
If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
```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
```
## Previous job definitions
CAUTION: **Caution:**
Before GitLab 11.5, 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 next major release, GitLab 12.0.
You are 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
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 next major release, GitLab 12.0.
[ee]: https://about.gitlab.com/pricing/
This document was moved to [another location](../../user/application_security/container_scanning/index.md).
# Dynamic Application Security Testing with GitLab CI/CD
---
redirect_to: '../../user/application_security/dast/index.md'
---
[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.
Since it is based on [ZAP Baseline](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan)
DAST will perform passive scanning only;
it will not actively attack your application.
It can be very useful combined with [Review Apps](../review_apps/index.md).
These examples show how to run DAST on your running web application by using GitLab CI/CD.
## Prerequisites
To run a DAST job, you need GitLab Runner with
[docker-in-docker executor](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
## Configuring with templates
Since GitLab 11.9, a CI/CD template with the default DAST job definition is provided as a part of your GitLab installation.
This section describes how to use it and customize its execution.
### Using job definition template
CAUTION: **Caution:**
The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
For earlier versions, use the [manual job definition](#manual-job-definition).
Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for DAST:
```yaml
include:
template: DAST.gitlab-ci.yml
variables:
DAST_WEBSITE: https://example.com
```
The above example will create a `dast` job in your CI/CD pipeline which will 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:
- The `DAST_WEBSITE` [variable](../../ci/yaml/README.md#variables).
- In an `environment_url.txt` file at the root of your project.
It's also possible to authenticate the user before performing DAST checks:
```yaml
include:
template: DAST.gitlab-ci.yml
variables:
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
```
### Scanning results
The report will be saved as a
[DAST report artifact](../yaml/README.md#artifactsreportsdast-ultimate)
that you can later download and analyze.
Due to implementation limitations we always take the latest DAST artifact available.
TIP: **Tip:**
For [GitLab Ultimate][ee] users, this information will
be automatically extracted and shown right in the merge request widget.
[Learn more on DAST in merge requests](../../user/project/merge_requests/dast.md).
### Customizing the template
You can customize DAST job execution in various ways of different granularity.
#### Scanning tool settings
DAST tool settings can be changed through environment variables. These variables are documented in the:
- Job definition [template](#using-job-definition-template).
- DAST [README](https://gitlab.com/gitlab-org/security-products/dast#settings).
The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
parameter in the project's pipeline configuration file (`.gitlab-ci.yml`):
```yaml
include:
template: DAST.gitlab-ci.yml
variables:
DAST_TARGET_AVAILABILITY_TIMEOUT: 120
```
Because template is evaluated [before](../yaml/README.md#include) the pipeline configuration,
the last mention of the variable will take precedence.
#### Overriding job definition
If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
its definition 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:
CI_DEBUG_TRACE: "true"
```
CAUTION: **Caution:**
As DAST job belongs to a separate `"dast"` stage that runs after all [default stages](../yaml/README.md#stages),
don't forget to add `stage: dast` entry when you override the template job definition.
## Manual job definition
CAUTION: **Caution:**
The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use
[the job definition template](#using-job-definition-template) since 11.9)_.
It also requires the GitLab Runner 11.5 or later.
For earlier versions, use the [previous job definitions](#previous-job-definitions).
If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
```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 is supposed to hold 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 [zaproxy documentation](https://gitlab.com/gitlab-org/security-products/zaproxy)
to learn more about authentication settings.
## Previous job definitions
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 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]
```
[ee]: https://about.gitlab.com/pricing/
This document was moved to [another location](../../user/application_security/dast/index.md).
# Dependency Scanning with GitLab CI/CD **[ULTIMATE]**
---
redirect_to: '../../user/application_security/dependency_scanning/index.md'
---
These examples show how to run Dependency Scanning on your project's dependencies by using GitLab CI/CD.
## Prerequisites
To run a Dependency Scanning job, you need GitLab Runner with
[docker-in-docker executor](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode).
## Configuring with templates
Since GitLab 11.9, a CI/CD template with the default Dependency Scanning job definition is provided as a part of your GitLab installation.
This section describes how to use it and customize its execution.
### Using job definition template
CAUTION: **Caution:**
The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
For earlier versions, use the [manual job definition](#manual-job-definition).
Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for Dependency Scanning:
```yaml
include:
template: Dependency-Scanning.gitlab-ci.yml
```
### Scanning results
The above example will create a `dependency_scanning` job in your CI/CD pipeline
and scan your dependencies 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.
The results are sorted by the priority of the vulnerability:
1. High
1. Medium
1. Low
1. Unknown
1. Everything else
Behind the scenes, the [GitLab Dependency Scanning Docker image](https://gitlab.com/gitlab-org/security-products/dependency-scanning)
is used to detect the languages/package managers and in turn runs the matching scan tools.
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 documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks)
and the [customization guide](#customizing-the-template).
TIP: **Tip:**
For [GitLab Ultimate][ee] users, this information will
be automatically extracted and shown right in the merge request widget.
[Learn more on Dependency Scanning in merge requests](../../user/project/merge_requests/dependency_scanning.md).
### Customizing the template
You can customize Dependency Scanning job execution in various ways of different granularity.
#### Scanning tool settings
Dependency Scanning tool settings can be changed through environment variables. These variables are documented in the:
- Job definition [template](#using-job-definition-template).
- Dependency Scanning [README](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings).
The customization itself is performed by using the [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables)
parameter in the project's pipeline configuration file (`.gitlab-ci.yml`):
```yaml
include:
template: Dependency-Scanning.gitlab-ci.yml
variables:
DEP_SCAN_DISABLE_REMOTE_CHECKS: true
```
Because template is evaluated [before](../yaml/README.md#include) the pipeline configuration,
the last mention of the variable will take precedence.
#### Overriding job definition
If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
its definition 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
CAUTION: **Caution:**
The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use
[the job definition template](#using-job-definition-template) since 11.9)_.
It also requires the GitLab Runner 11.5 or later.
For earlier versions, use the [previous job definitions](#previous-job-definitions).
If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
```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.
## Previous job definitions
CAUTION: **Caution:**
Before GitLab 11.5, Dependency 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 next major release, GitLab 12.0.
You are 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]
```
## Supported languages and package managers
See [the full list of supported languages and package managers](../../user/project/merge_requests/dependency_scanning.md#supported-languages-and-dependency-managers).
[ee]: https://about.gitlab.com/pricing/
This document was moved to [another location](../../user/application_security/dependency_scanning/index.md).
# Dependencies license management with GitLab CI/CD **[ULTIMATE]**
---
redirect_to: '../../user/application_security/license_management/index.md'
---
These examples show how to run License Management scanning on your project's dependencies by using GitLab CI/CD.
## Prerequisites
To run a License Management scanning job, you need GitLab Runner with
[docker executor](https://docs.gitlab.com/runner/executors/docker.html).
## Configuring with templates
Since GitLab 11.9, a CI/CD template with the default License Management scanning job definition is provided as a part of your GitLab installation.
This section describes how to use it and customize its execution.
### Using job definition template
CAUTION: **Caution:**
The CI/CD template for job definition is supported on GitLab 11.9 and later versions.
For earlier versions, use the [manual job definition](#manual-job-definition).
Once you set up the Runner, add a new job to `.gitlab-ci.yml` using [the CI/CD template](../../ci/yaml/README.md#includetemplate) for License Management:
```yaml
include:
template: License-Management.gitlab-ci.yml
```
### Scanning results
The above example 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.
TIP: **Tip:**
For [GitLab Ultimate][ee] users, this information will
be automatically extracted and shown right in the merge request widget.
[Learn more on License Management in merge requests](../../user/project/merge_requests/license_management.md).
### Customizing the template
#### Install custom project dependencies
> Introduced in GitLab Ultimate 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 `SETUP_CMD` environment variable can be passed to the container,
with the required commands to run before license detection.
If present, this variable will override the setup step necessary to install all the packages
of your application (ex: for a project with a `Gemfile`, the setup step will be `bundle install`).
Example:
```yaml
include:
template: License-Management.gitlab-ci.yml
variables:
LICENSE_MANAGEMENT_SETUP_CMD: ./my-custom-install-script.sh
```
In this example, `my-custom-install-script.sh` is a shell script at the root of the project.
#### Overriding job definition
If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare
its definition after the template inclusion and specify any additional keys under it. For example:
```yaml
include:
template: License-Management.gitlab-ci.yml
license_management:
stage: my-custom-stage
```
## Manual job definition
CAUTION: **Caution:**
The job definition shown below is supported on GitLab 11.5 and later versions _(although it's preferred to use
[the job definition template](#using-job-definition-template) since 11.9)_.
It also requires the GitLab Runner 11.5 or later.
For earlier versions, use the [previous job definitions](#previous-job-definitions).
If you are using GitLab prior to 11.9, you can define it manually using the following snippet:
```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
```
Install custom project dependencies via `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
```
## Maven projects configuration
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, e.g.:
```yaml
include:
template: License-Management.gitlab-ci.yml
license_management:
variables:
MAVEN_CLI_OPTS: --debug
```
CAUTION: **Caution:**
`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`, don't forget to add `-DskipTests` to your
options.
TIP: **Tip:**
If you still need to run tests during `mvn install`, supply `MAVEN_CLI_OPTS` with value `-DskipTests=false`.
## Previous job definitions
CAUTION: **Caution:**
Before GitLab 11.5, License Management 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 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: