Python API Reference¶

The Python API is usable by Vexcalibur’s CLI and tests, but public import paths and return shapes can still change before a stable 1.0 compatibility policy.

Domain Objects¶

Provider-neutral Vexcalibur domain objects.

class vexcalibur.domain.VexAnalysisState(*values)¶

Bases: str, Enum

CycloneDX VEX analysis states supported by the domain model.

class vexcalibur.domain.ComponentIdentity(ref, name, version, purl, type='library')¶

Bases: object

Minimal component data needed by vulnerability sources and VEX output.

Parameters:

ref (str)
name (str)
version (str | None)
purl (PackageURL)
type (str)

class vexcalibur.domain.VulnerabilityFinding(id, source_name, source_url, component_ref, purl, modified=None, analysis_state=VexAnalysisState.IN_TRIAGE, analysis_detail='Detected by vulnerability source; manual exploitability analysis required.')¶

Bases: object

Provider-neutral vulnerability finding for one affected component.

Parameters:

id (str)
source_name (str)
source_url (str)
component_ref (str)
purl (str)
modified (datetime | None)
analysis_state (VexAnalysisState)
analysis_detail (str)

exception vexcalibur.domain.VulnerabilitySourceError¶

Bases: RuntimeError

Base error raised by provider-neutral vulnerability sources.

exception vexcalibur.domain.VulnerabilitySourceInputError¶

Bases: VulnerabilitySourceError, ValueError

Raised when source-specific findings cannot be produced from the input components.

class vexcalibur.domain.VulnerabilitySource(*args, **kwargs)¶

Bases: Protocol

Provider-neutral contract for vulnerability finding sources.

findings_for_components(components)¶

Return VEX-ready vulnerability findings for SBOM components.

Return type:: tuple[VulnerabilityFinding, ...]
Parameters:: components (tuple[ComponentIdentity, ...])

SBOM Ingest¶

Use load_cyclonedx_sbom for untrusted CycloneDX files. It applies Vexcalibur’s size limits, XML parser hardening, component limits, and duplicate-reference checks before returning component identities. load_cyclonedx_json is the JSON-only compatibility helper. component_identities_from_github_spdx_sbom extracts package identities from the SPDX JSON shape returned by GitHub’s Dependency Graph SBOM API and lives in vexcalibur.github_sbom.

SBOM loader contract¶
Loader	Accepted formats	Encodings	Limits and filtering
`load_cyclonedx_sbom`	CycloneDX JSON `1.4`, `1.5`, or `1.6`; CycloneDX XML rooted at `bom` in the `http://cyclonedx.org/schema/bom/1.4`, `/1.5`, or `/1.6` namespace.	JSON must be UTF-8. XML may use parser-detected XML encodings such as UTF-8 or UTF-16.	Files over 10 MiB, more than 10,000 components, nesting deeper than 50 component levels, malformed package URLs, and duplicate returned `bom-ref` values raise `SbomError`. Components without package URLs are ignored.
`load_cyclonedx_json`	CycloneDX JSON `1.4`, `1.5`, or `1.6` only.	UTF-8 JSON.	Applies the same file size, component count, nesting, package URL, and duplicate returned `bom-ref` checks as `load_cyclonedx_sbom`.
`component_identities_from_github_spdx_sbom`	GitHub Dependency Graph SBOM report containing SPDX `2.3` JSON.	Already-decoded Python mapping from a trusted JSON decoder.	Applies the same component count, package URL, and duplicate returned reference checks. Packages without package URL references are ignored, and the repository package reference is not emitted as a component.

These loaders return a tuple of ComponentIdentity values sorted by package URL and component reference. XML input also rejects DTD, entity, and external-reference declarations before component extraction.

CycloneDX SBOM ingestion.

exception vexcalibur.sbom.SbomError¶: Raised when an SBOM cannot be parsed into supported component data.

vexcalibur.sbom.load_cyclonedx_sbom(path)¶

Load supported component identities from a CycloneDX JSON or XML SBOM.

Return type:: tuple[ComponentIdentity, ...]
Parameters:: path (Path)

vexcalibur.sbom.load_cyclonedx_json(path)¶

Load supported component identities from a CycloneDX JSON SBOM.

Return type:: tuple[ComponentIdentity, ...]
Parameters:: path (Path)

GitHub SBOM Client¶

GithubSbomClient fetches a repository Dependency Graph SBOM from GitHub’s REST API and returns the same ComponentIdentity values used by local SBOM ingest. Public repositories can be fetched without a token, subject to GitHub rate limits. Private repositories and higher rate limits require a token with repository read access; the CLI can source this from common GitHub environment variables or gh auth token.

GitHub Dependency Graph SBOM client.

exception vexcalibur.github_sbom.GithubSbomError¶

Bases: SbomError

Base error raised for GitHub SBOM input failures.

exception vexcalibur.github_sbom.GithubSbomConfigurationError¶

Bases: GithubSbomError

Raised when GitHub SBOM input configuration is invalid.

exception vexcalibur.github_sbom.GithubSbomClientError¶

