No-Network Local Findings Tutorial

This tutorial generates CycloneDX 1.6 VEX JSON from committed fixture files without contacting OSV or any other vulnerability service.

Use this path when you are evaluating Vexcalibur from a private environment, or when another trusted process already produced vulnerability and exploitability findings.

Prerequisites

• Python 3.10 or newer

• uv 0.11.17

• Dependency installation access through PyPI, an internal package index, a populated uv cache, or a prebuilt environment.

Install the project and development dependencies from the repository root:

uv sync

After dependencies are installed, the generation command in this tutorial does not contact OSV or any other vulnerability service.

Confirm that the CLI starts:

uv run --frozen vexcalibur --help

Generate VEX Offline

Run generate with the fixture SBOM and fixture findings file:

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-offline-vex.json

Expected success signal: the command exits with status 0 and writes /tmp/vexcalibur-offline-vex.json.

Verify The Output

Inspect the generated document:

python -m json.tool /tmp/vexcalibur-offline-vex.json | sed -n '1,120p'

Verify stable fields and the expected fixture vulnerability count:

python - <<'PY'
import json
from pathlib import Path

vex = json.loads(Path("/tmp/vexcalibur-offline-vex.json").read_text())
assert vex["bomFormat"] == "CycloneDX"
assert vex["specVersion"] == "1.6"
assert vex["metadata"]["timestamp"] == "2026-06-23T00:00:00+00:00"
assert len(vex["vulnerabilities"]) == 5
print("generated offline CycloneDX VEX")
PY

Expected success signal: the Python verification command prints generated offline CycloneDX VEX.

What The Command Did

--offline --findings-file selects the local findings source. Vexcalibur parses the SBOM locally, matches each finding to an SBOM component by component_ref or unique package URL, and renders CycloneDX VEX. It does not construct an OSV client or send package data to a network provider.

Use the local findings reference when writing your own findings file.