Crates.io | vex2pdf |
lib.rs | vex2pdf |
version | 0.8.2 |
created_at | 2025-04-22 16:45:55.340772+00 |
updated_at | 2025-09-10 19:39:26.44855+00 |
description | A tool to convert CycloneDX(VEX) JSON or XML documents to PDF reports |
homepage | |
repository | https://gitlab.com/jurassicLizard/vex2pdf |
max_upload_size | |
id | 1644334 |
size | 4,611,157 |
A command-line tool to convert CycloneDX (VEX/VDR/(S)BoM) Documents in JSON or XML format to PDF reports.
VEX2PDF is a Rust application that scans the current directory for CycloneDX (VEX/VDR/(S)BoM files (JSON and XML) and converts them to human-readable PDF reports. It fully supports the CycloneDX 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 CycloneDX document format including vulnerabilities, components, metadata, and more.
This tool uses Liberation Sans fonts to render PDFs. The fonts are embedded directly in the binary, so no extra font configuration is required and the binary works standalone and is fully portable.
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.
Check VEX2PDF_SHOW_OSS_LICENSES for more Information.
The font license file is also available at Liberation fonts License file in the current repository.
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.
Notice: As of v0.6.1 no extra font configuration is needed. Fonts have been embedded in the software binary. Check Fonts handling and license for further information
Clone the repository, then build the application with cargo build --release
. The binary will be available at target/release/vex2pdf.
Users can either:
Currently, No Mac Binaries are provided however Mac Users can build and install with cargo. Please check the From Source Section
:note: If Mac release binaries are needed please create an issue
Run the application in a directory containing CycloneDX (VEX/VDR/(S)BoM 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/VDR/(S)BoM) document
Generate a PDF report with the same name as the original file (with .pdf extension)
Display progress and results in the console
$ ./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
No configuration files are required. However the application has some customization options available via Environment variables.
Windows Users: To set environment variables on Windows, use:
- Command Prompt:
set VEX2PDF_ENV_VARIABLE=false && vex2pdf
- PowerShell:
$env:VEX2PDF_ENV_VARIABLE="false"; vex2pdf
The following environment variables can be used to customize behavior:
Variable | Purpose | Default |
---|---|---|
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_REPORT_TITLE | Overrides the default report title | Not set (uses default title) |
VEX2PDF_PDF_META_NAME | Overrides the PDF metadata title | Not set (uses default metadata title) |
VEX2PDF_PURE_BOM_NOVULNS | Whether to treat the file as a component list instead of a vulnerability list | false |
VEX2PDF_SHOW_COMPONENTS | Whether to additionally show the component list after the vulnerability list | true |
This variable controls how the Vulnerabilities section appears when no vulnerabilities exist:
Example : VEX2PDF_NOVULNS_MSG=false vex2pdf
Shows all relevant OSS licenses:
Example : VEX2PDF_SHOW_OSS_LICENSES=true vex2pdf
Shows version information prior to running software normally
Overrides the default report title with custom text
Example : VEX2PDF_REPORT_TITLE="My Custom VEX Report" vex2pdf
Overrides the PDF metadata title with custom text
Example 1 : VEX2PDF_PDF_META_NAME="VEX Report - Company XYZ" vex2pdf
Example 2 : VEX2PDF_PDF_META_NAME="VEX Report - Company XYZ" VEX2PDF_REPORT_TITLE="My Custom VEX Report" vex2pdf
Whether to treat the file as a pure CycloneDX Bill of Materials only listing the components and ignoring the vulnerability list
Example : VEX2PDF_PURE_BOM_NOVULNS=true vex2pdf
Whether to show the complete list of components after the vulnerabilities section. The default behaviour is true
but this can be overridden
Example: VEX2PDF_SHOW_COMPONENTS=false vex2pdf
For full API documentation, please visit:
To generate documentation locally:
cargo doc --open
This tool fully supports CycloneDX 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 format, see:
This tool implements a special compatibility mode for CycloneDX 1.6 documents:
specVersion: "1.6"
, it will:
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:
When processing 1.6 documents, you'll see console messages indicating the compatibility mode is active.
Changes to the software between version increments are documented under Changelog.md.
This project is licensed under either of:
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you shall be dual-licensed as above, without any additional terms or conditions.
This project uses third-party dependencies that may be distributed under different licenses. Please refer to the license information provided with each dependency for details.