vexcalibur 0.2.0

Generate and transform VEX documents from SBOMs and vulnerability data sources.

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.

Published version 0.1.1 writes CycloneDX 1.6 VEX JSON. The current source tree also writes OpenVEX 0.2.0 JSON.

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

Area	Support
SBOM input	CycloneDX JSON and XML 1.4–1.6; GitHub Dependency Graph SPDX 2.3 JSON
Finding sources	Public OSV with explicit consent; private OSV-compatible endpoints; local findings files
VEX output	CycloneDX 1.6 JSON in published version 0.1.1; OpenVEX 0.2.0 JSON in the current source tree
Automation	A companion GitHub Action
Migration	A narrow vexy command-line compatibility layer
Python	3.10–3.14

Install a release

Create an environment and pin the package version:

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

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

Published version 0.1.1 does not include OpenVEX. Use the source checkout below to try it before the next release.

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. The source checkout can create OpenVEX when you add --format openvex and identify the document author. Follow the OpenVEX guide for a runnable example and its stricter finding rules.

Choose a finding source

Vexcalibur requires one finding source for each generation run.

Inventory and trust boundary	Use
Findings already exist locally	Use --findings-file findings.json. Add --offline for a local SBOM.
Inventory may go to an internal service	--osv-url https://osv.internal.example
Inventory is approved for public OSV	--allow-public-osv

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 or OpenVEX generation guide.
• Use the CLI reference for flags and failure behavior.
• Read the CycloneDX or OpenVEX output contract before consuming generated files.
• Read the architecture before adding a source or output format.
• 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

See CONTRIBUTING.md, the security policy, 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.