Black Duck SCA API client

Standalone Python client library for Black Duck BDSCA and BDBA APIs.

This package provides a typed, composable API client for common Black Duck BDSCA workflows such as:

• project and version management
• BOM and component queries
• vulnerability and policy queries
• report generation and download
• scan orchestration (binary, container, SBOM, BDIO)
• users, groups, system, jobs, and custom fields

Requirements

• Python 3.13

Installation

Using pip or uv

Install from local source:

pip install .

uv pip install .

Or install in editable mode for development:

pip install --editable .

uv sync

Quick Start

1) Initialize client and authenticate

from blackduck.bdsca.client import BDScaClient

HOST = "https://your-blackduck.example.com"
TOKEN = "your-api-token"

client = BDScaClient.from_params(
	host=HOST,
	token=TOKEN,
	max_requests_per_sec=10,
)

# Exchange token for bearer auth and store it in session headers
client.authenticate()

## Call a few common endpoints

# Current user
me = client.users.get_current_user()
print("Current user:", me.user_name)

# System status
health = client.system.liveness_check()
print("Liveness:", health.status)

# List projects (first page)
projects = client.projects.list_projects(limit=10)
for p in projects.items:
	print(p.project_id, p.name)

Client Structure

The top-level BDScaClient exposes domain clients as attributes:

• client.projects
• client.projectgroups
• client.codelocations
• client.components
• client.customfields
• client.jobs
• client.licenses
• client.policies
• client.reports
• client.scans
• client.snippets
• client.system
• client.users
• client.usergroups
• client.vulnerabilities

The public BDSCA and BDBA documentation at the https://docs.blackduck.com needs no login, so it has its own client, the blackduck.docs.DocumentationClient, with the search() and the get_topic_as_markdown(). The site is a Fluid Topics portal, and the client calls its web services.

A BDSCA instance from 2026.1.0 can have the "AI Assisted Documentation", a Coveo IPX search of the same documentation. client.system.get_documentation_settings() tells whether it is on, and its settings build a blackduck.docs.CoveoClient, with the search() and the get_answer().

Error Handling

Client methods usually raise requests exceptions via response.raise_for_status() on non-2xx responses.

Typical pattern:

import requests

try:
	client.authenticate()
	projects = client.projects.list_projects(limit=5)
except requests.HTTPError as exc:
	print("HTTP error:", exc)
except requests.RequestException as exc:
	print("Request error:", exc)

Development

Common tasks with just:

just setup-dev
just lint
just test

just test only runs unit tests (mocked, no network). For opt-in tests against a live BDSCA instance, see tests/integration/README.md.

Notes

• Host values with or without scheme are supported; the transport normalizes the host URL.
• Authentication is explicit: call client.authenticate() before making API calls.
• The transport includes resilient adapter wiring for retries, throttling, and reauthentication callback support.