Vexcalibur

Vexcalibur turns SBOM package inventories and vulnerability findings into VEX documents. It reads CycloneDX files, SPDX 3 files, or a GitHub Dependency Graph SBOM, collects findings from OSV-compatible services or local JSON, and writes CycloneDX 1.6, OpenVEX 0.2.0, CSAF 2.0, or SPDX 3.0.1 JSON.

Public OSV access fails closed. Vexcalibur sends package URLs and versions to https://api.osv.dev only when a command includes --allow-public-osv.

Vexcalibur is pre-1.0. Pin an exact release and review the project status before depending on a public contract.

New here? Install a release, then work through the quickstart.

Using Vexcalibur

These pages are for people generating VEX documents rather than changing Vexcalibur itself.

Tutorials

Start here if you haven’t used Vexcalibur before. Both work from a source checkout rather than an installed release, so you get the same inputs and the same output they describe.

• Generate your first VEX document

• Write and use a local findings file

How-to guides

One task each. Most call an installed vexcalibur against your own SBOM, so follow Install Vexcalibur first if you haven’t:

• Generate CycloneDX VEX

• Generate OpenVEX

• Generate CSAF VEX

• Generate SPDX 3 VEX

• Use an SPDX 3 SBOM as input

• Use a private OSV mirror

Three need a source checkout instead, because they run committed example scripts or validate against the repository’s schema:

• Generate VEX from Python

• Generate an execution report from Python

• Consume a generation execution report

Reference

Field-by-field contracts for the command line, the Python API, the input and output formats, and the two extension points.

• Command-line interface

• Compatibility policy

• Python API

• CycloneDX VEX output

• OpenVEX output

• CSAF output

• SPDX 3 output

• Generation execution report

• Local findings format

• Vulnerability-source provider contract

• VEX renderer contract

Explanation

Why Vexcalibur is built the way it is, and what it does and doesn’t promise yet.

• Architecture and trust boundaries

• Project status and compatibility

Running Vexcalibur in CI

• GitHub Actions uses the released companion Action to run Vexcalibur in a workflow.

• CircleCI uses the released companion Orb. Its README covers registry setup and production use. Treat any development reference as mutable and inspection-only. Do not import one into a project with environment variables, contexts, private source, or other credentials.

The GitHub Action’s compatibility reference explains how to resolve its latest tested commit and Vexcalibur package. The Orb’s interface reference documents its parameters and failure behavior; its consumer check verifies published components and execution-report artifacts in CircleCI.

Contributing to Vexcalibur

Separate from the guides above: how this repository is tested, released, and governed. The contributor documentation covers the style policy, fuzzing guide, CI layout, governance checks, and release runbooks.