GitLab CI template for DefectDojo

This project implements a GitLab CI/CD template for DefectDojo dashboard.

DefectDojo is a security program and vulnerability management tool that allows you to consolidate all the vulnerabilities of your project into one source of truth.

⚠️ By default, DefectDojo will collect vulnerabilities only on your master or your main branch. For collecting vulnerabilities on another branch, set PROD_REF variable to your branch name.

Please read DefectDojo documentation for further information.

Get started

DefectDojo instance

You must have access to a DefectDojo server and set DEFECTDOJO_SERVER_URL variable according to this server's URL.

Define variables in your project

The name of the DefectDojo product will be set to the CI_PROJECT_PATH variable of the GitLab project.

The initial mandatory step for a developer is to retrieve his DefectDojo API v2 key. Once logged into DefectDojo, retrieve your API v2 key by clicking on the user logo in the top-right corner. Store this API key into a variable named DEFECTDOJO_API_KEY.

Check you use at least one security tool

DefectDojo job will NOT launch security tools: it will only import security reports that have been generated on YOUR demand in your .gitlab-ci.yml. We strongly advise you to use to be continuous templates to launch security tools. Some security tools are already included in more generic templates (such as python), but other security tools are the object of a specific template (such as sonar).

So make sure that your .gitlab-ci.yml config launches at least one of the supported security tools, otherwise the current template will be useless.

Every day usage in your pipelines

Every time your CI/CD pipeline is launched, if you have at least one security tool which generates a security report, then all of the newly generated security reports will be imported into DefectDojo, you have nothing to do.

You may connect to DefectDojo server to visualize the summary of your project's vulnerabilities. You might also receive an e-mail notification if your project contains new vulnerabilities, depending on the threshold you defined in DEFECTDOJO_NOTIFICATION_SEVERITIES and on the fact you defined DEFECTDOJO_SMTP_SERVER.

Usage

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/defectdojo/gitlab-ci-defectdojo@2.6.4
    # 2: set/override component inputs
    inputs:
      server-url: "https://defectdojo.acme.host" # ⚠ this is only an example

Use as a CI/CD template (legacy)

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: "to-be-continuous/defectdojo"
    ref: "2.6.4"
    file: "/templates/gitlab-ci-defectdojo.yml"

variables:
  # 2: set/override template variables
  DEFECTDOJO_SERVER_URL: "https://defectdojo.acme.host" # ⚠ this is only an example

defectdojo job

This job uploads security reports found in the artifacts to a DefectDojo server.

It is bound to the .post stage, and uses the following variables:

Global variables

Depending on the security tools you launch, and their configuration, you may have to redefine some of the following variables in your gitlab-ci.yml:

Supported security tools

For now, the current template allows to import reports from the following tools:

• Bandit
• Dependency Check
• Gitleaks
• Hadolint
• MobSF
• NodeJSScan
• NPM Audit
• Semgrep
• SonarQube
• TestSSL
• Trivy
• Zap

SonarQube specific case

SonarQube is specific: contrary to other jobs, sonar job does not generate any artifact, but just launches an analysis on SonarQube server. In defectdojo job, a tool named sonar-report generates an HTML report thanks to Sonar API ; this report is finally imported in DefectDojo.

In order to launch SonarQube HTML-report generation, the following variables must be set:

• SONAR_URL (used by sonar template)
• SONAR_TOKEN (used by sonar template)
• DEFECTDOJO_SONARQUBE_APPLICATION
• DEFECTDOJO_SONARQUBE_PROJECT_KEY

The following variables are set by default, but may be overriden:

• DEFECTDOJO_SONARQUBE_SINCELEAKPERIOD (default: false)
• DEFECTDOJO_SONARQUBE_NOSECURITYHOTSPOT (default: true)
• DEFECTDOJO_SONARQUBE_ALLBUGS (default: false)

The following command is executed:

sonar-report \
--sonarurl="${SONAR_URL}" \
--sonarcomponent="${DEFECTDOJO_SONARQUBE_PROJECT_KEY}" \
--project="${DEFECTDOJO_SONARQUBE_PROJECT_KEY}" \
--application="${DEFECTDOJO_SONARQUBE_APPLICATION}" \
--branch="${CI_COMMIT_REF_NAME}" \
--sonartoken="${SONAR_TOKEN}" \
--sinceleakperiod="${DEFECTDOJO_SONARQUBE_SINCELEAKPERIOD}" \
--noSecurityHotspot="${DEFECTDOJO_SONARQUBE_NOSECURITYHOTSPOT}" \
--allbugs="${DEFECTDOJO_SONARQUBE_ALLBUGS}" > "$sonar_report"

Manual actions during pipeline

Since some security tools (Bandit, Safety...) must be launched manually in the pipeline, proceed in two steps:

• click manually on the corresponding jobs
• when they are all finished, click on defectdojo-publish job to launch it manually

Version history

See Tags page

Variants

The DefectDojo template can be used in conjunction with template variants to cover specific cases.

Vault variant

This variant allows delegating your secrets management to a Vault server.

Configuration

In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters:

Usage

Then you may retrieve any of your secret(s) from Vault using the following syntax:

@url@http://vault-secrets-provider/api/secrets/{secret_path}?field={field}

With:

Example

include:
  # main template
  - component: $CI_SERVER_FQDN/to-be-continuous/defectdojo/gitlab-ci-defectdojo@2.6.4
    inputs:
      server-url: "https://defectdojo.acme.host" # ⚠ this is only an example
      # Secrets managed by Vault
      api-key: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/defectdojo/credentials?field=token"
  # Vault variant
  - component: $CI_SERVER_FQDN/to-be-continuous/defectdojo/gitlab-ci-defectdojo-vault@2.6.4
    inputs:
      # audience claim for JWT
      vault-oidc-aud: "https://vault.acme.host"
      vault-base-url: "https://vault.acme.host/v1"