Bases: GithubSbomError

Raised when GitHub’s SBOM API cannot return usable data.

class vexcalibur.github_sbom.GithubRepository(owner, repo)¶

Bases: object

Parsed GitHub repository owner and name.

Parameters:

owner (str)
repo (str)

property full_name: str¶: Return the OWNER/REPO repository name.

class vexcalibur.github_sbom.GithubSbomClient(*, api_url='https://api.github.com', token=None, timeout=30.0, report_poll_attempts=30, report_poll_interval=1.0, client=None)¶

Bases: object

Client for GitHub’s Dependency Graph SBOM export endpoint.

Parameters:

api_url (str)
token (str | None)
timeout (float)
report_poll_attempts (int)
report_poll_interval (float)
client (httpx.Client | None)

property api_url: str¶: GitHub API base URL used by this client.

component_identities(repository)¶

Fetch and parse repository Dependency Graph SBOM components.

Return type:: tuple[ComponentIdentity, ...]
Parameters:: repository (str)

vexcalibur.github_sbom.component_identities_from_github_spdx_sbom(raw_response, *, source)¶

Extract component identities from GitHub Dependency Graph SPDX JSON.

Return type:

tuple[ComponentIdentity, ...]

Parameters:

raw_response (Any)
source (str)

vexcalibur.github_sbom.parse_github_repository(value)¶

Parse OWNER/REPO repository text.

Return type:: GithubRepository
Parameters:: value (str)

vexcalibur.github_sbom.normalize_github_api_url(value)¶

Normalize and validate a GitHub API base URL.

Return type:: str
Parameters:: value (str)

vexcalibur.github_sbom.resolve_github_token(*, api_url='https://api.github.com', token_env=None, allow_gh_cli=True, environ=None)¶

Resolve a GitHub token from explicit env, standard env, or gh auth token.

Return type:

str | None

Parameters:

api_url (str)
token_env (str | None)
allow_gh_cli (bool)
environ (Mapping[str, str] | None)

VEX Rendering¶

CycloneDX VEX document generation.

exception vexcalibur.vex.VexRenderError¶: Raised when domain findings cannot be rendered as a valid VEX document.

vexcalibur.vex.render_cyclonedx_vex_json(*, components, findings, timestamp=None)¶

Render deterministic CycloneDX VEX JSON for vulnerability findings.

Return type:

str

Parameters:

components (tuple[ComponentIdentity, ...])
findings (tuple[VulnerabilityFinding, ...])
timestamp (datetime | None)

vexcalibur.vex.parse_timestamp(value)¶

Parse an ISO-8601 timestamp for deterministic VEX output.

Return type:: datetime
Parameters:: value (str)

Generation Workflow¶

SBOM-to-VEX generation workflow.

vexcalibur.generate.generate_vex_from_source(*, input_file, source, timestamp=None)¶

Generate CycloneDX VEX JSON from a CycloneDX SBOM and source provider.

Return type:

str

Parameters:

input_file (Path)
source (VulnerabilitySource)
timestamp (datetime | None)

vexcalibur.generate.generate_vex_from_components(*, components, source, timestamp)¶

Generate CycloneDX VEX JSON from component identities and a source provider.

Return type:

str

Parameters:

components (tuple[ComponentIdentity, ...])
source (VulnerabilitySource)
timestamp (datetime | None)

vexcalibur.generate.generate_vex_from_sbom(*, input_file, timestamp=None, osv_client=None, osv_base_url='https://api.osv.dev', allow_public_osv=False)¶

Generate CycloneDX VEX JSON from a CycloneDX SBOM.

Return type:

str

Parameters:

input_file (Path)
timestamp (datetime | None)
osv_client (OsvClient | None)
osv_base_url (str)
allow_public_osv (bool)

vexcalibur.generate.generate_vex_from_github_sbom(*, repository, timestamp=None, github_client=None, osv_client=None, osv_base_url='https://api.osv.dev', allow_public_osv=False)¶

Generate CycloneDX VEX JSON from a GitHub Dependency Graph SBOM.

Return type:

str

Parameters:

repository (str)
timestamp (datetime | None)
github_client (GithubSbomClient | None)
osv_client (OsvClient | None)
osv_base_url (str)
allow_public_osv (bool)

vexcalibur.generate.generate_vex_from_local_findings(*, input_file, findings_file, timestamp=None)¶

Generate CycloneDX VEX JSON from a CycloneDX SBOM and local findings.

Return type:

str

Parameters:

input_file (Path)
findings_file (Path)
timestamp (datetime | None)

OSV Provider¶

The OSV client can contact the public OSV API by default. Library callers should prefer OsvSource, osv_client_for_url, or ensure_osv_url_allowed so public OSV access still requires an explicit opt-in before package URLs or SBOM-derived inventories leave the local environment. generate_vex_from_source delegates policy to the supplied source adapter; custom network sources must enforce their own trust boundary.

OSV API client.

class vexcalibur.sources.osv.OsvVulnerabilitySummary(id, modified=None)¶