Generate OpenVEX¶

Use vexcalibur generate --format openvex to write OpenVEX 0.2.0 JSON. CycloneDX remains the default when --format is absent.

OpenVEX requires a document author and at least one statement. Some statuses also require explicit evidence fields.

Prerequisites¶

Before you begin:

Install Vexcalibur v0.2.0 or newer. See Install Vexcalibur.
Have a CycloneDX SBOM or supported SPDX 3 input and a reviewed findings file ready. The example calls them sbom.json and findings.json.
Open a Bash-compatible shell.
Confirm that /tmp is writable, or replace the example output path.

This example needs no service credentials and contacts no network service.

Generate from local inputs¶

Confirm that your release supports OpenVEX:

vexcalibur generate --help

The --format choices must include openvex. If they don’t, install a newer release.

The command below reads only local files. It does not contact GitHub or an OSV service.

vexcalibur generate \
  sbom.json \
  --offline \
  --findings-file findings.json \
  --format openvex \
  --author "Example Security Team" \
  --author-role "VEX document producer" \
  --timestamp 2026-06-23T00:00:00Z \
  --output /tmp/vexcalibur-openvex.json

The command should exit with status 0 and print nothing. It writes grouped statements to /tmp/vexcalibur-openvex.json.

Findings that agree on the vulnerability, source, state, and evidence become a single statement listing every affected product, so the statement count can be lower than the finding count. The OpenVEX output reference lists the exact grouping values.

Check the result¶

Confirm the context, the author claim, and that the document carries statements:

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

document = json.loads(Path("/tmp/vexcalibur-openvex.json").read_text())

assert document["@context"] == "https://openvex.dev/ns/v0.2.0"
assert document["author"] == "Example Security Team"
statements = document["statements"]
assert statements
print(f"OpenVEX 0.2.0 document with {len(statements)} statements")
PY

This is a field check, not validation against the full OpenVEX schema. The repository test suite validates generated documents against the pinned official 0.2.0 schema on every change; see the OpenVEX output reference for the exact pin.

To run that schema validation yourself, install from source and use the committed schema at tests/fixtures/schemas/openvex-0.2.0.schema.json with the checkout’s jsonschema dependency.

Supply affected actions¶

Set action_statement when a local finding uses analysis_state: exploitable:

{
  "id": "CVE-2026-0002",
  "component_ref": "pkg:npm/minimist@0.0.8",
  "analysis_state": "exploitable",
  "analysis_detail": "The affected feature is reachable.",
  "action_statement": "Upgrade minimist to version 1.2.8 or later."
}

Vexcalibur maps exploitable to OpenVEX affected. It refuses to use analysis_detail as the action because reachability analysis is not remediation guidance.

Supply status evidence¶

OpenVEX rendering applies these field rules:

Analysis state	OpenVEX status	Required field	Rule
`resolved`	`fixed`	`fixed_version`	Must equal the version in the emitted product package URL.
`exploitable`	`affected`	`action_statement`	Must describe remediation or mitigation.
`in_triage`	`under_investigation`	None	Do not supply an OpenVEX-only evidence field.
`false_positive`	`not_affected`	`impact_statement`	Must explain why the product is not affected.
`not_affected`	`not_affected`	`impact_statement`	Must explain why the product is not affected.

Each evidence field is valid only for the states shown in the table. Vexcalibur does not substitute analysis_detail for one of these fields.

For a resolved finding on pkg:pypi/django@1.2, use the exact product version:

{
  "id": "CVE-2026-0001",
  "component_ref": "component:django",
  "analysis_state": "resolved",
  "analysis_detail": "The installed release contains the fix.",
  "fixed_version": "1.2"
}

For a non-affected finding, state the deployment-specific impact:

{
  "id": "CVE-2026-0005",
  "component_ref": "component:django",
  "analysis_state": "not_affected",
  "analysis_detail": "The affected configuration is disabled.",
  "impact_statement": "The deployment does not enable the affected configuration."
}

Change the inventory or finding source¶

OpenVEX uses the same inventory and finding sources as CycloneDX output. Keep the format and author options, then choose one source mode:

Task	Replace the local source options with
Query a private OSV-compatible service	`--osv-url https://osv.internal.example`
Query public OSV with approved inventory	`--allow-public-osv`
Fetch a GitHub SBOM	Replace the input path with `--github-repo OWNER/REPO`; keep a finding-source option

OSV findings enter the domain as in_triage. They become OpenVEX under_investigation statements.

Warning: --allow-public-osv sends package URLs and versions to https://api.osv.dev. The OpenVEX author options do not change this data-sharing boundary.

See the CycloneDX generation guide for private mirror and GitHub authentication examples. The source flags behave the same for both output formats.

Resolve common failures¶

--author is required with --format openvex means the command cannot identify who makes the statements. Pass an individual or organization that accepts responsibility for the document.

OpenVEX output requires at least one vulnerability finding means the selected source returned no findings. OpenVEX has no standalone empty-document form, so Vexcalibur does not invent a placeholder statement.

requires an action_statement means an exploitable local finding lacks remediation or mitigation text. Add that field or correct the analysis state.

requires an impact_statement means a false_positive or not_affected finding lacks an explicit impact. Add the field or correct the analysis state.

requires fixed_version means a resolved finding does not confirm the fixed product version. Set it to the exact version in the emitted product package URL.

fixed_version ... does not match product means the declared fixed version differs from the emitted product. Correct the inventory or the finding instead of weakening the assertion.

must include a version means the matched component has no version in its package URL or inventory field. Add a precise component version before making an OpenVEX assertion.

overlapping assertions means the input makes different claims about one vulnerability and product. Keep one assertion for that pair. Differences in source, state, detail, evidence, or modification time make assertions distinct.

Read the OpenVEX output reference before publishing or converting the result.