Black Duck SCA

Application Security

Overview

The BlackDuck REST connector integrates with Black Duck SCA (formerly Synopsys Black Duck), a software composition analysis (SCA) platform, via its REST API. It synchronizes code projects, project versions, packages (components and origins), open-source vulnerability findings, and vulnerability definitions into the Brinqa platform.

Data retrieved from Black Duck SCA

Connector Object	Required	Maps to Data Model
Project	Yes	Code Project
Project Version	Yes	Project Version
Component (Package)	Yes	Package
Component Version	Yes	Component Version
Open Source Finding	Yes	Open Source Finding
Open Source Finding Definition	Yes	Open Source Finding Definition

Model relationships

note

For detailed steps on how to view the data retrieved from Black Duck SCA in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select Black Duck SCA from the Connector dropdown and provide the following:

Setting	Required	Default	Description
Server URL	Yes	https://<server_name>	Black Duck SCA server URL
API token	Yes	—	Black Duck SCA user API token
Page size	No	100	Maximum number of records to get per API request
Parallel requests	No	min(4, availableProcessors)	Maximum number of parallel API requests
SSL / TLS	No	false	Skip certificate verification

Authentication

Method

API-token authentication. The connector exchanges a long-lived API token for a short-lived bearer token, then refreshes it as needed (with a 5-minute expiry buffer).

Endpoint

Method	URL
POST	<base-url>/api/tokens/authenticate

Request Headers

Header	Value
Authorization	token <api-token>
Accept	application/vnd.blackducksoftware.user-4+json

Request Body

(empty)

Sample Response

{
  "bearerToken": "eyJhbGciOiJIUzUxMiJ9...",
  "expiresInMilliseconds": 7200000
}

Response Fields

Field	Type	Description
bearerToken	String	Bearer token to use on subsequent requests
expiresInMilliseconds	Long	Token lifetime in milliseconds

Usage

Once authenticated, all subsequent API requests include the bearer token:

Authorization: Bearer <bearerToken>

The token is refreshed automatically when Instant.now() > expirationTimestamp - 300000. Generate API tokens under Black Duck → User Management → My Access Tokens.

---

Sync Behavior

• Parameter: since (Instant) — accepted by the connector as a sync high-water mark.
• Logic: The Black Duck project-list endpoint does not support server-side timestamp filtering, so since is applied as a high-water mark while the connector iterates rather than as a direct API filter. The sync enumerates projects, then walks each project's versions, components, component versions, and vulnerable BOM components. All child models (Project Version, Component, Component Version, Open Source Finding, and Open Source Finding Definition) are gated by this parent project/version enumeration.

---

How to obtain Black Duck SCA credentials

Generate a Black Duck SCA API token

For the Black Duck SCA connector to use the Black Duck API, you must provide an API token. Since Black Duck prohibits retrieving API tokens for existing users, you'll need to generate a new one. To do so, follow these steps:

1. Log in to your organization's Black Duck SCA account.

2. Click the User Account menu, and then select Access Tokens from the dropdown.

3. Click Create Token. The Create Token dialog displays.

   

   Provide the following information:

   • Name: Provide a name for the API token.

   • Description: (Optional) Provide a description for the API token.

   • Scope: Select Read Access Only. The Black Duck connector does not require write access to retrieve data.

4. Click Create.

   The new API token displays. You cannot view the token again. Copy the token and save it in a secure location.

Note: If you do not have the permissions to create an API token, contact your Black Duck SCA administrator. For additional information, see Black Duck documentation.

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Project

Source Field Name	SDM Attribute
constant	CATEGORIES
customField.label → customField.values from /api/projects/{id}/custom-fields	<custom fields>
ProjectMapping.applicationId[] from /api/projects/{id}/project-mappings	APPLICATION_IDS
ProjectResource.description	DESCRIPTION
ProjectResource.id	UID
ProjectResource.lastScanDate	LAST_SCANNED
ProjectResource.name	NAME
ProjectResource.policyStatus	POLICY_STATUS
ProjectResource.projectTier	TIER
Tag.name[] from /api/projects/{id}/tags	TAGS

Project Version

