BitVex

Automated CRA Compliance for Embedded Linux

Generate spec-compliant OpenVEX reports from Yocto builds by filtering CVEs against your actual hardware configuration.

Getting Started · Features · CLI Reference · Integration · Architecture

The Problem

The EU Cyber Resilience Act (CRA) mandates vulnerability disclosure for connected devices. If you build embedded Linux products with Yocto, you face a critical challenge:

Your SBOM lists 200+ packages. A scanner flags 500 CVEs. How many actually affect your device?

Most are false positives:

Manual triage of hundreds of CVEs per build is unsustainable. BitVex automates it.

What BitVex Does

BitVex takes three inputs from your Yocto build and produces an auditable VEX document:

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  SBOM       │     │  Kernel      │     │  Device     │
│  (SPDX)     │     │  .config     │     │  Tree       │
└──────┬──────┘     └──────┬───────┘     └──────┬──────┘
       │                   │                    │
       └───────────────────┼────────────────────┘
                           │
                    ┌──────▼──────┐
                    │   BitVex    │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │  OpenVEX    │
                    │  Report     │
                    └─────────────┘

Result: A machine-readable document that tells scanners exactly which CVEs are real, which are mitigated by your hardware config, and why.

Features

Core Filters

Rules Engine

Define custom filtering rules in bitvex.toml:

[author]
name = "Mi Empresa <security@empresa.com>"

[[rules]]
name = "OpenSSL parcheado"
cve = "CVE-2024-12345"
package = "openssl"
status = "not_affected"
justification = "vulnerable_code_not_present"
impact_statement = "Parcheado manualmente en nuestra build"

[[rules]]
name = "WiFi deshabilitado"
cve_pattern = "CVE-2024-*"
package = "linux-firmware"
status = "not_affected"
justification = "component_not_present"

Offline Mode

Download the OSV vulnerability database and scan without internet — perfect for air-gapped environments:

# Download (~35 MB for Linux + Alpine + crates.io)
bitvex download-db --profile medium

# Scan offline
bitvex --offline --sbom ... --kernel-config ... --device-tree ...

SBOM Diff

Compare two builds and see what changed:

bitvex diff --old v1.spdx.json --new v2.spdx.json

╔══════════════════════════════════════════════════════╗
║          BitVex - SBOM Diff Report                  ║
╠══════════════════════════════════════════════════════╣
║  Packages added:       5                            ║
║  Packages removed:     2                            ║
║  Packages updated:     12                           ║
╚══════════════════════════════════════════════════════╝

Download Profiles

Choose your database size based on your needs:

Getting Started

Prerequisites

• Rust 1.85+ (install via rustup)
• Three files from your Yocto build:
  • SBOM in SPDX JSON format (generated by meta-spdxscanner or syft)
  • Kernel .config file
  • Device Tree source (.dts)

Install

git clone https://github.com/LManuXx/BitVex.git
cd BitVex
cargo install --path .

Quick Start

# 1. Download vulnerability database (one time, ~35 MB)
bitvex download-db --profile medium

# 2. Scan your build
bitvex \
  --sbom build/tmp/deploy/images/rpi4/image-spdx.json \
  --kernel-config build/tmp/work/rpi4-linux/linux-raspberrypi/6.1/.config \
  --device-tree build/tmp/work/rpi4-linux/linux-raspberrypi/6.1/arch/arm64/boot/dts/broadcom/bcm2711-rpi-4-b.dts \
  --output rpi4-cra-report.vex.json \
  --author "Acme Devices <security@acme.com>"

# 3. Or scan offline (no internet needed)
bitvex \
  --offline \
  --sbom build/image-spdx.json \
  --kernel-config build/.config \
  --device-tree build/board.dts \
  --rules bitvex.toml

Output

╔══════════════════════════════════════════════════════╗
║          BitVex - CRA Compliance Report             ║
╠══════════════════════════════════════════════════════╣
║  Total packages analyzed:     142                    ║
║  Native packages filtered:     23                    ║
║  Kernel drivers filtered:      12                    ║
║  DTS disabled filtered:         5                    ║
║  ─────────────────────────────────────              ║
║  CVEs marked not_affected:     40                    ║
║  CVEs marked fixed:             0                    ║
║  Real CVEs to address:         12                    ║
╚══════════════════════════════════════════════════════╝

CLI Reference

Scan Mode (default)

bitvex [OPTIONS] --sbom <PATH> --kernel-config <PATH> --device-tree <PATH>

