Black Duck SCA

This guide outlines practical, step-by-step instructions for integrating Black Duck SCA into your workflow, from initial project setup to CI/CD integration, advanced manual operations, and local IDE scanning.

Prerequisites: You must have Maintainer permissions for your GitLab repository and access to the Black Duck server.

How to Prepare Your Black Duck Project

Before analyzing your source code, you must provision a project space.

1. Log in to your account on the Black Duck server.
2. In the top-right corner of the dashboard, click + Create Project.
3. Enter your Project Name.
4. Enter an initial Version Name (e.g., main, v1.2.0).
5. Fill out the desired fields (like Tier or Phase) and click Save.
6. Ensure your user account (or service account) has Project Code Scanner permissions.

How to Generate and Secure an Authentication Token

Your tools need access to a token to communicate with the server. Never hardcode this token in your source code.

1. Generate the Token:

1. Log in to your Black Duck server.
2. In the top-right menu, select your name, then choose Access Tokens.
3. Click + Create Token, name it, and fill in the form.
4. Copy the generated token.

2. Secure it in GitLab:

1. Go to your GitLab repository Settings > CI/CD.
2. Expand the Variables section and select Add variable.
3. Name the variable BLACKDUCK_TOKEN.
4. Paste your token as the value.
5. Check the Masked and Protected boxes, then select Add variable.

How to Configure Your CI/CD Pipeline

To trigger automated scans, instruct GitLab by updating the .gitlab-ci.yml file. We use the NextGen CI/CD Black Duck step which wraps Synopsys Detect.

1. Go to Code > Repository and open your .gitlab-ci.yml file.
2. Include the shared pipeline definitions and extend the relevant job. For standard source scanning:

include:
  - project: 'nextgen-cicd/config'
    file: 'config.yml'
  - project: 'nextgen-cicd/release'
    file: 'step/blackduck.yml'

variables:
  CICD_BLACKDUCK_TOKEN: $BLACKDUCK_TOKEN
  CICD_BLACKDUCK_PROJECTNAME: my-project

stages:
  - sca

blackduck-detect:
  stage: sca
  extends: .blackduck-detect

Managing Scan Scope (Excluding Directories)

Black Duck scans are meant for production code dependencies. To prevent test dependencies or internal proprietary libraries from skewing your results, you should exclude them using extra options:

(Optional) If you have a Python project and want to restrict detection to pip-managed dependencies only, use this configuration:

blackduck-detect-python:
  stage: sca
  extends: .blackduck-detect
  variables:
    CICD_BLACKDUCK_EXTRA_OPTS: >-
      --detect.tools=DETECTOR
      --detect.included.detector.types=PIP
      --detect.python.path=/usr/bin/python3
      --detect.pip.path=/usr/bin/pip3
  before_script:
    - pip3 install -r requirements.txt

1. Commit your changes. Pushing this file will automatically trigger the pipeline and execute the scan.

How to Review Results and Remediate

Optional Step: Integrate Results into GitLab Dashboards (NextGen CI/CD)
If you prefer to consult vulnerabilities directly within GitLab rather than logging into Black Duck, you can optionally configure your pipeline to retrieve the results . Add the following NextGen CI/CD configuration to your .gitlab-ci.yml:

include:
  - project: nextgen-cicd/config
    file: config.yml # in order to set variable CICD_CATALOG_REGISTRY
  - project: nextgen-cicd/release    # ref: can indicate a version or master by default
    file: 'step/blackduck.yml'

variables:
  CICD_BLACKDUCK_TOKEN: Blackduck API token # store this one in pipeline masked variable to avoid secret leak
  CICD_BLACKDUCK_PROJECTNAME: myprojectname

stages:
  - report

# Retrieves vulnerabilities from the server and imports them into Gitlab dashboards
blackduck-report:
  stage: report
  extends: .blackduck-gitlab-report

Once the pipeline finishes successfully:

1. Log into the Black Duck web UI and open your project version.
2. Review Security Risks: Navigate to the Security tab to identify high/critical vulnerabilities (CVEs/BDSAs). Utilize the BDSA data for exact upgrade guidance.
3. Review Operational Risks: Check the Risk tab for Operational risks (components that are severely outdated or have no recent commit activity). Address these to avoid accumulating third-party Technical Debt.
4. Triage Findings: Update the remediation status for discovered vulnerabilities:
   • New: Needs review.
   • Remediation Required: Acknowledged, waiting for a fix.
   • Mitigated/Ignored: Provide a clear justification if a vulnerability is not exploitable in your specific execution context.