Source Field Name	SDM Attribute
License.licenseDisplay[]	LICENSES
ProjectResource.id	TARGETS
ProjectResource.lastScanDate	LAST_SCANNED
ProjectVersion.createdAt	SOURCE_CREATED_DATE
ProjectVersion.distribution	DISTRIBUTION
ProjectVersion.id	UID
ProjectVersion.nickname	NICK_NAME
ProjectVersion.phase	PHASE
ProjectVersion.releasedOn	RELEASE_DATE
ProjectVersion.source	SOURCE
ProjectVersion.versionName	NAME

Component (Package)

Source Field Name	SDM Attribute
aggregated ProjectResource.id[]	PROJECTS
aggregated ProjectVersion.id[]	PROJECT_VERSIONS
Component.description	DESCRIPTION
Component.id	UID
Component.name	NAME
Component.url	URL
constant	CATEGORIES

Component Version

Source Field Name	SDM Attribute
ActivityData.lastCommitDate	LAST_COMMIT_DATE
aggregated ProjectResource.id[]	PROJECTS
aggregated ProjectVersion.id[]	PROJECT_VERSIONS
ComponentVersion.componentId	COMPONENT_ID
ComponentVersion.componentName	COMPONENT_NAME
ComponentVersion.id	VERSION_ID
ComponentVersion.id + ":" + Origin.id	UID
ComponentVersion.releasedOn	RELEASE_DATE
License.licenseDisplay[]	LICENSES
Origin.externalId	ORIGIN_ID
UID (then overwritten by componentVersionName)	NAME

Open Source Finding

Source Field Name	SDM Attribute
"CWE-" + cweId	WEAKNESSES
[ProjectResource.id, BomComponent.id]	TARGETS
BomComponent.id	COMPONENT_ID
BomComponent.originId	COMPONENT_VERSION_ORIGIN_ID
BomComponent.versionId	COMPONENT_VERSION_ID
Cvss2.baseScore	CVSS_V2_BASE_SCORE
Cvss2.temporalMetrics.score	CVSS_V2_TEMPORAL_SCORE
Cvss2.vector	CVSS_V2_VECTOR
Cvss3.baseScore	CVSS_V3_BASE_SCORE
Cvss3.temporalMetrics.score	CVSS_V3_TEMPORAL_SCORE
Cvss3.vector	CVSS_V3_VECTOR
derived from normalized severity	SEVERITY_SCORE
derived from STATUS	STATUS_CATEGORY
MD5 of [projectVersionId, componentId, componentVersionId, originId, vulnerabilityName]	UID
normalized from remediationStatus	STATUS
normalized from Vulnerability.severity	SEVERITY
parsed Cvss2 metrics	CVSS_V2_AV / _AC / _AU / _CI / _II / _AI / _E / _RL / _RC
parsed Cvss3 metrics	CVSS_V3_AV / _AC / _PR / _UI / _CI / _II / _AI / _E / _RL / _RC
ProjectVersion.id	PROJECT_VERSION_ID
ProjectVersion.versionName	PROJECT_VERSION
Vulnerability.exploitPublishDate	EXPLOIT_PUBLISH_DATE
Vulnerability.publishedDate	PUBLISHED_DATE
Vulnerability.severity	SOURCE_SEVERITY
Vulnerability.solution	RECOMMENDATION
Vulnerability.technicalDescription (fallback: description)	DESCRIPTION
Vulnerability.title (fallback: UID)	NAME
Vulnerability.updatedDate	SOURCE_LAST_MODIFIED
Vulnerability.workaround	WORKAROUND
VulnerabilityWithRemediation.cweId	CWE_IDS
VulnerabilityWithRemediation.remediationCreatedAt	FIRST_FOUND
VulnerabilityWithRemediation.remediationCreatedAt	LAST_FOUND
VulnerabilityWithRemediation.remediationStatus	SOURCE_STATUS
VulnerabilityWithRemediation.vulnerabilityName	TYPE
VulnerabilityWithRemediation.vulnerabilityName	CVE_IDS

Open Source Finding Definition

