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.

Current releases write CycloneDX 1.6, OpenVEX 0.2.0, and CSAF 2.0 JSON. CSAF output uses the csaf_vex profile. This branch also writes SPDX 3.0.1 JSON-LD through the security profile's VEX relationships; no release through v0.6.3 includes it.

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

Open the release page and choose an exact version. The commands prompt for that version so an unresolved placeholder cannot reach pip:

set -euo pipefail

read -r -p "Vexcalibur version from the release page: " VEXCALIBUR_VERSION
if [[ ! "$VEXCALIBUR_VERSION" =~ ^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$ ]]; then
  printf 'Enter a MAJOR.MINOR.PATCH release version\n' >&2
  exit 2
fi
VEXCALIBUR_VENV=".venv-vexcalibur-${VEXCALIBUR_VERSION}"
if [[ -e "$VEXCALIBUR_VENV" ]]; then
  printf 'Refusing to reuse %s\n' "$VEXCALIBUR_VENV" >&2
  exit 2
fi
python -m venv "$VEXCALIBUR_VENV"
"$VEXCALIBUR_VENV/bin/python" -m pip install \
  "vexcalibur==${VEXCALIBUR_VERSION}"
INSTALLED_VERSION="$("$VEXCALIBUR_VENV/bin/python" -c \
  'from importlib.metadata import version; print(version("vexcalibur"))')"
test "$INSTALLED_VERSION" = "$VEXCALIBUR_VERSION"
"$VEXCALIBUR_VENV/bin/vexcalibur" --help

In PowerShell 7.3 or newer, use:

$ErrorActionPreference = "Stop"
$PSNativeCommandUseErrorActionPreference = $true
$VEXCALIBUR_VERSION = Read-Host "Vexcalibur version from the release page"
if ($VEXCALIBUR_VERSION -notmatch '^(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})\.(0|[1-9][0-9]{0,5})$') {
    throw "Enter a MAJOR.MINOR.PATCH release version"
}
$VEXCALIBUR_VENV = ".venv-vexcalibur-$VEXCALIBUR_VERSION"
if (Test-Path -LiteralPath $VEXCALIBUR_VENV) {
    throw "Refusing to reuse $VEXCALIBUR_VENV"
}
py -m venv $VEXCALIBUR_VENV
$PYTHON = Join-Path $VEXCALIBUR_VENV "Scripts/python.exe"
$VEXCALIBUR = Join-Path $VEXCALIBUR_VENV "Scripts/vexcalibur.exe"
& $PYTHON -m pip install "vexcalibur==$VEXCALIBUR_VERSION"
$INSTALLED_VERSION = & $PYTHON -c `
    'from importlib.metadata import version; print(version("vexcalibur"))'
if ($INSTALLED_VERSION -ne $VEXCALIBUR_VERSION) {
    throw "Installed $INSTALLED_VERSION instead of $VEXCALIBUR_VERSION"
}
& $VEXCALIBUR --help

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.
• Use the Python API guide and API reference when embedding Vexcalibur.
• The default-branch execution report reference covers machine-readable generation metadata. The Python report guide covers the cross-platform API. Before using either path, verify that the selected release contains the report API or lists --execution-report in vexcalibur generate --help.
• The CLI report transaction supports Linux and macOS. Windows embeddings can construct and validate the same report through the supported Python facade.
• Read the provider contract and renderer contract before adding an integration.
• 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

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, run the 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 the contribution guide, 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.