12 releases (5 breaking)
new 0.6.2 | May 22, 2025 |
---|---|
0.6.1 | May 22, 2025 |
0.5.0 | May 15, 2025 |
0.4.3 | Apr 30, 2025 |
0.1.0 | Apr 22, 2025 |
#343 in Parser implementations
1,068 downloads per month
2.5MB
1K
SLoC
CycloneDX (VEX) to PDF Converter
A command-line tool to convert CycloneDX VEX (Vulnerability Exploitability eXchange) documents in JSON or XML format to PDF reports.
- CycloneDX (VEX) to PDF Converter
Overview
VEX2PDF is a Rust application that scans the current directory for CycloneDX VEX files (JSON and XML) 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.
Fonts Handling
This tool uses Liberation Sans fonts to render PDFs. The fonts are now embedded directly in the binary, so no external font installation is required.
Font Fallback Mechanism deprecated
Note: The fonts have been embedded in the software as of 0.6.1. Therefore, The
VEX2PDF_FONTS_PATH
environment variable is deprecated as of version 0.6.1 and will be removed in version 0.7.0. Using embedded fonts is now the recommended approach and will be done automatically in the future. the deprecation also applies to project/user/system location fonts to simplify the process. If you still need this functionality you may open a ticket under vex2pdf issues. otherwise the simpler and more elegant solution of embedded fonts will be enforced which will make the application more portable accross platforms
Note: This section will be removed upon deprecation of external fonts
The tool will use fonts in the following order of preference:
- Embedded fonts (built into the binary)
- Custom location (if set via
VEX2PDF_FONTS_PATH
environment variable) - Deprecated - Project location:
./fonts/liberation-fonts/
- Deprecated - User location:
~/.local/share/fonts/liberation-fonts/
- Deprecated - System location:
/usr/share/fonts/liberation-fonts/
- Deprecated
Font Licensing
The embedded Liberation Sans fonts are licensed under the SIL Open Font License (OFL).
Set the environment variable VEX2PDF_SHOW_OSS_LICENSES=true
to display full license details at runtime.
The font license file is available at fonts/liberation-fonts/LICENSE
in the source repository.
Features
- Automatically scans directories for JSON and XML files with VEX data
- Converts VEX documents to structured PDF reports
- Supports both JSON and XML CycloneDX formats
- 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 in the Font Requirement section)
Via Cargo
The easiest way to install VEX2PDF is directly from crates.io:
cargo install vex2pdf
After installation, the vex2pdf
binary will be available in your Cargo bin directory.
⚠️ Important: You'll still need to set up the Liberation Sans fonts as described in the Font Requirement section. When installing via Cargo, fonts should be placed in one of the paths listed in the Font Path Configuration section.Notice: As of 0.6.1 no extra font configuration is needed. Fonts have been embedded in the software binary. Check Fonts handling and license for further information
From Source
Clone the repository, then build the application with cargo build --release
. The binary will be available at target/release/vex2pdf.
Windows Users
Windows users can either:
- Install via Cargo as described above
- Build using Rust for Windows from source
- Use a pre-built binary (GitHub Releases Section)
Usage
Run the application in a directory containing CycloneDX VEX files (JSON or XML):
./vex2pdf
The tool will:
- Scan the current directory for JSON and XML files
- Attempt to parse each file as a CycloneDX VEX document
- Generate a PDF report with the same name as the original file (with .pdf extension)
- Display progress and results in the console
Example
$ ./vex2pdf
vex2pdf v0.6.1 - CycloneDX (VEX) to PDF Converter
Copyright (c) 2025 jurassicLizard - MIT License
Active font path: <embedded liberationSans fonts> -- the env variable VEX2PDF_SHOW_OSS_LICENSES=true shows Font license details
Scanning for JSON files in: ./documents
Found 2 JSON files
Processing: ./documents/example1.json
Generating PDF: ./documents/example1.pdf
Successfully generated PDF: ./documents/example1.pdf
Processing: ./documents/example2.json
Generating PDF: ./documents/example2.pdf
Successfully generated PDF: ./documents/example2.pdf
Scanning for XML files in: ./documents
Found 5 XML files
Processing: ./documents/example1.xml
Generating PDF: ./documents/example1.pdf
Successfully generated PDF: ./documents/example1.pdf
Processing: ./documents/example2.xml
Generating PDF: ./documents/example2.pdf
Successfully generated PDF: ./documents/example2.pdf
Processing: ./documents/example3.xml
NOTE: Downgrading CycloneDX BOM from spec version 1.6 to 1.5
Reason: Current implementation does not yet fully support spec version 1.6
Warning: This compatibility mode only works for BOMs that don't utilize 1.6-specific fields
Processing will fail if 1.6-specific fields are encountered
Generating PDF: ./documents/example3.pdf
Successfully generated PDF: ./documents/example3.pdf
Configuration
No configuration files are required. However the application has some customization options available
Font Path Configuration deprecated
As of 0.6.1 Embedded fonts are used in the binary and no extra configuration is needed. This section will be removed at the latest in v0.7.0 check Font handling and license for more information
The application uses these locations for fonts in order of precedence:
- Custom directory specified via
VEX2PDF_FONTS_PATH
environment variable (if set) - deprecated - Project-local directory
./fonts/liberation-fonts
(if it exists) - deprecated - User's local fonts directory
~/.local/share/fonts/liberation-fonts
(if it exists) - deprecated - System-wide directory
/usr/share/fonts/liberation-fonts
- deprecated
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 - deprecated
export VEX2PDF_FONTS_PATH=/path/to/your/liberation-fonts
./vex2pdf
Windows (PowerShell) - deprecated
$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 - deprecated | Custom path to look for font files - deprecated | Check Font Path Configuration |
VEX2PDF_NOVULNS_MSG | Controls the "No Vulnerabilities reported" message display | true |
VEX2PDF_SHOW_OSS_LICENSES | Shows all relevant licenses and exits | off |
VEX2PDF_VERSION_INFO | Shows version information before executing normally | off |
VEX2PDF_FONTS_PATH
this has been deprecated see Fonts handling section
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
VEX2PDF_SHOW_OSS_LICENSES
Shows all relevant OSS licenses and quits the application. Currently shows :
- MIT License for the current software
- SIL License for the liberation-fonts
VEX2PDF_VERSION_INFO
Shows version information prior to running software normally 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
For full API documentation, please visit:
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 locally:
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:- Display a notification about downgrading to 1.5
- Automatically modify the document's spec version to "1.5"
- 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
- CycloneDX for the VEX specification
- cyclonedx-bom for CycloneDX parsing
- genpdf for PDF generation
- serde_json for JSON processing
- Liberation Fonts for the PDF rendering fonts
Dependencies
~27MB
~275K SLoC