Skip to main content

Black Duck

Bring your software composition analysis (SCA) results from Black Duck SCA (formerly Black Duck Hub) into the JupiterOne graph: the projects Black Duck tracks, each project's versions with their lifecycle phase and distribution, the open-source and third-party components in each version's bill of materials (BOM) with their license names, and the known vulnerabilities on those components, with severity, numeric score, CVE and CWE identifiers, and the remediation status Black Duck records for each project version. Use it to find which released project versions still carry open critical or high vulnerabilities, see every project version that ships a given component or is affected by a given CVE, and tell findings that are still open from those already marked patched, mitigated or ignored in Black Duck. The integration works with hosted and self-managed Black Duck instances, reads data only, and never changes anything in Black Duck.

Installation​

This integration connects to Black Duck SCA (formerly Black Duck Hub) using the Black Duck REST API (https://<your-black-duck-host>/api/...) and ingests projects, project versions, the components in each version's bill of materials (BOM), and the known vulnerabilities on those components. Black Duck can be hosted by Black Duck or deployed in your own environment, so the integration supports both ways of running it. It can run in the JupiterOne cloud when your Black Duck instance is reachable from the internet, or on a JupiterOne collector inside your network when the instance is only reachable internally. For self-managed instances that use a self-signed or internal-CA TLS certificate, you can supply the CA certificate.

Prerequisites​

  • A Black Duck SCA instance, hosted or self-managed, and its base URL, for example https://blackduck.example.com.
  • A Black Duck user account that can view the projects you want to ingest, and an access token for that user.
  • Network access from where the integration runs to the Black Duck instance: from the JupiterOne cloud for an internet-reachable instance, or from a JupiterOne collector for an instance that is only reachable inside your network.
  • Access to JupiterOne with permission to configure integrations.

Configuration in Black Duck​

The integration authenticates in two steps, as described in the Black Duck API documentation:

  1. It sends your access token to POST /api/tokens/authenticate in the header Authorization: token <access-token>.
  2. Black Duck returns a short-lived bearer token, which the integration sends as Authorization: Bearer <bearer-token> on every other request. When the bearer token expires, the integration requests a new one.

Every other request is a GET. The integration never writes to Black Duck.

Choose the account​

Black Duck access tokens have the same role as the user who created them, so the integration can see exactly what that user can see. Projects the user cannot view are not returned by the API and are not ingested. We recommend a dedicated user that has:

  • The Global Project Viewer global role. Black Duck describes it as read-only access to all projects, with permission to view all projects and BOMs, but not to modify BOMs or project settings.

To limit ingestion to some projects only, you can instead leave the user without global roles and give it the Project Viewer project role ("read-only access to assigned projects") on just those projects.

The integration does not need any role that changes data, such as Project Manager, BOM Manager or Security Manager. Black Duck describes Security Manager as managing vulnerability remediation, which the integration never does.

caution

The Authorization information generated for this integration lists Security Manager next to Global Project Viewer for the Vulnerabilities data source. Start with Global Project Viewer only. If the Vulnerabilities data source fails with a 403 Forbidden error while Projects and Components succeed, the user cannot read vulnerability data on your instance, and you need to review its roles.

Create the access token​

Access tokens can only be created by the user they belong to, so sign in to Black Duck as the dedicated user.

  1. From the user menu in the top navigation bar, select My Access Tokens.
  2. Click Create New Token.
  3. Enter a name and, optionally, a description. For the scope, select read access only. The integration does not need write access.
  4. Click Create, then copy the token. Black Duck shows the token value only once. Store it somewhere safe; you will paste it into JupiterOne.
  5. Click Close.

Black Duck access tokens do not expire, but:

  • A Black Duck user administrator can purge tokens that have been inactive for a set number of weeks, or purge all tokens. Running the integration on a polling interval keeps the token in use.
  • Deactivating the user invalidates its tokens.

If the token is purged or invalidated, the integration stops ingesting until you add a new token to the instance.

Configuration in JupiterOne​

To install the Black Duck integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Black Duck. Click New Instance to begin configuring your integration.

Creating an instance requires the following:

  • The Account Name used to identify the Black Duck account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • If your Black Duck instance cannot be reached from the internet, set the instance to run on a JupiterOne collector in your network.

  • The Authentication fields below.

Authentication fields​

FieldRequiredDescription
Black Duck URLYesThe base URL of your Black Duck instance, including https://, for example https://blackduck.example.com. Do not add /api. Trailing slashes are removed.
API TokenYesThe access token created above. It is exchanged for a bearer token at POST /api/tokens/authenticate.

When you save the instance, JupiterOne checks the credentials by exchanging the access token for a bearer token and reading GET /api/current-version. This confirms that the token is valid and the instance is reachable. It does not check which projects the user can view.

Connection Options​

Both options are optional. They are only needed for a self-managed Black Duck instance whose TLS certificate is not signed by a publicly trusted certificate authority.

FieldDefaultDescription
Disable TLS Certificate VerificationOffSkip TLS certificate verification for the Black Duck instance. Not recommended: use CA Certificate instead.
CA CertificateEmptyThe PEM-encoded certificate of the CA that signed your Black Duck instance's TLS certificate. Used to verify a self-signed or internal-CA certificate.

Filters​

All filters are optional. Leave them empty to ingest everything the user can view.

FieldDefaultDescription
Project Version PhasesEmpty (all phases)Ingest only project versions in these phases. Options are Planning, Development, Pre-release, Released, Deprecated and Archived. Components and vulnerabilities are read only for the project versions that are ingested. When set, project versions with no phase are skipped.
Vulnerability SeveritiesEmpty (all severities)Ingest only vulnerabilities at these severities. Options are Critical, High, Medium and Low. When set, vulnerabilities with no severity are skipped.

Click Create once all values are provided to finalize the integration.

Both filters are applied by the integration after the data is read, not by the Black Duck API:

  • Project Version Phases still lists every version of every project, but components and vulnerabilities are only requested for the versions that match. Setting it to, for example, Released reduces the number of requests on instances with many development versions.
  • Vulnerability Severities does not reduce the number of requests. Every vulnerable component is still read, and the ones outside the selected severities are dropped.
caution

Narrowing a filter later removes data from JupiterOne. On the next run, project versions that no longer match Project Version Phases are deleted from the graph together with their vulnerabilities and their links to components, and vulnerabilities that no longer match Vulnerability Severities are deleted as well.

Data Sources​

Each data source can be enabled or disabled on its own. All data sources are disabled by default, so enable the ones you want to ingest. The blackduck_account entity for the Black Duck instance and the blackduck_service entity are always created, even with every data source disabled.

Data SourceDescriptionEntities Created
ProjectsProjects tracked in Black Duck, with their name, description and created and updated dates, and each project's versions, with their phase, distribution and created date. Project versions are limited by Project Version Phases when set.blackduck_project, blackduck_project_version
ComponentsThe open-source and third-party components in the BOM of each ingested project version, with their name, version and license names. Requires Projects.blackduck_component
VulnerabilitiesKnown vulnerabilities on the components of each ingested project version, with their severity, numeric score, CVE and CWE identifiers, source (for example NVD or BDSA), published date and remediation status. Limited by Vulnerability Severities when set. Requires Projects. Components is not required.blackduck_vulnerability, blackduck_component

To ingest everything the integration supports, enable all three data sources.

caution

Projects must be enabled for any other Black Duck data to be ingested. Components and vulnerabilities are read per project version, and project versions belong to the Projects data source. If Projects is disabled, the Components and Vulnerabilities data sources do not run at all, even when they are enabled.

Vulnerabilities does not depend on Components. When Components is disabled, Vulnerabilities still creates a blackduck_component entity, with its name and version, for each component that has a vulnerability, so that the vulnerability can be linked to its component. It does not create the blackduck_project_version HAS blackduck_component relationship, and components without vulnerabilities are not ingested.

Relationships are built only when every data source they need is enabled:

RelationshipRequires
blackduck_account PROVIDES blackduck_serviceAlways created
blackduck_account HAS blackduck_projectProjects
blackduck_project HAS blackduck_project_versionProjects
blackduck_project_version HAS blackduck_componentProjects and Components
blackduck_project_version HAS blackduck_vulnerabilityProjects and Vulnerabilities
blackduck_component HAS blackduck_vulnerabilityProjects and Vulnerabilities
blackduck_service IDENTIFIED blackduck_vulnerabilityProjects and Vulnerabilities

The blackduck_project_version HAS blackduck_component relationship describes how that project version uses the component. It carries the component's usages, policyStatus and reviewStatus in that version's BOM.

Components and vulnerabilities in the graph​

  • A component is shared across project versions. Each component name and version, for example log4j-core 2.14.1, is one blackduck_component entity, linked to every ingested project version whose BOM contains it. BOM entries without a resolved component version are skipped.
  • A vulnerability is scoped to one project version. Black Duck records the remediation status of a vulnerability separately in each project version, so the same CVE on the same component appears as one blackduck_vulnerability per affected project version, each with its own remediationStatus.
  • Remediated vulnerabilities are ingested too. open is false when the remediation status is PATCHED, MITIGATED, IGNORED, REMEDIATION_COMPLETE or DUPLICATE, and true otherwise. Filter on open = true to see what still needs work.
  • CVE and BDSA advisories. When a vulnerability is a CVE, or a Black Duck Security Advisory (BDSA) linked to a CVE, the entity has the classes Finding and Vulnerability and its cveId is set. A BDSA advisory without a related CVE has only the Finding class.
  • Severity and score. severity is normalized to critical, high, medium or low. numericSeverity is the vulnerability's overall score from Black Duck, or its base score when no overall score is reported.

Example queries​

Open critical and high vulnerabilities in released project versions:

FIND blackduck_project_version WITH phase = 'RELEASED' AS v
  THAT HAS blackduck_vulnerability WITH open = true AND severity = ('critical' or 'high') AS f
RETURN v.displayName, f.displayName, f.severity, f.remediationStatus

Every project version affected by a given CVE:

FIND blackduck_project_version
  THAT HAS blackduck_vulnerability WITH cveId = 'CVE-2021-44228'

Every project version that ships a given component (requires Components):

FIND blackduck_project_version AS v
  THAT HAS blackduck_component WITH name = 'log4j-core' AS c
RETURN v.displayName, v.phase, c.displayName

What the integration does not collect​

  • Users, groups, and their roles.
  • Policy rules and policy violations. Only each component's policyStatus in a project version is recorded.
  • Licenses as separate entities, license risk, and license obligations. Only license names are recorded on components.
  • Scans, code locations, and the files in which components were found.
  • Remediation comments and the Black Duck users who created or changed a remediation status.
  • Vulnerability reports, notifications, and project tags.

Rate limits and request volume​

The integration makes requests in this order: the projects list, then the versions of each project, then, for each ingested project version, its BOM components (Components) and its vulnerable BOM components (Vulnerabilities). Lists are read 100 items per page. On an instance with many projects and versions, most requests come from the per-version BOM reads, so each run takes longer as the number of ingested project versions grows. Use Project Version Phases to reduce it.

The integration does not throttle its own requests. When Black Duck answers with 429 Too Many Requests or a 5xx error, the integration makes up to three attempts with an increasing delay between them, and waits for the time in the Retry-After header when Black Duck sends one.

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.

Additional resources​