Black Duck integrations & APIs

We created multiple options so you can choose the type of integration that best supports the task and your way of doing CI/CD development.

First, choose your approach:

  • Command line (CLI): Script the command line client to run in your environment, either directly or integrated into a build script of CI workflow.

  • Continuous integration (CI): Add a plug-in to existing pipelines that run in your SCM repo or Jenkins. Plug-ins are available in the marketplace and in many cases can be added to your config file by following step-by-step instructions in the documentation.

  • API: Use REST APIs to call services built into the product (e.g. retrieve issue data and import it into your internal dashboards).

Secondly, select the option tailored to the security products and CI/CD platforms you use.

Command line clients

For scripting in the command line, users have a choice between the original Detect client (built by the Black Duck team for Black Duck SCA) and the Bridge CLI client.

Detect client

Black Duck Detect is a scan client that analyzes code in your projects and associated folders to perform compositional analysis and find vulnerabilities.

It can be configured to send scan results to Black Duck, which generates risk analysis when identifying open-source components, licenses, and security vulnerabilities.

How Detect works:

  1. Uses the project's package manager to derive the hierarchy of dependencies.

  2. Runs the Black Duck signature scanner on the project. This might identify additional dependencies not known to the package manager.

  3. Uploads both sets of results (dependency details) to Black Duck, which creates the Bill Of Materials (BOM) for the project/version.

  4. You can view the output and analysis results in Black Duck SCA.

Detect consolidates the functionality of Black Duck, package managers, and continuous integration plugin tools to perform the following tasks:

  • Discover open-source components in your code.

  • Map components to known security vulnerabilities.

  • Identify license compliance and component quality risks.

  • Set and enforce open-source use and security policies.

  • Integrate open-source management into your DevOps environment.

  • Monitor and alert users when new security threats are reported.

  • Calculate security vulnerability risk in your code.

  • Produce reports of the open-source analysis findings.

  • Provide malware information if identified.

Note: Some scan types require specific feature licenses to execute. Contact your Black Duck representative for further information.

Bridge CLI client

Bridge is useful when you want a unified CLI for all the security tools offered by Black Duck Software: Polaris, Coverity Connect, Black Duck SCA, Software Risk Manager.

Bridge does all the following:

  • SAST and SCA scanning

  • Scan in synchronous or asynchronous (non-blocking) mode

  • Scan whenever new code is merged to a branch

  • Scan whenever a pull request is created/updated

  • Decorate PRs with comments

  • Create Fix PRs (Black Duck SCA only)

  • Generates a SARIF file

  • Post results to SCM (GitHub advanced security)

  • Post results to any supported server (see the list of products above).

For more information see, Bridge documentation.

Note: Bridge can do any of the above in an air gapped environment. See the individual tool pages for more information.

Plug-in integrations

Plug-ins are the easiest way to integrate testing into your CI/CD pipeline. Choose from CI/CD plug-in integrations derived from either of the CLI clients above: Detect or the Bridge CLI.

Detect-based CLI plug-ins

Jenkins

The Detect Extension for Jenkins enables you to install and run Black Duck Detect in your Jenkins instance.

Capabilities include:

  • Performing compositional analysis and functioning as a Black Duck intelligent scan client.

  • Sending scan results to your Black Duck SCA server, which generates risk analysis when identifying open source components, licenses, and security vulnerabilities.

  • Running Detect as either of the following:

    • A post-build action in a Jenkins Freestyle job.

    • Pipeline step using a Pipeline script in a Pipeline job.

Azure

The Detect Extension for Azure DevOps is designed to integrate Black Duck Detect seamlessly into Azure DevOps build and release pipelines.

It includes the ability to:

  • Run a component scan in an Azure DevOps job.

  • Create projects and releases in Black Duck SCA through the Azure DevOps job.

  • Make results available on the Black Duck SCA server.

GitHub

The Detect GitHub Action plug-in integrates Black Duck Detect into GitHub action workflows.

Capabilities include all of the following:

  • Run a component scan in a GitHub workflow.

  • Upload results to a project in Black Duck SCA.

  • Configure Detect in either of two modes:

    • Rapid scan mode to get detailed Black Duck policy reports (default behavior)

    • Intelligent scan mode to upload your data into Black Duck for more detailed analysis.

Note: As of October 2024, we recommend using the newer, Bridge-based GitHub Action for creating new pipelines, rather than Detect GitHub Action.

Bridge-based CI Plug-ins

Our latest plug-ins are built with the Bridge CLI Client under the hood, so you get the same benefits without writing the code.

Capabilities include:

  • SAST and SCA scanning

  • Scan in synchronous or asynchronous (non-blocking) mode

  • Scan whenever new code is merged to a branch

  • Scan whenever a pull request is created/updated

  • Decorate PRs with comments

  • Create Fix PRs (Black Duck SCA only)

  • Generates a SARIF file

  • Post results to SCM (GitHub advanced security)

  • Post results to any supported server (see the list of products above).

  • Make issues available in your instance of Black Duck SCA, Coverity, Polaris, or SRM.

  • Fail the build in your CI system when a high-severity issue is found.

Bridge plug-ins for Black Duck are available on the following platforms:

API reference

Black Duck APIs offer a convenient way to retrieve ad-hoc information from Black Duck or to perform automated review or workflows. However, customers looking to build out customized views or dashboards using bulk data from Black Duck would be best served by using the Black Duck Reporting DB schema.

Tip: Although APIs offer a way to do most functions that Black Duck UI can do, you might choose the Black Duck Bridge command line interface or an SCM integration for building tests or automation into your pipeline.

After tests run, APIs can help with the following:

  • Generate and download a notices file or SBOM

  • Collate component copyright information

  • Automatically assign issues to developers

  • Add comments to Pull Requests with Black Duck data

To explore what Black Duck SCA APIs have to offer:

  • Access the REST API documentation found in Black Duck SCA by opening the Help menu from the top navigation bar and selecting REST API Developers Guide.

  • Visit the REST API documentation directly at https://<Black Duck Server URL>/api-doc/public.html.

Black Duck REST API Python bindings

This Python library provides a streamlined interface to interact with Black Duck APIs, enabling customers to efficiently automate and customize their workflows. This library is distributed as an open-source extension of Black Duck and is licensed under the Apache 2.0 license.

For more details or to contribute, visit the Black Duck API Python bindings GitHub repository.

Downloading the Black Duck API Specification

Black Duck provides the capability to download the full API specification using either a Postman collection or an OpenAPI Specification (OAS). These options allow customers to directly import the documentation into tools like Postman, simplifying the process of working with the APIs.

  • Postman Collection: You can generate a Postman collection from the API documentation by downloading the postman-collection-public.json file from /api-doc/postman-collection-public.json. This file can be imported into Postman to interact with the Black Duck APIs.

  • OpenAPI Specification (OAS): Similarly, the OpenAPI Specification can be generated via the /api-doc/openapi3-public.json endpoint. This allows you to explore and document the Black Duck API with tools that support OAS.

Integrating Black Duck with Business Intelligence tools

Black Duck offers a Reporting Database (Reporting DB) interface that enables seamless integration with Business Intelligence (BI) tools, such as PowerBI. This interface provides customers with the flexibility to generate custom reports, visualize data, and build comprehensive dashboards that reflect key performance indicators (KPI) and risk management views.

To accelerate the integration process, Black Duck provides sample reports specifically designed for use with PowerBI. These templates serve as an efficient starting point for customers, allowing them to quickly build customizable dashboards using data from Black Duck's Reporting DB.

For more details, visit Black Duck Dashboards using Microsoft Power BI.