<div align="center">
# BitVex
**Automated CRA Compliance for Embedded Linux**
Generate spec-compliant OpenVEX reports from Yocto builds by filtering CVEs against your actual hardware configuration.
[](LICENSE)
[](https://www.rust-lang.org/)
[](#)
[](https://openvex.dev/)
[](https://spdx.dev/)
[Getting Started](#getting-started) ·
[Features](#features) ·
[CLI Reference](#cli-reference) ·
[Integration](#integration) ·
[Architecture](#architecture)
</div>
---
## 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:
| `gcc-native`, `cmake-native` | Host-only build tools, never deployed on target |
| `CONFIG_BT` drivers | Kernel compiled without Bluetooth support |
| WiFi chipset firmware | `status = "disabled"` in your Device Tree |
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
| **Native Recipes** | SBOM package names | Packages ending in `-native` are build host tools | `component_not_present` |
| **Kernel Config** | `.config` file | Drivers with `CONFIG_XXX` not set to `=y` or `=m` | `vulnerable_code_not_present` |
| **Device Tree** | `.dts` source | Peripherals with `status = "disabled"` | `vulnerable_code_not_in_execute_path` |
### Rules Engine
Define custom filtering rules in `bitvex.toml`:
```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:
```bash
# 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:
```bash
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:
| `small` | Linux | ~29 MB | Kernel-only devices |
| `medium` | Linux, Alpine, crates.io | ~35 MB | Typical embedded |
| `big` | + Debian, PyPI | ~116 MB | Full coverage |
| `complete` | All 10 ecosystems | ~822 MB | Maximum audit |
---
## Getting Started
### Prerequisites
- Rust 1.85+ (install via [rustup](https://rustup.rs/))
- 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
```bash
git clone https://github.com/LManuXx/BitVex.git
cd BitVex
cargo install --path .
```
### Quick Start
```bash
# 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
```yaml
# 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`:
```bitbake
# 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
<details>
<summary><strong>SBOM (SPDX 2.3 JSON)</strong></summary>
Produced by Yocto's `meta-spdxscanner` or tools like [syft](https://github.com/anchore/syft). Required fields per package:
- `name` — package identifier
- `versionInfo` — version string
- `externalRefs` — optional `purl` (Package URL)
</details>
<details>
<summary><strong>Kernel .config</strong></summary>
Standard Linux kernel configuration. Located at `${STAGING_KERNEL_BUILDDIR}/.config` in a Yocto build.
</details>
<details>
<summary><strong>Device Tree (.dts)</strong></summary>
Source format, not compiled `.dtb`. To decompile:
```bash
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/`.
</details>
---
## 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
```bash
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)](LICENSE).
**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](https://openvex.dev/) — VEX specification
- [OSV](https://osv.dev/) — vulnerability database
- [CISA](https://www.cisa.gov/) — VEX minimum requirements
- [Yocto Project](https://www.yoctoproject.org/) — embedded Linux build system