<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) ·
[How It Works](#how-it-works) ·
[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.
## Getting Started
### Prerequisites
- Rust 1.75+ (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/bitvex-rs/bitvex.git
cd bitvex
cargo install --path .
```
### Run
```bash
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>"
```
### 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 ║
╚══════════════════════════════════════════════════════╝
```
## How It Works
### Filtering Pipeline
BitVex applies three hardware-aware filters to eliminate false positives before they reach your security team:
| **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` |
Each filter maps to a machine-readable justification defined in the [OpenVEX specification](https://github.com/openvex/spec), enabling automated processing by downstream tools.
### OSV Integration
For packages that pass hardware filters, BitVex queries Google's [OSV API](https://osv.dev/) in batch:
- Async HTTP requests via `tokio` + `reqwest`
- 100 packages per batch request
- Covers all ecosystems (NVD, GitHub, PyPI, etc.)
- No API key required
### Output Format
The generated JSON strictly conforms to [OpenVEX v0.2.0](https://github.com/openvex/spec):
```json
{
"@context": "https://openvex.dev/ns/v0.2.0",
"@id": "https://openvex.dev/docs/bitvex/vex-...",
"author": "Acme Devices <security@acme.com>",
"role": "Document Creator",
"timestamp": "2024-01-15T10:30:00Z",
"version": 1,
"tooling": "BitVex 0.1.0",
"statements": [
{
"vulnerability": { "name": "CVE-2024-12345" },
"products": [{ "@id": "pkg:generic/openssl@3.0.13" }],
"status": "not_affected",
"justification": "vulnerable_code_not_present",
"impact_statement": "The driver 'openssl' is not enabled in the kernel configuration."
}
]
}
```
This document can be:
- Consumed by vulnerability scanners to suppress false positives
- Attached to SBOMs as an attestation
- Submitted to regulators as CRA compliance evidence
## CLI Reference
```
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 [default: BitVex <bitvex@automated>]
-v, --verbose Enable debug logging
-h, --help Print help
-V, --version Print version
```
## Integration
### CI/CD Pipeline
```yaml
# GitHub Actions example
- name: Generate VEX Report
run: |
bitvex \
--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 \
--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 argument definitions (clap)
├── sbom/
│ └── spdx.rs SPDX JSON parser
├── osv/
│ └── client.rs Async OSV API client
├── filters/
│ ├── native.rs Host-only recipe filter
│ ├── kernel_config.rs .config cross-reference
│ └── device_tree.rs DTS status cross-reference
├── vex/
│ └── openvex.rs OpenVEX document generator
└── output/
└── console.rs Console summary formatter
```
## Development
```bash
# Build
cargo build
# Run tests
cargo test
# Lint (zero warnings expected)
cargo clippy
# Format
cargo fmt
# Verbose output
RUST_LOG=debug cargo run -- --sbom ... --kernel-config ... --device-tree ... -v
```
## 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
- **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