Commit 58f99e68 authored by Clement Bois's avatar Clement Bois
Browse files

feat: add quality gate feature

parent baa39764

README.md

+21 −1
Original line number Diff line number Diff line
@@ -31,7 +31,7 @@ Add the following to your `.gitlab-ci.yml`: 
include:

  # 1: include the template

  - project: "to-be-continuous/dependency-track"

    ref: "1.1.0"

    ref: "1.4.0"

    file: "/templates/gitlab-ci-dependency-track.yml"



variables:
@@ -179,6 +179,26 @@ The Dependency Track template uses the following configuration. 
| `show-findings` / `DEPTRACK_SHOW_FINDINGS`               | Wait for analysis and display found vulnerabilities in logs                                                              | _none_ (disabled)                                                           |

| `risk-score-threshold` / `DEPTRACK_RISK_SCORE_THRESHOLD` | Fail the job if risk score threshold is exceeded (`<0`: disabled - default: `-1`)                                        | `-1` (disabled)                                                             |



### Quality Gate



The job `dependency-track` runs after all the jobs in the pipeline have completed. It will not block the pipeline execution.



The `quality-gate-enabled` / `DEPTRACK_QUALITY_GATE_ENABLED` configuration can be set to `true` to enable a quality gate job `dependency-track-acceptance` that will block the pipeline if the risk score computed by Dependency Track exceeds a certain threshold defined by the `risk-score-threshold` / `DEPTRACK_RISK_SCORE_THRESHOLD` configuration.



:warning: By default, this acceptance job will use the same target project path as the main job, erasing the previous release SBOM files. If you want to keep clean release SBOM files, you should define a different project path for the acceptance job.



You can override the following configuration to customize the quality gate job:



| Input / Variable                                                                   | Description                                                                                               | Default value         |

| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------- |

| `quality-gate-enabled` / `DEPTRACK_QUALITY_GATE_ENABLED`                           | Enable a job at acceptance stage which will block the pipeline when failing                               | `false`               |

| `quality-gate-base-api-url` / `DEPTRACK_QUALITY_GATE_BASE_API_URL`                 | Override Dependency Track server base API url (includes `/api`) to use for acceptance stage               | _none_ (uses default) |

| :lock: `DEPTRACK_QUALITY_GATE_API_KEY`                                             | Override Dependency Track API key to use for acceptance stage                                             | _none_ (uses default) |

| `quality-gate-project-path` / `DEPTRACK_QUALITY_GATE_PROJECT_PATH`                 | Override Dependency Track target project path to publish SBOM files to during acceptance stage            | _none_ (uses default) |

| `quality-gate-merge` / `DEPTRACK_QUALITY_GATE_MERGE`                               | Merge all SBOM files into one (default `false`) during acceptance stage                                   | _none_ (uses default) |

| `quality-gate-show-findings` / `DEPTRACK_QUALITY_GATE_SHOW_FINDINGS`               | Wait for analysis and display found vulnerabilities in logs during acceptance stage                       | _none_ (uses default) |

| `quality-gate-risk-score-threshold` / `DEPTRACK_QUALITY_GATE_RISK_SCORE_THRESHOLD` | Fail the job if risk score threshold is exceeded (`<0`: disabled - default: `-1`) during acceptance stage | _none_ (uses default) |



### Secrets management



Here are some advices about your **secrets** (variables marked with a :lock:):

kicker.json

