csaf-vex

A Python library for generating, parsing, and validating CSAF VEX files.

Installation

pip install csaf-vex

For development setup, see DEVELOP.md.

Usage

CLI

Read and parse a CSAF VEX file (with verification):

csaf-vex read tests/test_files/sample-vex.json

Read with verbose verification output:

csaf-vex read -v tests/test_files/sample-vex.json

Disable verification:

csaf-vex read --no-verify tests/test_files/minimal-vex.json

Verify a CSAF VEX file:

# Run all verification tests
csaf-vex verify tests/test_files/sample-vex.json

# Run only CSAF compliance tests (Test Set 1)
csaf-vex verify tests/test_files/sample-vex.json --test-set csaf

# Run only data type checks (Test Set 2)
csaf-vex verify tests/test_files/sample-vex.json --test-set data

# Run specific tests by ID
csaf-vex verify tests/test_files/sample-vex.json -t 1.1 -t 2.5

Validate with plugins:

csaf-vex validate tests/test_files/sample-vex.json

See docs/plugins.md for authoring and how the plugin system works.

Python API

from csaf_vex.models import CSAFVEX

# Load from file
csafvex = CSAFVEX.from_file("path/to/document.json")

# Or load from dictionary
import json
with open("vex-file.json") as f:
    data = json.load(f)
csafvex = CSAFVEX.from_dict(data)

# Access document metadata
print(csafvex.document.title)
print(csafvex.document.publisher.name)
print(csafvex.document.tracking.id)

# Access vulnerabilities
for vuln in csafvex.vulnerabilities:
    print(f"CVE: {vuln.cve}")
    if vuln.cwe:
        print(f"  CWE: {vuln.cwe.id}")

# Access product tree
if csafvex.product_tree:
    for branch in csafvex.product_tree.branches:
        print(f"Branch: {branch.name}")

# Serialize back to dictionary
data = csafvex.to_dict()

Validation (Plugins) - Python API

import logging
from csaf_vex.models import CSAFVEX
from csaf_vex.validation.validator import Validator

csafvex = CSAFVEX.from_file("path/to/document.json")

# Create validator; default log level is WARNING
validator = Validator(csafvex, log_level=logging.INFO)

# Run all installed validation plugins
report = validator.run_all()
print(f"Plugins: total={report.total}, passed={report.passed_count}, failed={report.failed_count}")
for r in report.results:
    if not r.success:
        print(f"[{r.validator_name}]")
        for e in r.errors:
            print(f"  - {e.message}")

# Run a subset of plugins by name
subset = validator.run_plugins(["<PLUGIN-NAME>"])
print(f"Subset failed: {subset.failed_count}")

# List available plugin names
from csaf_vex.validation.validator import Validator
print(Validator.get_available_plugins())

For detailed API documentation including working with CVSS scores, PURLs, and more examples, see docs/csafvex-usage.md.

Verification

The library provides comprehensive verification of CSAF VEX documents through two test sets:

• Test Set 1 (CSAF Compliance): 14 tests verifying VEX Profile conformance and CSAF mandatory requirements
• Test Set 2 (Data Type Checks): 16 tests verifying data format compliance, patterns, and schema constraints

Using the Verifier

from csaf_vex.verification import Verifier

# Create verifier from a file
verifier = Verifier.from_file("path/to/vex.json")

# Run all verification tests
report = verifier.run_all()

# Check results
if report.passed:
    print("All verification tests passed!")
else:
    print(f"Failed: {report.failed_count}/{report.total_tests}")
    for failure in report.failures:
        print(f"  {failure.test_id}: {failure.message}")

# Run specific test sets
csaf_report = verifier.run_csaf_compliance()   # Test Set 1 only
data_report = verifier.run_data_type_checks()  # Test Set 2 only

# Run individual tests
result = verifier.run_test("1.1")  # VEX Profile Conformance
result = verifier.run_test("2.5")  # CVE ID Format

# Get available tests
tests = Verifier.get_available_tests()
for test_id, test_name in tests.items():
    print(f"{test_id}: {test_name}")

Verification Test Reference

Contributing

Interested in contributing? Check out:

• DEVELOP.md - Development setup, workflow, and contribution guidelines
• RELEASE.md - Release process for maintainers

License

MIT License - see LICENSE file for details.

Authors

• Jakub Frejlach (jfrejlac@redhat.com)
• Juan Perez de Algaba (jperezde@redhat.com)
• George Vauter (gvauter@redhat.com)

Developed by Red Hat Product Security.