OWASP Dependency-Track

ID: dependency-track

Build Status Quality Gate Status Security Rating License Plugin Version Jenkins Plugin Installs GitHub open issues Website

The Dependency-Track Jenkins plugin aids in publishing CycloneDX and SPDX Software Bill-of-Materials (SBOM) to the Dependency-Track platform.

Dependency-Track is an intelligent Software Supply Chain Component Analysis platform that allows organizations to identify and reduce risk from the use of third-party and open source components.

Publishing SBOMs can be performed asynchronously or synchronously.

Asynchronous publishing simply uploads the SBOM to Dependency-Track and the job continues. Synchronous publishing waits for Dependency-Track to process the SBOM after being uploaded. Synchronous publishing has the benefit of displaying interactive job trends and per build findings.

job trend

findings

Global Configuration

To setup, navigate to Jenkins > System Configuration and complete the Dependency-Track section.

global configuration

Dependency-Track URL: URL to your Dependency-Track instance.

API key: API Key used for authentication.

Auto Create Projects: auto creation of projects by giving a project name and version. The API key provided requires the PROJECT_CREATION_UPLOAD permission to use this feature.

Dependency-Track Frontend URL: alternative URL to the Frontend of your Dependency-Track instance. Use this if you run backend and frontend on different servers. If omitted, "Dependency-Track URL" will be used instead.

Polling Timeout: Defines the maximum number of minutes to wait for Dependency-Track to process a job when using synchronous publishing.

Polling Interval: Defines the number of seconds to wait between two checks for Dependency-Track to process a job when using synchronous publishing.

Connection Timeout: Defines the maximum number of seconds to wait for connecting to Dependency-Track.

Response Timeout: Defines the maximum number of seconds to wait for Dependency-Track to respond.

Job Configuration

Once configured with a valid URL and API key, simply configure a job to publish the artifact.

job configuration

Dependency-Track project: Specifies the unique project ID to upload SBOM to. This dropdown will be automatically populated with a list of active projects.

Dependency-Track project name: Specifies the name of the project for automatic creation of project during the upload process. This is an alternative to specifying the unique ID. It must be used together with a project version. Only avaible if "Auto Create projects" is enabled. The use of environment variables in the form ${VARIABLE} is supported here.

Dependency-Track project version: Specifies the version of the project for automatic creation of project during the upload process. This is an alternative to specifying the unique ID. It must be used together with a project name. Only avaible if "Auto Create projects" is enabled. The use of environment variables in the form ${VARIABLE} is supported here.

Artifact: Specifies the file to upload. Paths are relative from the Jenkins workspace. The use of environment variables in the form ${VARIABLE} is supported here.

Enable synchronous publishing mode: Uploads a SBOM to Dependency-Track and waits for Dependency-Track to process and return results. The results returned are identical to the auditable findings but exclude findings that have previously been suppressed. Analysis decisions and vulnerability details are included in the response. Synchronous mode is possible with Dependency-Track v3.3.1 and higher.

Override global settings: Allows to override global settings for "Auto Create Projects", "Dependency-Track URL", "Dependency-Track Frontend URL" and "API key".

Thresholds

When Synchronous mode is enabled, thresholds can be defined which can optionally put the job into an UNSTABLE or FAILURE state.

risk thresholds

Total Findings: Sets the threshold for the total number of critical, high, medium, or low severity findings allowed. If the number of findings equals or is greater than the threshold for any one of the severities, the job status will be changed to UNSTABLE or FAILURE.

New Findings: Sets the threshold for the number of new critical, high, medium, or low severity findings allowed. If the number of new findings equals or is greater than the previous builds finding for any one of the severities, the job status will be changed to UNSTABLE or FAILURE.

Examples

Declarative Pipeline

pipeline {
    agent any

    stages {
        stage('dependencyTrackPublisher') {
            steps {
                withCredentials([string(credentialsId: '506ed685-4e2b-4d31-a44f-8ba8e67b6341', variable: 'API_KEY')]) {
                    dependencyTrackPublisher artifact: 'target/bom.xml', projectName: 'my-project', projectVersion: 'my-version', synchronous: true, dependencyTrackApiKey: API_KEY
                }
            }
        }
    }
}

Scripted Pipeline

node {
    stage('dependencyTrackPublisher') {
        try {
            dependencyTrackPublisher artifact: 'target/bom.xml', projectId: 'a65ea72b-5b77-40c5-8b19-fb83525f40eb', synchronous: true
        } catch (e) {
            echo 'failed'
        }
    }
}

Copyright & License

Dependency-Track and the Dependency-Track Jenkins Plugin are Copyright © Steve Springett. All Rights Reserved.

Permission to modify and redistribute is granted under the terms of the Apache 2.0 license.

Changes

Please refer to CHANGELOG.md for a list of changes.

ArchivesGet past versions
Version: 3.1.1
Released:
Requires Jenkins 2.249.2
Installs: 3,262
Maintainers
Ronny Perinke
Help us improve this page!
To propose a change submit a pull request to the plugin page on GitHub.
Previous Security Warnings