Vulnera Advisors: Open Source Vulnerability Intelligence

A Rust library for aggregating and querying security vulnerability advisories from multiple sources. Designed for building vulnerability scanners, SCA tools, and security dashboards.

About Vulnera

This project is an open source contribution from the Vulnera organization, dedicated to improving security tooling and vulnerability management. Vulnera provides security-focused libraries and tools to help developers build more secure applications.

Features

Multi-Source Aggregation: Fetch advisories from:
- GitHub Security Advisories (GHSA) via GraphQL API
- NIST National Vulnerability Database (NVD) via REST API
- Open Source Vulnerabilities (OSV) via bulk downloads
- CISA Known Exploited Vulnerabilities (KEV)
- OSS Index for on-demand PURL queries
Enrichment Data:
- EPSS (Exploit Prediction Scoring System) scores
- KEV status for identifying actively exploited vulnerabilities
Unified Data Model: All sources normalized to OSV-compatible Advisory format
Efficient Storage: Redis/DragonflyDB backend with zstd compression
Version Matching: SemVer-aware vulnerability matching
Caching: Automatic caching for OSS Index queries with configurable TTL

Installation

Add to your Cargo.toml:

[dependencies]
vulnera-advisors = "0.1.0"

Quick Start

use vulnera_advisors::{VulnerabilityManager, Config};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load configuration from environment variables
    let config = Config::from_env()?;
    let manager = VulnerabilityManager::new(config).await?;

    // Sync advisories from all configured sources
    manager.sync_all().await?;

    // Query vulnerabilities for a package
    let advisories = manager.query("npm", "lodash").await?;
    println!("Found {} advisories for lodash", advisories.len());

    // Check if a specific version is affected
    let affected = manager.matches("npm", "lodash", "4.17.20").await?;
    for advisory in affected {
        println!("CVE: {} - {}", advisory.id, advisory.summary.unwrap_or_default());
    }

    Ok(())
}

Builder Pattern

For more control over configuration:

use vulnera_advisors::VulnerabilityManager;

let manager = VulnerabilityManager::builder()
    .redis_url("redis://localhost:6379")
    .with_osv_defaults()  // npm, PyPI, Maven, crates.io, Go, etc.
    .with_nvd(Some("your-nvd-api-key".to_string()))
    .with_ghsa("your-github-token".to_string())
    .with_ossindex(None)  // Uses env vars for auth
    .build()?;

OSS Index Queries

Query vulnerabilities directly by Package URL (PURL):

use vulnera_advisors::{VulnerabilityManager, Purl};

// Build PURLs for packages
let purls = vec![
    Purl::new("npm", "lodash").with_version("4.17.20").to_string(),
    Purl::new("pypi", "requests").with_version("2.25.0").to_string(),
];

// Query with automatic caching
let advisories = manager.query_ossindex(&purls).await?;

Filtering Options

Filter vulnerabilities by severity, EPSS score, or KEV status:

use vulnera_advisors::{MatchOptions, Severity};

// Only high/critical severity
let options = MatchOptions::high_severity();

// Only actively exploited (KEV)
let options = MatchOptions::exploited_only();

// Custom filters
let options = MatchOptions {
    min_cvss: Some(7.0),
    min_epss: Some(0.5),
    kev_only: false,
    min_severity: Some(Severity::Medium),
    include_enrichment: true,
};

let vulns = manager.matches_with_options("npm", "lodash", "4.17.20", &options).await?;

Environment Variables

Variable	Description	Required
`REDIS_URL`	Redis/DragonflyDB connection URL	Yes
`VULNERA__APIS__GHSA__TOKEN`	GitHub token for GHSA API	For GHSA
`VULNERA__APIS__NVD__API_KEY`	NVD API key (higher rate limits)	Optional
`OSSINDEX_USER`	OSS Index username	For OSS Index
`OSSINDEX_TOKEN`	OSS Index API token	For OSS Index
`VULNERA__STORE__TTL_SECONDS`	Advisory cache TTL	Optional

Supported Ecosystems

The library supports Package URLs (PURLs) for these ecosystems:

npm - Node.js packages
pypi - Python packages
cargo / crates.io - Rust crates
maven - Java/Kotlin packages
nuget - .NET packages
gem - Ruby gems
golang / go - Go modules
composer / packagist - PHP packages
pub - Dart/Flutter packages
hex - Erlang/Elixir packages
cocoapods - iOS/macOS packages
swift - Swift packages

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    VulnerabilityManager                      │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐│
│  │  GHSA   │ │   NVD   │ │   OSV   │ │   KEV   │ │  EPSS  ││
│  │ Source  │ │ Source  │ │ Source  │ │ Source  │ │ Source ││
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └───┬────┘│
│       │           │           │           │          │      │
│       └───────────┴─────┬─────┴───────────┴──────────┘      │
│                         │                                    │
│                    ┌────▼────┐                               │
│                    │Aggregator│                              │
│                    └────┬────┘                               │
│                         │                                    │
│                    ┌────▼────┐                               │
│                    │  Store  │ ◄── Redis/DragonflyDB        │
│                    └─────────┘     + zstd compression       │
└─────────────────────────────────────────────────────────────┘

Data Model

Advisories follow the OSV Schema:

pub struct Advisory {
    pub id: String,                    // e.g., "CVE-2021-23337", "GHSA-xxxx"
    pub summary: Option<String>,
    pub details: Option<String>,
    pub affected: Vec<Affected>,       // Affected packages and versions
    pub references: Vec<Reference>,
    pub published: Option<DateTime<Utc>>,
    pub modified: Option<DateTime<Utc>>,
    pub aliases: Option<Vec<String>>,  // Cross-references (CVE ↔ GHSA)
    pub enrichment: Option<Enrichment>, // EPSS, KEV data
}

Performance

Compressed Storage: zstd compression reduces Redis memory usage by ~70%
Batch Operations: Efficient bulk inserts and queries
Incremental Sync: Only fetches new/modified advisories after initial sync
Parallel Fetching: Sources are synced concurrently
Query Caching: OSS Index results cached with configurable TTL

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Contributing

This is an open source project from the Vulnera organization. We welcome contributions from the security community!

How to Contribute

Fork the repository
Create a feature branch
Submit a Pull Request with detailed description
Follow the existing code style and patterns
Add tests for new functionality

Security Contributions

We particularly welcome contributions that:

Improve security coverage
Add new vulnerability sources
Enhance matching algorithms
Optimize performance for large-scale analysis

About Vulnera

Vulnera is an organization dedicated to providing open source security tools and libraries that help developers build more secure applications. Our projects focus on making security accessible and actionable through practical, well-maintained tools.

Our mission is to democratize security by providing high-quality, open source tools that can be easily integrated into development workflows.

vulnera-advisor 0.1.1

Vulnera Advisors: Open Source Vulnerability Intelligence

About Vulnera

Features

Installation

Quick Start

Builder Pattern

OSS Index Queries

Filtering Options

Environment Variables

Supported Ecosystems

Architecture

Data Model

Performance

License

Contributing

How to Contribute

Security Contributions

About Vulnera