csaf-rust

This repository is a reference implementation for the CSAF standard in Rust that relies on automatically generating CSAF document structs from the JSON schema.

This is work-in-progress.

Repository structure

• csaf-validator contains a command line tool to validate CSAF documents.
• csaf-rs contains the actual validator library which currently publishes a crate to crates.io.
• csaf-ffi contains UniFFI bindings that expose csaf-rs to other languages (Go, WASM/TypeScript, and more).
• go/ contains generated Go bindings and integration tests.
• wasm/ contains generated WASM/TypeScript bindings and integration tests.

Minimum required Rust version (MSRV)

1.88.0

Usage

After building or downloading csaf-validator from the available releases, the usage is quite simple and additional help can be display using --help.

A validator for CSAF documents

Usage: csaf-validator [OPTIONS] <PATH>...

Arguments:
  <PATH>...  Path(s) to the CSAF document(s) to validate

Options:
  -C, --csaf-version <CSAF_VERSION>  Version of CSAF to use [possible values: auto, 2.0, 2.1] [default: auto]
  -T, --test <TEST>                  The validation preset or test ID to use; may be specified multiple times [default: basic]
  -v, --verbose                      Show detailed validation results
  -h, --help                         Print help
  -V, --version                      Print version

Some examples to use are included below. Please note that the validation is not yet fully implemented!

# validate a CSAF document, auto-detecting the version, with preset basic (the default)
csaf-validator my-csaf-document.json

# validate a CSAF 2.0 document with preset full
csaf-validator --csaf-version 2.0 --test full my-csaf-2-0-document.json

# validate a CSAF 2.1 document with one specific test
csaf-validator --csaf-version 2.1 --test 6.1.34 my-csaf-2-1-document.json

You can also use the library version as depicted here:

use std::path::Path;
use csaf::csaf2_0::loader::load_document;
use csaf::schema::csaf2_0::schema::CommonSecurityAdvisoryFramework;
use csaf::validation::{Validatable, validate_by_preset, validate_by_test, validate_by_tests};

let csaf_version = "2.0";
let path = "/path/to/local/cve-2025-9820.json";

// load the document
let document = load_document(Path::new(path))?;

// validate a preset
let preset_results = validate_by_preset(&document, csaf_version, "basic");

// validate multiple tests
let multiple_tests_result = validate_by_tests(&document, csaf_version, &["6.1.1", "6.1.10", "6.1.20"]);

// validate a single test
let single_test_result = validate_by_test(&document, "6.1.13");

// get all test IDs from a preset
let test_ids_in_basic_preset = CommonSecurityAdvisoryFramework::tests_in_preset("basic");

Go

To use this library you have to download the binaries for your specific operating system and platform. A download script is provided to help you with that.

You can either install systemwide (sudo may be needed)

go run github.com/csaf-rs/csaf/go/cmd/download-libs --system
go build ./...

Or without root permissions, but you have to tell the linker where to find the artifacts:

go run github.com/csaf-rs/csaf/go/cmd/download-libs   # one-time, writes to ~/.cache/csaf-ffi/
CGO_LDFLAGS="-L$HOME/.cache/csaf-ffi/lib/$(go env GOOS)_$(go env GOARCH)" go build ./...

Alternatively you can put the CGO_LDFLAGS export in your shell profile.

Then add it to your project with

go get github.com/csaf-rs/csaf/go

or directly to your go.mod file with

require github.com/csaf-rs/csaf/go

You can then import the necessary package into your code like this

import (
	"github.com/csaf-rs/csaf/go/csaf_ffi"
)

The easiest way to validate a document is to use the generic ValidateCsaf function, which takes the document and a preset to test against.

result, err := csaf_ffi.ValidateCsaf(string(data), preset)

Versioning

To bump the version across all crates and wasm/package.json at once, use the provided script. It requires cargo-edit and npm.

# Install cargo-edit (one-time)
cargo install cargo-edit

./scripts/publish/bump_version.sh patch        # x.y.z -> x.y.z+1
./scripts/publish/bump_version.sh minor        # x.y.z -> x.y+1.0
./scripts/publish/bump_version.sh major        # x.y.z -> x+1.0.0
./scripts/publish/bump_version.sh set 1.2.3    # explicit version

Commit Messages

Please use commit messages and pull request titles following Conventional Commits when contributing to this project. You can use a tool such as commitlint to check your commit locally, e.g., by running:

commitlint --default-config --last

to verify the latest commit. More options can be found with --help. The CI workflow pre-checks will also ensure that PR titles and commit messages in pushes to main conform to Conventional Commits. In addition, warnings in the pipeline are emitted if the commits contained within a PR do not adhere to Conventional Commits; these warnings do not fail the pipeline.

Build