+39 −0
Original line number Diff line number Diff line
@@ -73,6 +73,45 @@ 
      "default": "-1"

    }

  ],

  "features": [

    {

      "id": "quality-gate",

      "name": "Quality Gate",

      "description": "Enable a job at acceptance stage which will block the pipeline when failing",

      "enable_with": "DEPTRACK_QUALITY_GATE_ENABLED",

      "variables": [

        {

          "name": "DEPTRACK_QUALITY_GATE_BASE_API_URL",

          "description": "Override Dependency Track server base API url (includes `/api`) to use for acceptance stage",

          "type": "url"

        },

        {

          "name": "DEPTRACK_QUALITY_GATE_API_KEY",

          "description": "Override Dependency Track API key to use for acceptance stage",

          "secret": true

        },

        {

          "name": "DEPTRACK_QUALITY_GATE_PROJECT_PATH",

          "description": "Override Dependency Track target project path to publish SBOM files to during acceptance stage"

        },

        {

          "name": "DEPTRACK_QUALITY_GATE_MERGE",

          "description": "Merge all SBOM files into one during acceptance stage",

          "advanced": true

        },

        {

          "name": "DEPTRACK_QUALITY_GATE_SHOW_FINDINGS",

          "description": "Wait for analysis and display found vulnerabilities in logs during acceptance stage",

          "advanced": true

        },

        {

          "name": "DEPTRACK_QUALITY_GATE_RISK_SCORE_THRESHOLD",

          "description": "Fail the acceptance job if risk score threshold is exceeded (`<0`: disabled - default: `-1`)",

          "advanced": true

        }

      ]

    }

  ],

  "variants": [

    {

      "id": "vault",

templates/gitlab-ci-dependency-track.yml

+69 −1
Original line number Diff line number Diff line
@@ -49,6 +49,28 @@ spec: 
      description: 'Fail the job if risk score threshold is exceeded (`<0`: disabled - default: `-1`)'

      type: number

      default: -1

    quality-gate-enabled:

      description: Enable a job at acceptance stage which will block the pipeline when failing

      type: boolean

      default: false

    quality-gate-base-api-url:

      description: Override Dependency Track server base API url (includes `/api`) to use for acceptance stage

      default: ''

    quality-gate-project-path:

      description: Override Dependency Track target project path to publish SBOM files to during acceptance stage

      default: ''

    quality-gate-merge:

      description: Merge all SBOM files into one during acceptance stage

      # should be a boolean but we want to keep the default empty

      default: ''

    quality-gate-show-findings:

      description: Wait for analysis and display found vulnerabilities in logs during acceptance stage

      # should be a boolean but we want to keep the default empty

      default: ''

    quality-gate-risk-score-threshold:

      description: 'Fail the acceptance job if risk score threshold is exceeded (`<0`: disabled - default: `-1`)'

      # should be a number but we want to keep the default empty

      default: ''

---

# default workflow rules: Merge Request pipelines

workflow:
@@ -75,6 +97,25 @@ workflow: 
      when: never

    - when: always



# test job prototype: implement adaptive pipeline rules

.test-policy:

  rules:

    # on tag: auto & failing

    - if: $CI_COMMIT_TAG

    # on ADAPTIVE_PIPELINE_DISABLED: auto & failing

    - if: '$ADAPTIVE_PIPELINE_DISABLED == "true"'

    # on production or integration branch(es): auto & failing

    - if: '$CI_COMMIT_REF_NAME =~ $PROD_REF || $CI_COMMIT_REF_NAME =~ $INTEG_REF'

    # early stage (dev branch, no MR): manual & non-failing

    - if: '$CI_MERGE_REQUEST_ID == null && $CI_OPEN_MERGE_REQUESTS == null'

      when: manual

      allow_failure: true

    # Draft MR: auto & non-failing

    - if: '$CI_MERGE_REQUEST_TITLE =~ /^Draft:.*/'

      allow_failure: true

    # else (Ready MR): auto & failing

    - when: on_success



variables:

  # variabilized tracking image

  TBC_TRACKING_IMAGE: registry.gitlab.com/to-be-continuous/tools/tracking:master
@@ -90,6 +131,13 @@ variables: 
  DEPTRACK_SHOW_FINDINGS: $[[ inputs.show-findings ]]

  DEPTRACK_RISK_SCORE_THRESHOLD: $[[ inputs.risk-score-threshold ]]



  DEPTRACK_QUALITY_GATE_ENABLED: $[[ inputs.quality-gate-enabled ]]

  DEPTRACK_QUALITY_GATE_BASE_API_URL: $[[ inputs.quality-gate-base-api-url ]]

  DEPTRACK_QUALITY_GATE_PROJECT_PATH: $[[ inputs.quality-gate-project-path ]]

  DEPTRACK_QUALITY_GATE_MERGE: $[[ inputs.quality-gate-merge ]]

  DEPTRACK_QUALITY_GATE_SHOW_FINDINGS: $[[ inputs.quality-gate-show-findings ]]

  DEPTRACK_QUALITY_GATE_RISK_SCORE_THRESHOLD: $[[ inputs.quality-gate-risk-score-threshold ]]



  # default production ref name (pattern)

  PROD_REF: '/^(master|main)$/'

  # default integration ref name (pattern)
@@ -334,7 +382,7 @@ stages: 


  # ENDSCRIPT



dependency-track:

.dependency-track-base:

  image:

    name: $DEPTRACK_SBOM_SCANNER_IMAGE

    entrypoint: [""]
@@ -352,8 +400,28 @@ dependency-track: 
    expire_in: 1 day

    paths:

      - "reports/deptrack-*"



dependency-track:

  extends: .dependency-track-base

  rules:

    # on production branch: auto

    - if: '$CI_COMMIT_REF_NAME =~ $PROD_REF'

    # on tag with release pattern: auto

    - if: '$CI_COMMIT_TAG =~ $RELEASE_REF'



dependency-track-quality-gate:

  extends: .dependency-track-base

  stage: acceptance

  script: |

    export DEPTRACK_BASE_API_URL="${DEPTRACK_QUALITY_GATE_BASE_API_URL:-$DEPTRACK_BASE_API_URL}"

    export DEPTRACK_API_KEY="${DEPTRACK_QUALITY_GATE_API_KEY:-$DEPTRACK_API_KEY}"

    export DEPTRACK_PROJECT_PATH="${DEPTRACK_QUALITY_GATE_PROJECT_PATH:-$DEPTRACK_PROJECT_PATH}"

    export DEPTRACK_MERGE="${DEPTRACK_QUALITY_GATE_MERGE:-$DEPTRACK_MERGE}"

    export DEPTRACK_SHOW_FINDINGS="${DEPTRACK_QUALITY_GATE_SHOW_FINDINGS:-$DEPTRACK_SHOW_FINDINGS}"

    export DEPTRACK_RISK_SCORE_THRESHOLD="${DEPTRACK_QUALITY_GATE_SCORE_THRESHOLD:-$DEPTRACK_SCORE_THRESHOLD}"

    sbom-scanner

  rules:

    # when quality gate enabled

    - if: '$DEPTRACK_QUALITY_GATE_ENABLED != "true"'

      when: never

    - !reference [.test-policy, rules]