Source Field Name	SDM Attribute
"CWE-" + cweId	WEAKNESSES
derived from normalized severity	SEVERITY_SCORE
normalized from Vulnerability.severity	SEVERITY
parsed Cvss2	CVSS_V2_VECTOR / _AV / _AC / _AU / _CI / _II / _AI / _E / _RL / _RC / _BASE_SCORE / _TEMPORAL_SCORE
parsed Cvss3	CVSS_V3_VECTOR / _AV / _AC / _PR / _UI / _CI / _II / _AI / _E / _RL / _RC / _BASE_SCORE / _TEMPORAL_SCORE
Vulnerability.exploitPublishDate	EXPLOIT_PUBLISH_DATE
Vulnerability.publishedDate	PUBLISHED_DATE
Vulnerability.severity	SOURCE_SEVERITY
Vulnerability.solution	RECOMMENDATION
Vulnerability.technicalDescription (fallback: description)	DESCRIPTION
Vulnerability.title (fallback: UID)	NAME
Vulnerability.updatedDate	SOURCE_LAST_MODIFIED
Vulnerability.workaround	WORKAROUND
VulnerabilityWithRemediation.cweId	CWE_IDS
VulnerabilityWithRemediation.vulnerabilityName	UID
VulnerabilityWithRemediation.vulnerabilityName	CVE_IDS

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Project

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Project on every run and applies no incremental date filter.

API

• Type: REST

Project Version

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Project Version on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /api/projects/{id}/versions (Accept: application/vnd.blackducksoftware.project-detail-5+json)

Component (Package)

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Component (Package) on every run and applies no incremental date filter.

API

• Type: REST

Component Version

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Component Version on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /api/projects/{projectId}/versions/{versionId}/components

Open Source Finding

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Open Source Finding on every run and applies no incremental date filter.

API

• Type: REST

Open Source Finding Definition

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Open Source Finding Definition on every run and applies no incremental date filter.

API

• Type: REST (same payload as Open Source Finding)

Changelog

Changelog

The Black Duck SCA connector has undergone the following changes:

Version	Description	Migration Steps
3.2.10	No changes in this release.	N/A
3.2.9	No changes in this release.	N/A
3.2.8	No changes in this release.	N/A
3.2.7	Improvements - Models now write attributes through the platform's shared, type-validating attribute helper instead of connector-local helpers. Attribute values are now validated against the declared schema type at write time, which surfaces type mismatches early rather than silently storing the wrong type. Bug Fixes - Corrected numerous date/time attributes that were being stored as numbers instead of proper timestamps, which caused data integration failures on the affected syncs. The values are now stored as timestamps, matching the connector schema: - Component Version — "Last commit date", "Release date" - Project — "Last scanned" - Project Version — "Release date", "Source created date", "Last scanned" - Open Source Finding and Open Source Finding Definition — "First found", "Last found", "Published date", "Exploit publish date", "Source last modified"	• The date attributes listed above changed from numbers to timestamps. Re-sync the Black Duck (REST) connector to repopulate these records with the corrected type.
3.2.6	Improvements - Connector-sourced attribute values now take precedence over non-connector data channels (manual edits, bulk imports, UI input) when the platform consolidates records, so Synopsys data is no longer overridden by lower-priority sources. Bug Fixes - Corrected the Project Version "Nickname" attribute from a numeric type to text (it is populated with the project version's nickname string).	• Project Version: the "Nickname" attribute changed from numeric to text. Re-sync the Black Duck (REST) connector to repopulate these records with the corrected type.
3.2.5	No changes in this release.	N/A
3.2.4	No changes in this release.	N/A
3.2.3	No changes in this release.	N/A
3.2.2	No changes in this release.	N/A
3.2.1	No changes in this release.	N/A
3.2.0	No changes in this release.	N/A
3.1.2	No changes in this release.	N/A
3.1.1	No changes in this release.	N/A
3.1.0	No changes in this release.	N/A
3.0.5	No changes in this release.	N/A
3.0.4	No changes in this release.	N/A
3.0.3	New Features - Added a "Source status" attribute to Open Source Findings, carrying the raw remediation status reported by Black Duck alongside the normalized status.	N/A
3.0.2	No changes in this release.	N/A
3.0.1	New Features - Introduced the full Open Source Finding and Open Source Finding Definition models, synchronizing component vulnerabilities discovered by Black Duck along with their shared definitions. Improvements - Built out the Component, Component Version, Project, and Project Version schemas with their attributes (including component and version identifiers, project version linkage, and properly typed date/time fields such as last commit date and release date).	N/A
3.0.0	Overview The Black Duck (REST) connector integrates with Black Duck (Synopsys) over its REST API to synchronize open source software composition analysis data, including projects, their versions, the components they use, and the open source vulnerability findings against those components. Category: Application Security Models	N/A