Generate VEX from Python

Use vexcalibur.api when an application needs to generate VEX without invoking the command-line interface. This example stays offline: it reads a CycloneDX SBOM and reviewed findings from the Vexcalibur test fixtures.

Prepare the checkout

Run the example from a Vexcalibur source checkout. Install the locked project environment first:

uv sync --frozen

The example uses only the supported facade. It catches the documented input, source, and rendering errors before it writes output.

"""Generate and verify a VEX document through the supported Python API."""

from __future__ import annotations

import json
from pathlib import Path

from vexcalibur.api import (
    LocalFindingsError,
    SbomError,
    VexRenderError,
    generate_vex_from_local_findings,
)

REPOSITORY_ROOT = Path(__file__).resolve().parents[2]


def main(output_path: Path = Path("build/vexcalibur-python-api.json")) -> None:
    """Generate the example document and fail when its result is incomplete."""
    try:
        document = generate_vex_from_local_findings(
            input_file=REPOSITORY_ROOT / "tests/fixtures/sbom/cyclonedx-json-simple.json",
            findings_file=REPOSITORY_ROOT / "tests/fixtures/findings/all-analysis-states.json",
        )
    except (LocalFindingsError, SbomError, VexRenderError) as exc:
        raise SystemExit(f"VEX generation failed: {exc}") from exc

    parsed = json.loads(document)
    vulnerabilities = parsed.get("vulnerabilities")
    if not isinstance(vulnerabilities, list) or len(vulnerabilities) != 5:
        raise SystemExit("VEX generation returned an unexpected finding count")

    try:
        output_path.parent.mkdir(parents=True, exist_ok=True)
        output_path.write_text(document, encoding="utf-8")
    except OSError as exc:
        raise SystemExit(f"Could not write {output_path}: {exc}") from exc

    print(f"Wrote {len(vulnerabilities)} findings to {output_path}")


if __name__ == "__main__":
    main()

Generate and verify the document

Run the checked-in example:

uv run --frozen python docs/examples/use_python_api.py

A successful run prints:

Wrote 5 findings to build/vexcalibur-python-api.json

Confirm that the output is CycloneDX 1.6 JSON with five vulnerability entries:

uv run --frozen python - <<'PY'
import json
from pathlib import Path

document = json.loads(
    Path("build/vexcalibur-python-api.json").read_text(encoding="utf-8")
)
assert document["bomFormat"] == "CycloneDX"
assert document["specVersion"] == "1.6"
assert len(document["vulnerabilities"]) == 5
print("CycloneDX 1.6 VEX contains 5 findings")
PY

Use application paths in place of the two fixture paths. Keep imports under vexcalibur.api; implementation modules can change outside the 1.x compatibility contract.

To query an OSV-compatible service instead of reviewed local findings, use generate_vex_from_sbom. Public OSV remains blocked until the call includes allow_public_osv=True. See Use a private OSV mirror before sending a private inventory to any service.

When the embedding also needs counts and a digest for the exact rendered bytes, follow Generate an execution report from Python.