diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md index 5ef41d498cc0f7a503fd29b5d56d54a2b93dd084..7c5031a3989d57558dc4add30c964cfaaf1bb2f1 100644 --- a/doc/ci/examples/container_scanning.md +++ b/doc/ci/examples/container_scanning.md @@ -1,20 +1,73 @@ -# Container Scanning with GitLab CI/CD - -CAUTION: **Caution:** -The job definition shown below is supported on GitLab 11.5 and later versions. -It also requires the GitLab Runner 11.5 or later. -For earlier versions, use the [previous job definitions](#previous-job-definitions). +# Container Scanning with GitLab CI/CD **[ULTIMATE]** 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. -First, you need GitLab Runner with -[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). +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). -Once you set up the Runner, add a new job to `.gitlab-ci.yml` that -generates the expected report: +## 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: @@ -47,29 +100,6 @@ container_scanning: container_scanning: gl-container-scanning-report.json ``` -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. - -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`. - -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). - -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. - ## Previous job definitions CAUTION: **Caution:** @@ -111,7 +141,7 @@ container_scanning: paths: [gl-container-scanning-report.json] ``` -Alternatively the job name could be `sast:container` +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. diff --git a/doc/ci/examples/dast.md b/doc/ci/examples/dast.md index 52c4147e2453518f355438cb618be32434d7aafe..c9506cf3f02a46871f0e61c32e1a13b687566472 100644 --- a/doc/ci/examples/dast.md +++ b/doc/ci/examples/dast.md @@ -1,11 +1,6 @@ # Dynamic Application Security Testing with GitLab CI/CD -CAUTION: **Caution:** -The job definition shown below is supported on GitLab 11.5 and later versions. -It also requires the GitLab Runner 11.5 or later. -For earlier versions, use the [previous job definitions](#previous-job-definitions). - -[Dynamic Application Security Testing (DAST)](https://en.wikipedia.org/wiki/Dynamic_program_analysis) +[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) @@ -14,13 +9,114 @@ it will not actively attack your application. It can be very useful combined with [Review Apps](../review_apps/index.md). -## Example +These examples show how to run DAST on your running web application by using GitLab CI/CD. + +## Prerequisites -First, you need GitLab Runner with +To run a DAST job, you need GitLab Runner with [docker executor](https://docs.gitlab.com/runner/executors/docker.html). -Once you set up the Runner, add a new job to `.gitlab-ci.yml` that -generates the expected report: +## 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 +``` + +The above example will create a `dast` job in your CI/CD pipeline which will run +the tests on the URL defined in the `DAST_WEBSITE` variable (change it to use your +own) and scan it for possible vulnerabilities. + +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: @@ -37,14 +133,9 @@ dast: dast: gl-dast-report.json ``` -The above example will create a `dast` job in your CI/CD pipeline which will run -the tests on the URL defined in the `website` variable (change it to use your -own) and scan it for possible vulnerabilities. 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. +where the `website` variable is supposed to hold the URL to run the tests against. -It's also possible to authenticate the user before performing DAST checks: +For an authenticated scan, use the following definition: ```yaml dast: @@ -66,14 +157,10 @@ dast: reports: dast: gl-dast-report.json ``` + See [zaproxy documentation](https://gitlab.com/gitlab-org/security-products/zaproxy) to learn more about authentication settings. -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). - ## Previous job definitions CAUTION: **Caution:** @@ -97,6 +184,6 @@ dast: - cp /zap/wrk/gl-dast-report.json . artifacts: paths: [gl-dast-report.json] -``` +``` [ee]: https://about.gitlab.com/pricing/ diff --git a/doc/ci/examples/dependency_scanning.md b/doc/ci/examples/dependency_scanning.md index 48ddea7320320e853ed29ec22e9edafa285fd604..3b3cafc39b4f7366bd0f4a12ba2442343f710240 100644 --- a/doc/ci/examples/dependency_scanning.md +++ b/doc/ci/examples/dependency_scanning.md @@ -1,40 +1,32 @@ # Dependency Scanning with GitLab CI/CD **[ULTIMATE]** -CAUTION: **Caution:** -The job definition shown below is supported on GitLab 11.5 and later versions. -It also requires the GitLab Runner 11.5 or later. -For earlier versions, use the [previous job definitions](#previous-job-definitions). +These examples show how to run Dependency Scanning on your project's dependencies by using GitLab CI/CD. + +## Prerequisites -This example shows how to run Dependency Scanning on your -project's dependencies by using GitLab CI/CD. +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 -First, you need GitLab Runner with -[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). +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. -Once you set up the Runner, add a new job to `.gitlab-ci.yml` that -generates the expected report: +### 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 -dependency_scanning: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/') - - docker run - --env DEP_SCAN_DISABLE_REMOTE_CHECKS="${DEP_SCAN_DISABLE_REMOTE_CHECKS:-false}" - --volume "$PWD:/code" - --volume /var/run/docker.sock:/var/run/docker.sock - "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$SP_VERSION" /code - artifacts: - reports: - dependency_scanning: gl-dependency-scanning-report.json +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) @@ -54,16 +46,94 @@ is used to detect the languages/package managers and in turn runs the matching s 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). +disable it, check the [GitLab Dependency Scanning documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks) +and the [customization guide](#job-execution-customization). 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). -## Supported languages and package managers +### Customizing the template -See [the full list of supported languages and package managers](../../user/project/merge_requests/dependency_scanning.md#supported-languages-and-dependency-managers). +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 @@ -85,14 +155,26 @@ dependency_scanning: services: - docker:stable-dind script: - - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/') - - docker run - --env DEP_SCAN_DISABLE_REMOTE_CHECKS="${DEP_SCAN_DISABLE_REMOTE_CHECKS:-false}" - --volume "$PWD:/code" - --volume /var/run/docker.sock:/var/run/docker.sock - "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$SP_VERSION" /code + - 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/ diff --git a/doc/ci/examples/license_management.md b/doc/ci/examples/license_management.md index c45f1c0404ab1e2704e6bea561de9e5a9c9b9008..ab78b3c0b53ac50bbe1694b4d8be3277fe93a1bd 100644 --- a/doc/ci/examples/license_management.md +++ b/doc/ci/examples/license_management.md @@ -1,40 +1,46 @@ # Dependencies license management with GitLab CI/CD **[ULTIMATE]** -CAUTION: **Caution:** -The job definition shown below is supported on GitLab 11.5 and later versions. -It also requires the GitLab Runner 11.5 or later. -For earlier versions, use the [previous job definitions](#previous-job-definitions). +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). -This example shows how to run the License Management tool on your -project's dependencies by using GitLab CI/CD. +## Configuring with templates -First, you need GitLab Runner with -[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). +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. -Once you set up the Runner, add a new job to `.gitlab-ci.yml` that -generates the expected report: +### 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 -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 +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. -## Install custom project dependencies +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. @@ -50,14 +56,45 @@ of your application (ex: for a project with a `Gemfile`, the setup step will be 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 - variables: - SETUP_CMD: ./my-custom-install-script.sh allow_failure: true script: - /run.sh analyze . @@ -66,12 +103,23 @@ license_management: license_management: gl-license-management-report.json ``` -In this example, `my-custom-install-script.sh` is a shell script at the root of the project. +Install custom project dependencies via `SETUP_CMD` variable: -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). +```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 +``` ## Previous job definitions diff --git a/doc/ci/examples/sast.md b/doc/ci/examples/sast.md index 2c9db74b9b99a33eb7cd77189e4d5b8608849b2a..d55e1d11e3f45d61f1c7f4bfbd4da7ef2a1e2f1c 100644 --- a/doc/ci/examples/sast.md +++ b/doc/ci/examples/sast.md @@ -1,42 +1,35 @@ # Static Application Security Testing with GitLab CI/CD **[ULTIMATE]** -CAUTION: **Caution:** -The job definition shown below is supported on GitLab 11.5 and later versions. -It also requires the GitLab Runner 11.5 or later. -For earlier versions, use the [previous job definitions](#previous-job-definitions). - -This example shows how to run -[Static Application Security Testing (SAST)](https://en.wikipedia.org/wiki/Static_program_analysis) +These examples show how to run [Static Application Security Testing (SAST)](https://en.wikipedia.org/wiki/Static_program_analysis) on your project's source code by using GitLab CI/CD. -First, you need GitLab Runner with -[docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). +## Prerequisites + +To run a SAST 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 SAST 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 -Once you set up the Runner, add a new job to `.gitlab-ci.yml` that -generates the expected report: +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 SAST: ```yaml -sast: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export 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:$SP_VERSION" /app/bin/run /code - artifacts: - reports: - sast: gl-sast-report.json +include: + template: SAST.gitlab-ci.yml ``` +### Scanning results + The above example will create a `sast` job in your CI/CD pipeline -and scan your dependencies for possible vulnerabilities. The report will be saved as a +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. @@ -58,9 +51,89 @@ For [GitLab Ultimate][ee] users, this information will be automatically extracted and shown right in the merge request widget. [Learn more on SAST in merge requests](../../user/project/merge_requests/sast.md). -## Supported languages and frameworks +### Customizing the template + +You can customize SAST job execution in various ways of different granularity. + +#### Scanning tool settings + +SAST tool settings can be changed through environment variables. These variables are documented in the: + +- Job definition [template](#using-job-definition-template). +- SAST [README](https://gitlab.com/gitlab-org/security-products/sast#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: SAST.gitlab-ci.yml + +variables: + SAST_GOSEC_LEVEL: 2 +``` + +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: SAST.gitlab-ci.yml + +sast: + 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 +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 +``` -See [the full list of supported languages and frameworks](../../user/project/merge_requests/sast.md#supported-languages-and-frameworks). +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. ## Previous job definitions @@ -82,12 +155,12 @@ sast: services: - docker:stable-dind script: - - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/') + - 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:$SP_VERSION" /app/bin/run /code + "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code artifacts: paths: [gl-sast-report.json] ```