5. Remediate: Update your source code’s manifest files (e.g., bumping a dependency version in package.json or pom.xml) to fix the issues.
6. Commit and push the updated code to re-run the pipeline and verify the fix.

How to Perform a License Analysis and Generate Reports

Ensuring open-source license compliance and generating compliance artifacts is just as critical as fixing vulnerabilities.

1. Reviewing Detected Licenses

1. Open your project version in the Black Duck UI.
2. Navigate to the Components tab.
3. Review the License and License Risk columns.
   • A high risk usually indicates a strict copyleft license (like GPL) that might conflict with proprietary software distribution.
   • Pay special attention to components flagged with policy violations related to banned licenses.

2. Resolving “Unknown” or Unconfirmed Licenses

Sometimes, Black Duck detects a component but cannot confidently determine its license.

1. In the Components tab, locate the component with the “Unknown” license.
2. Click on the component name to open its details.
3. If you have investigated the component’s source repository and know the correct license, click the Edit (pencil) icon next to the license field.
4. Search for the correct license in the KnowledgeBase, select it, and click Save.

3. Generating Reports (Notices, SBOMs, and Vulnerability)

Black Duck provides distinct report formats for legal, compliance, and security tracking.

1. Navigate to your project version and click the Reports tab.
2. Click + Create Report.
3. Choose your required report type:
   • Notices File: Select Text or HTML format. Use this for legal compliance and attribution to be shipped with your product.
   • SBOM (Software Bill of Materials): Select SPDX or CycloneDX format. Use this for supply chain transparency and sharing dependencies with customers.
   • Vulnerability Report: Generates a CSV/HTML detailing all security findings for internal patching prioritization and security audits.
4. Define which components to include (usually “All components”).
5. Click Create. Once generated, download the file.

Advanced Operations

Black Duck Code Sight (IDE Integration)

To detect vulnerable dependencies and license violations as you code, developers can install the Code Sight plugin in their IDE (Visual Studio Code, IntelliJ, etc.).

1. Search for “Code Sight” in your IDE’s extension/plugin marketplace.
2. Install the plugin and authenticate using your Black Duck Server URL and the Access Token you generated earlier. (Please find more informations at the Blackduck Secrets page )
3. The plugin will now suggest safer component versions before you even commit your code.

How to Install the Client and Run a Scan Locally

You can install Synopsys Detect locally when you need to run scans outside CI/CD environments. Ensure your Detect version matches your Black Duck server version.

1. Download and Install (Linux Example):

Install Java runtime

apt-get install --no-install-recommends -y openjdk-11-jdk-headless
Prepare directories and install

mkdir /opt/blackduck 
cp ~/Downloads/synopsys-detect.jar /opt/blackduck/synopsys-detect.jar 
unzip ~/Downloads/scancli.zip -d /opt/blackduck

export SYNOPSYS_SKIP_PHONE_HOME="TRUE"

2. Run a Local Scan:

/usr/bin/java -jar /opt/blackduck/synopsys-detect.jar
--detect.blackduck.signature.scanner.local.path=/opt/blackduck/scancli-VERSION
--blackduck.url=URL
--blackduck.api.token=TOKEN
--detect.project.name=PROJECTNAME
--detect.project.version.name=PROJECTVERSION
--detect.source.path=PATH

How to Upload an SBOM Manually

If running scans entirely offline, you can manually upload an SBOM file directly to the web UI.

1. Go to your Black Duck server and open your project version.
2. Navigate to Settings > Scan > Upload Scan.
3. Drag-and-drop your SBOM file (SPDX or CycloneDX) into the dialog.
4. Confirm the upload. A green “complete” badge confirms success.

How to Track Remediation Across Versions

To avoid repetitive remediation work for similar vulnerabilities across multiple releases, use the version cloning feature.

1. Go to your project homepage in Black Duck, then click Settings.
2. Enable the Remediation Details option.
3. In your project versions list, select the version you want to clone and click Clone.
4. Name your new version (e.g., 1.1.0) and adjust its settings.
5. When you upload scans to this cloned version, previous remediation statuses (like “Ignored” or “Mitigated”) will automatically carry over.