If you want to build csaf-validator on your own, please install Rust (see https://rustup.rs) and then run

# make sure submodules are up-to-date
git submodule init
git submodule update --remote

# make sure that local assets are in sync with git submodules
./scripts/update/update_assets.sh

# run the tests
cargo test

# build for release
cargo build --release

The final binary will be in target/release and can then be installed, for example, in a system-wide folder.

Building for other languages

Bindings for other languages are created through the csaf-ffi crate, which is built by the language specific generate_XXX_bindings script.

Go

The Go bindings are generated via uniffi-bindgen-go.

Note: The generate_go_bindings.sh script invokes go fmt, go env GOOS and go env GOARCH to autoformat the output and detect the target platform, which is used to name the generated file. This requires Go to be installed and available on PATH, instructions can be found here.

# Install the Go binding generator (one-time)
cargo install uniffi-bindgen-go \
  --git https://github.com/NordSecurity/uniffi-bindgen-go \
  --tag v0.7.0+v0.31.0

# Build the Rust library, generate bindings, and copy the static archive
./scripts/publish/generate_go_bindings.sh

This creates GO code in the go/csaf_ffi folder.

To run the Go tests:

cd go
go test -v ./csaf_ffi/

As a demonstration there is a small CLI and Webserver example included.

Cli

cd go
CGO_LDFLAGS="-L$HOME/.cache/csaf-ffi/lib/$(go env GOOS)_$(go env GOARCH)" go run -buildvcs=false ./cmd/example/ <PATH_TO_CSAF_FILE>

Web server (API)

cd go
CGO_LDFLAGS="-L$HOME/.cache/csaf-ffi/lib/$(go env GOOS)_$(go env GOARCH)" go run -buildvcs=false ./cmd/webapi/

The server listens on port 8080 by default. Set the PORT environment variable to use a different port:

PORT=9090 go run -buildvcs=false ./cmd/webapi/

Endpoints

Method	Path	Description
POST	/api/validate/json	Validate a CSAF document sent as a raw JSON body
POST	/api/validate/upload	Validate a CSAF document sent as a multipart file upload (field: file)

Both endpoints accept the optional query parameter ?preset=basic (default), ?preset=extended, or ?preset=full.

Example:

curl -X POST http://localhost:8080/api/validate/json?preset=basic \
  -H 'Content-Type: application/json' \
  --data-binary @my-csaf.json

WASM

The WASM bindings are generated via uniffi-bindgen-js.

# Install the WASM binding generator (one-time)
cargo install uniffi-bindgen-js --version 0.2.1

# Build and generate (uses generate_wasm_bindings.sh)
./scripts/publish/generate_wasm_bindings.sh

This creates TypeScript + WASM output in wasm/.

Implementation status in regards to the Standard

• ✅ Implemented
• ⭕ Not applicable

Mandatory Tests

Test specification	2.0	2.1 (experimental)
6.1.1	✅	✅
6.1.2	✅	✅
6.1.3	✅	✅
6.1.4	✅	✅
6.1.5	✅	✅
6.1.6	✅	✅
6.1.7	✅	✅
6.1.8	✅
6.1.9	✅	✅
6.1.10	✅	✅
6.1.11	✅	✅
6.1.12	✅	✅
6.1.13	✅	✅
6.1.14	✅	✅
6.1.15	✅	✅
6.1.16	✅	✅
6.1.17	✅	✅
6.1.18	✅	✅
6.1.19	✅	✅
6.1.20	✅	✅
6.1.21	✅	✅
6.1.22	✅	✅
6.1.23	✅	✅
6.1.24	✅	✅
6.1.25	✅	✅
6.1.26	✅	✅
6.1.27.1	✅	✅
6.1.27.2	✅	✅
6.1.27.3	✅	✅
6.1.27.4	✅	✅
6.1.27.5	✅	✅
6.1.27.6	✅	✅
6.1.27.7	✅	✅
6.1.27.8	✅	✅
6.1.27.9	✅	✅
6.1.27.10	✅	✅
6.1.27.11	✅	✅
6.1.27.12	⭕	✅
6.1.27.13	⭕
6.1.27.14	⭕	✅
6.1.27.15	⭕	✅
6.1.27.16	⭕	✅
6.1.27.17	⭕	✅
6.1.27.18	⭕	✅
6.1.27.19	⭕	✅
6.1.28	✅	✅
6.1.29	✅	✅
6.1.30	✅	✅
6.1.31	✅	✅
6.1.32	✅	✅
6.1.33	✅
6.1.34	⭕	✅
6.1.35	⭕	✅
6.1.36	⭕
6.1.37	⭕
6.1.38	⭕	✅
6.1.39	⭕	✅
6.1.40	⭕	✅
6.1.41	⭕	✅
6.1.42	⭕	✅
6.1.43	⭕	✅
6.1.44	⭕	✅
6.1.45	⭕
6.1.46	⭕	✅
6.1.47	⭕	✅
6.1.48	⭕
6.1.49	⭕
6.1.50	⭕
6.1.51	⭕
6.1.52	⭕
6.1.53	⭕	✅
6.1.54	⭕	✅
6.1.55	⭕	✅
6.1.56	⭕	✅
6.1.57	⭕	✅
6.1.58	⭕	✅
6.1.59	⭕
6.1.60.1	⭕
6.1.60.2	⭕
6.1.60.3	⭕
6.1.61	⭕	✅

Recommended Tests

Test specification	2.0	2.1 (experimental)
6.2.1
6.2.11	✅	✅
6.2.23	⭕	✅
6.2.24	⭕	✅
6.2.25	⭕	✅
6.2.26	⭕	✅
6.2.34	⭕	✅
6.2.35	⭕	✅
6.2.36	⭕	✅
6.2.37	⭕	✅
6.2.39.2	⭕	✅
6.2.39.3	⭕	✅
6.2.47	⭕	✅

Informative Tests

Test specification	2.0	2.1 (experimental)
6.3.1
6.3.14	⭕	✅
6.3.15	⭕	✅