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.

Vexcalibur 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

Run in CI

The companion GitHub Action runs Vexcalibur in GitHub Actions. Its release tags are permanent, and the current release workflow creates immutable GitHub Releases. The Action's compatibility reference explains the legacy releases and shows how to resolve the latest tested Action commit and Vexcalibur package.

The CircleCI orb README owns its current release status and supported references. Treat any development reference as mutable and use it only to inspect the interface. Do not import a development reference into a CircleCI project with environment variables, contexts, private source, or other credentials. Orb issue #22 records the App-backed production automation plan.

Install a release

Choose an exact release that is available in the PyPI release history. Review the corresponding GitHub Release, then replace X.Y.Z below with that release number:

python -m venv .venv
.venv/bin/python -m pip install "vexcalibur==X.Y.Z"
.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 Python API how-to to generate and verify VEX from application code.
• Follow the CycloneDX, OpenVEX, or CSAF generation guide.
• Use the CLI reference for flags and failure behavior.
• Use vexcalibur.api as the supported application and extension entrypoint. Its Python reference, provider contract, and renderer contract define the 1.x compatibility surface.
• 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.