Options:
      --sbom <PATH>           SBOM in SPDX JSON format
      --kernel-config <PATH>  Linux kernel .config file
      --device-tree <PATH>    Device Tree source (.dts)
  -o, --output <PATH>         Output OpenVEX file [default: bitvex-report.vex.json]
      --author <STRING>       VEX document author
      --rules <PATH>          Path to bitvex.toml rules file
      --offline               Use offline OSV database
      --download-db           Download DB before scanning
      --profile <PROFILE>     Download profile (small/medium/big/complete)
  -y, --yes                   Skip confirmation prompts
  -v, --verbose               Enable debug logging

Diff Mode

bitvex diff --old <PATH> --new <PATH> [--output <PATH>]

Download Database

bitvex download-db [OPTIONS]

Options:
      --db-path <PATH>        Custom database path
      --ecosystems <LIST>     Comma-separated ecosystems
      --profile <PROFILE>     small | medium | big | complete
  -y, --yes                   Skip confirmation prompt

Integration

CI/CD Pipeline

# GitHub Actions example
- name: Download OSV Database
  run: bitvex download-db --profile medium -y

- name: Generate VEX Report
  run: |
    bitvex \
      --offline \
      --sbom build/image-spdx.json \
      --kernel-config build/.config \
      --device-tree build/board.dts \
      --output vex-report.vex.json \
      --author "${{ github.repository_owner }} <ci@${{ github.repository_owner }}.com>"

- name: Upload VEX Artifact
  uses: actions/upload-artifact@v4
  with:
    name: vex-report
    path: vex-report.vex.json

Yocto Integration

Add BitVex to your Yocto build as a post-build step in local.conf:

# Generate VEX report after image build
IMAGE_POSTPROCESS_COMMAND += "generate_vex_report; "

generate_vex_report() {
    bitvex \
        --offline \
        --sbom ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.spdx.json \
        --kernel-config ${STAGING_KERNEL_BUILDDIR}/.config \
        --device-tree ${STAGING_KERNEL_BUILDDIR}/arch/${ARCH}/boot/dts/*.dts \
        --output ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.vex.json
}

Input Format Requirements

Produced by Yocto's meta-spdxscanner or tools like syft. Required fields per package:

• name — package identifier
• versionInfo — version string
• externalRefs — optional purl (Package URL)

Standard Linux kernel configuration. Located at ${STAGING_KERNEL_BUILDDIR}/.config in a Yocto build.

Source format, not compiled .dtb. To decompile:

dtc -I dtb -O dts -o board.dts board.dtb

In Yocto, the preprocessed DTS is typically in ${STAGING_KERNEL_BUILDDIR}/arch/${ARCH}/boot/dts/.

Architecture

src/
├── main.rs              Pipeline orchestration
├── lib.rs               Public API exports
├── cli.rs               CLI args + subcommands (clap)
├── sbom/
│   ├── spdx.rs          SPDX JSON parser
│   └── diff.rs          SBOM diff engine
├── osv/
│   ├── client.rs        Async OSV API client (online)
│   ├── offline.rs       Offline OSV provider
│   └── db.rs            DB download with profiles + progress
├── filters/
│   ├── native.rs        Host-only recipe filter
│   ├── kernel_config.rs .config cross-reference
│   ├── device_tree.rs   DTS status cross-reference
│   └── rules.rs         Custom rules engine
├── rules/
│   └── mod.rs           bitvex.toml parser + rule matching
├── vex/
│   └── openvex.rs       OpenVEX v0.2.0 generator
└── output/
    └── console.rs       Console summary formatter

Development

cargo build              # Compile
cargo test               # Run 38 tests (27 unit + 11 integration)
cargo clippy             # Lint (0 warnings)
cargo fmt                # Format

Security Model

BitVex follows the principle of least privilege:

• No credentials required — OSV API is free and anonymous
• No data sent — only package names/versions are transmitted to OSV
• Offline mode — download DB once, scan without internet
• Local processing — all filtering happens on your machine
• Deterministic output — same inputs produce the same VEX document

License

This project is licensed under the Server Side Public License (SSPL-1.0).

What this means:

• You can use, modify, and distribute BitVex freely for internal/non-commercial purposes
• If you offer BitVex as a service (SaaS), you must make your entire service stack open source under SSPL-1.0
• For commercial licensing or OEM integration, contact the author

Author: Manuel Neto Romero

Acknowledgments

• OpenVEX — VEX specification
• OSV — vulnerability database
• CISA — VEX minimum requirements
• Yocto Project — embedded Linux build system