vex2pdf 0.5.0

A tool to convert CycloneDX(VEX) JSON documents to PDF reports
Documentation

CycloneDX (VEX) to PDF Converter

Rust Documentation Crates.io License: MIT CI GitHub Release

A command-line tool to convert CycloneDX VEX (Vulnerability Exploitability eXchange) documents in JSON format to PDF reports.

⚠️ Font Requirement

This application requires Liberation Sans fonts to properly render PDF documents.

The Liberation Sans fonts are NOT included in this repository due to licensing considerations. To set up the required fonts:

  1. Download the Liberation Sans TTF fonts from the official repository
  2. Create a directory in the project root: fonts/liberation-fonts
  3. Place the following TTF files in that directory:
  • LiberationSans-Regular.ttf
  • LiberationSans-Bold.ttf
  • LiberationSans-Italic.ttf
  • LiberationSans-BoldItalic.ttf

Alternative options:

  • On Linux systems, if the fonts are installed system-wide (typically in /usr/share/fonts/liberation-sans), the application will attempt to use them.
  • Set the font path through the VEX2PDF_FONTS_PATH environment variable.

Note: The Liberation Fonts are licensed under the SIL Open Font License, not MIT. Please respect their license terms when using them.

Overview

VEX-to-PDF is a Rust application that scans the current directory for CycloneDX VEX JSON files and converts them to human-readable PDF reports. It fully supports the CycloneDX VEX schema version 1.5 and provides compatibility for version 1.6 documents that only use 1.5 fields. Documents using 1.6-specific fields may not process correctly. The tool handles various elements of the VEX documentation format including vulnerabilities, components, metadata, and more.

Features

  • Automatically scans directories for JSON files with VEX data

  • Converts VEX documents to structured PDF reports

  • Preserves all key VEX information including:

    • Document metadata and timestamps
    • Vulnerability details with severity ratings
    • Component information
    • Tools used to generate the VEX document

  • Cross-platform support (Linux, Windows)

Installation

Prerequisites

  • Rust and Cargo (latest stable version)
  • Liberation Sans fonts (must be obtained separately as described above)

From Source

Clone the repository, download and place Liberation fonts as described in the Font Requirement section, then build the application with . The binary will be available at target/release/vex2pdf. cargo build --release

Windows Users

Windows users can either:

  1. Build using Rust for Windows
  2. Use a pre-built binary (when available)

Usage

Run the application in a directory containing CycloneDX VEX JSON files:

./vex2pdf

The tool will:

  1. Scan the current directory for JSON files
  2. Attempt to parse each file as a CycloneDX VEX document
  3. Generate a PDF report with the same name as the original file (with .pdf extension)
  4. Display progress and results in the console

Example

$ ./vex2pdf
Scanning for JSON files in: /home/user/vex-documents
Found 3 JSON files
Processing: sample_vex.json
Generating PDF: sample_vex.pdf
Successfully generated PDF: sample_vex.pdf
Processing: second-sample.json
Generating PDF: second-sample.pdf
Successfully generated PDF: second-sample.pdf

Configuration

No configuration files are required. However the application has some customization options available

Font Path Configuration

The application uses these locations for fonts in order of precedence:

  1. Custom directory specified via VEX2PDF_FONTS_PATH environment variable (if set)
  2. Project-local directory ./fonts/liberation-fonts (if it exists)
  3. User's local fonts directory ~/.local/share/fonts/liberation-fonts (if it exists)
  4. System-wide directory /usr/share/fonts/liberation-fonts

You can customize the font path by setting the VEX2PDF_FONTS_PATH environment variable: The specified directory should contain the Liberation Sans font files directly (not in a subdirectory).

For example, if your fonts are in /path/to/your/liberation-fonts/, set:

Linux

export VEX2PDF_FONTS_PATH=/path/to/your/liberation-fonts
 ./vex2pdf

Windows (PowerShell)

$env:VEX2PDF_FONTS_PATH="C:\path\to\your\liberation-fonts" .\vex2pdf.exe

The specified directory should contain these font files:

  • LiberationSans-Regular.ttf
  • LiberationSans-Bold.ttf
  • LiberationSans-Italic.ttf
  • LiberationSans-BoldItalic.ttf

Environment Variables

The following environment variables can be used to customize behavior:

Variable Purpose Default
VEX2PDF_FONTS_PATH Custom path to look for font files Check Font Path Configuration
VEX2PDF_NOVULNS_MSG Controls the "No Vulnerabilities reported" message display true

VEX2PDF_NOVULNS_MSG

This variable controls how the Vulnerabilities section appears when no vulnerabilities exist:

  • When set to "true" or not set (default): A "Vulnerabilities" section will be shown with a "No Vulnerabilities reported" message
  • When set to "false": The Vulnerabilities section will be completely omitted from the PDF

Example:

# To hide the Vulnerabilities section when no vulnerabilities exist this is mostly useful when a report for a bom is generated
VEX2PDF_NOVULNS_MSG=false vex2pdf

Documentation

Note: Rust documentation is a work in progress. Please refer to the code comments for details on specific functions and data structures.

To generate documentation:

cargo doc --open

CycloneDX VEX Format

This tool fully supports CycloneDX VEX schema version 1.5 and provides compatibility for version 1.6 documents that only use 1.5 fields. Documents using 1.6-specific fields may not process correctly. For more information about the CycloneDX VEX format, see:

Version 1.6 Compatibility Mode

This tool implements a special compatibility mode for CycloneDX 1.6 documents:

  • When the tool encounters a document with specVersion: "1.6", it will:
    1. Display a notification about downgrading to 1.5
    2. Automatically modify the document's spec version to "1.5"
    3. Attempt to process it using the 1.5 schema parser

This compatibility approach works well for documents that don't use 1.6-specific fields but allows the tool to process newer documents without requiring users to manually modify them.

Limitations:

  • Documents that use 1.6-specific fields or structures may fail during processing
  • No validation is performed for 1.6-specific features
  • This is a temporary solution until full 1.6 support is implemented in the underlying cyclonedx-bom library

When processing 1.6 documents, you'll see console messages indicating the compatibility mode is active.

Security Considerations

  • The application reads and processes files from the current directory
  • No network connections are established
  • Input validation is performed on all JSON files
  • Font paths are validated before use

License

This project is licensed under the MIT License - see the LICENSE.md file for details. The Liberation Fonts used by this application are licensed under the SIL Open Font License and must be obtained separately.

Acknowledgments