Vexcalibur

Vexcalibur turns software bills of materials and vulnerability findings into VEX documents. It reads CycloneDX SBOMs or a GitHub Dependency Graph SBOM. Findings come from an OSV-compatible service or a local file.

Version 0.3.1 writes CycloneDX 1.6, OpenVEX 0.2.0, and CSAF 2.0 JSON. CSAF output uses the csaf_vex profile.

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

Create an environment and pin the package version:

python -m venv .venv
.venv/bin/python -m pip install "vexcalibur==0.3.1"
.venv/bin/vexcalibur --help

On Windows, use .venv\Scripts\python and .venv\Scripts\vexcalibur.

Try local generation

Clone the repository, then install its locked dependencies:

uv sync

Dependency installation may contact the configured package index. The generation command below uses only local inputs and does not contact 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:

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 remains the default output. Add --format openvex and identify the document author to create OpenVEX. Add --format csaf and the required document and publisher metadata to create a CSAF 2.0 VEX document. Follow the OpenVEX guide or CSAF guide for a runnable example and the format's evidence rules.

Choose a finding source

Vexcalibur requires one finding source for each generation 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.

The default public endpoint fails closed without that flag. Fetching an SBOM from GitHub is a separate network boundary and does not grant permission to send the resulting inventory to public OSV.

Documentation

• Start with the quickstart.
• Follow the CycloneDX, OpenVEX, or CSAF generation guide.
• Use the CLI reference for flags and failure behavior.
• Read the CycloneDX, OpenVEX, or CSAF output contract before consuming generated files.
• Read the architecture before adding a source or output format.
• Read the self-release evidence design, inspect a local bundle, or follow the immutable release runbook.
• Check project status for current limits.

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

Contributing

Run the local quality gate:

make check

Documentation changes must also build without warnings:

uv sync --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 CONTRIBUTING.md, the security policy, the fuzzing guide, and the Python style policy before opening a pull request.

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.