Black Duck SCA
Application Security- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
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
For detailed steps on how to view the data retrieved from Black Duck SCA in the Brinqa Platform, see How to view your data.
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
sinceis 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:
-
Log in to your organization's Black Duck SCA account.
-
Click the User Account menu, and then select Access Tokens from the dropdown.
-
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.
-
-
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.
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
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
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
The Black Duck SCA connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 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 |