Vexcalibur

Vexcalibur turns software bills of materials and vulnerability findings into VEX documents, for the security and release engineers who publish VEX statements alongside an SBOM. It reads CycloneDX SBOMs, SPDX 3 SBOMs, or a GitHub Dependency Graph SBOM. Findings come from an OSV-compatible service or a local file.

Current releases write CycloneDX 1.6, OpenVEX 0.2.0, CSAF 2.0, and SPDX 3.0.1 JSON. CSAF output uses the csaf_vex profile, and SPDX 3 output goes through the security profile's VEX relationships. SPDX 3 output arrived in v0.7.0. This branch also reads local SPDX 3.0.1 JSON-LD SBOMs; no release through v0.7.2 includes that input.

The project is usable, but still pre-1.0. Pin an exact release because command flags, Python APIs, and detailed output may change.

What works today

Install a release

Vexcalibur needs Python 3.10 through 3.14.

python3 -m venv .venv
source .venv/bin/activate
pip install vexcalibur
vexcalibur --help

In PowerShell, the virtual environment puts its commands under Scripts:

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install vexcalibur
vexcalibur --help

With uv, one command handles the environment and there's nothing to activate:

uv tool install vexcalibur

That gives you the latest release, which is what you want to try it out. Vexcalibur is pre-1.0, so pin an exact version in anything you automate. The install guide covers pinning, PATH setup, and how to check which formats your release supports.

Once it's installed, generate your first document against your own SBOM.

Try local generation from a checkout

Use this path to work on Vexcalibur itself, or to run unreleased output formats. Clone the repository, then install its locked dependencies:

uv sync --frozen

Installing the dependencies may reach the configured package index. The generate command below uses only local inputs, so it never reaches a vulnerability service.

Generate a VEX document from the committed example files:

uv run --frozen vexcalibur generate \
  tests/fixtures/sbom/cyclonedx-json-simple.json \
  --offline \
  --findings-file tests/fixtures/findings/all-analysis-states.json \
  --timestamp 2026-06-23T00:00:00Z \
  --output /tmp/vexcalibur-vex.json

Check the result:

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

vex = json.loads(Path("/tmp/vexcalibur-vex.json").read_text())
assert vex["bomFormat"] == "CycloneDX"
assert vex["specVersion"] == "1.6"
assert len(vex["vulnerabilities"]) == 5
print("generated CycloneDX VEX")
PY

See the quickstart for the guided version of this example.

CycloneDX is the default. To write OpenVEX, add --format openvex and name the document author. To write CSAF 2.0, add --format csaf and the document and publisher metadata it needs. The OpenVEX guide and CSAF guide each carry a runnable example and the evidence rules for that format.

Choose a finding source

Vexcalibur needs exactly one finding source per run.

Warning: --allow-public-osv sends package URLs and versions to https://api.osv.dev. Do not use it with a private SBOM or sensitive package inventory unless that disclosure is approved.

Without that flag, the public endpoint fails closed. Fetching an SBOM from GitHub crosses a separate network boundary; it doesn't give Vexcalibur permission to send the resulting inventory to public OSV.

Documentation

The complete manual is at vexcalibur-dev.github.io/vexcalibur.

Getting started

Work through the quickstart, then follow the CycloneDX, OpenVEX, CSAF, or SPDX 3 generation guide. Check project status for current limits.

Running it

The CLI reference covers flags and failure behavior. Read the CycloneDX, OpenVEX, CSAF, or SPDX 3 output contract before consuming generated files.

Embedding it

The Python API guide and API reference cover the supported facade. Read the provider contract and renderer contract before adding an integration, and the architecture before adding a source or output format.

Execution reports

The execution report reference covers the machine-readable generation metadata, and the Python report guide covers the cross-platform API. Both describe the default branch, so verify that your release lists --execution-report in vexcalibur generate --help first. The CLI report transaction supports Linux and macOS; Windows embeddings build and validate the same report through the Python facade.

Contributing

The complete local gate runs on Linux and needs the host tools listed in Reproduce important gates. That guide includes exact portable commands for macOS and Windows. Required pull-request CI runs the Linux-only checks.

On Linux, refresh the base branch and run the quality and coverage gates from the repository root:

git fetch origin main
make check
make coverage COVERAGE_COMPARE_REF=origin/main

Documentation changes must also build without warnings:

uv sync --frozen --extra docs
make docs

Parser, source-client, package-URL, and terminal-safety changes must also run the deterministic fuzz smoke profile:

make fuzz-smoke

See the contribution guide and the security policy before opening a pull request. The contributor documentation collects the style policy, fuzzing guide, CI layout, and governance checks.

Use the issue forms for questions, bugs, and feature requests. The organization support policy explains which public route to use, and the code of conduct applies to project spaces.

Vexcalibur is licensed under the Apache License 2.0.