CVE / Dependency Vulnerability Setup

How It Works — Priority Order

Primus tries options in this order automatically. No configuration required for the default path.

Priority	Option	How to enable	Ecosystems
1	Live OSV.dev API (default)	EnableDependencyScanning = true — no key, no DB file needed	NuGet, npm, PyPI, Maven, Go, Rust
2	Local SQLite CVE database	Set CveDatabasePath to an existing .db file	Same as above + offline
3	Disabled	EnableDependencyScanning = false	—

Option 0: Live OSV.dev API (Recommended)

This is the default when EnableDependencyScanning = true and no local DB is configured.

• Free — no API key, no registration, no rate limit for normal use
• Always current — OSV.dev is updated in real time as new CVEs are published
• Batch queries — all packages checked in a single HTTP call via /v1/querybatch
• Multi-ecosystem — NuGet, npm, PyPI, Maven, Go, Rust, Ruby, PHP
• CVE + GHSA — returns both CVE IDs and GitHub Security Advisory IDs with CVSS scores

builder.Services.AddPrimusSecurity(options =>
{
    options.EnableStaticAnalysis      = true;
    options.EnableSecretDetection     = true;
    options.EnableDependencyScanning  = true;  // uses OSV.dev live API automatically
    // No CveDatabasePath needed
});

Console output when OSV.dev is active:

info: Dependency scanning: using live OSV.dev API (NuGet/npm/PyPI/Maven/Go — free, no API key)
info: OSV.dev: checked 12 packages — 2 vulnerabilities found

What OSV.dev covers

OSV.dev (Open Source Vulnerabilities) is Google's open source vulnerability database. It aggregates:

• NVD / NIST — the authoritative CVE registry
• GitHub Security Advisories — GHSA-format advisories
• Ecosystem advisories — NuGet, npm, PyPI, Maven, Go module, crates.io advisories

Security Feature	Requires CVE Database?
Secret Detection	❌ No
Static Code Analysis	❌ No
Compliance Validation (OWASP, PCI-DSS)	❌ No
Dependency Scanning	✅ Yes

Quick Decision Guide

Skip the CVE database if:

• You only need secret detection
• You're just getting started
• You don't scan dependencies

Use the CVE database if:

• You want to scan NuGet/NPM packages for vulnerabilities
• You need comprehensive security reports
• You're deploying to production

---

Option 1: Skip It (Recommended for Getting Started)

Simply disable dependency scanning in your configuration:

builder.Services.AddPrimusSecurity(options =>
{
    options.EnableStaticAnalysis = true;
    options.EnableSecretDetection = true;
    options.EnableDependencyScanning = false;  // ❌ Disabled
    // Don't set CveDatabasePath
});

Result: Secret detection and static analysis work perfectly without the database.

---

Option 2: Download Pre-Built Database (Recommended for Production)

Step 1: Download the Database

Download the latest pre-built CVE database from Primus releases:

Coming Soon

Pre-built CVE database downloads are currently being prepared. Check back soon or build your own (Option 3).

Step 2: Place in Your Project

# Create directory
mkdir -p ./SecurityData

# Move downloaded database
mv cve-database.db ./SecurityData/

Step 3: Configure Your Application

builder.Services.AddPrimusSecurity(options =>
{
    options.EnableStaticAnalysis = true;
    options.EnableSecretDetection = true;
    options.EnableDependencyScanning = true;  // ✅ Enabled
    options.CveDatabasePath = "./SecurityData/cve-database.db";
});

Step 4: Verify It Works

dotnet run

Check console output for:

✅ CVE database loaded: 15,234 vulnerabilities

---

Option 3: Build Your Own (Advanced)

Building your own CVE database gives you complete control and the latest vulnerability data.

Prerequisites

1. NVD API Key (Required)

   • Register at: https://nvd.nist.gov/developers/request-an-api-key
   • Wait 1-2 weeks for approval
   • Free for non-commercial use

2. GitHub Token (Optional, for higher rate limits)

   • Generate at: https://github.com/settings/tokens
   • No special permissions needed

Step 1: Navigate to CVE Aggregator Tool

cd tools/CveAggregator

Step 2: Set API Keys

Option A: Environment Variables (Recommended)

# Windows (PowerShell)
$env:NVD__ApiKey = "your-nvd-api-key-here"
$env:GitHub__Token = "your-github-token-here"

# Linux/Mac
export NVD__ApiKey="your-nvd-api-key-here"
export GitHub__Token="your-github-token-here"

Option B: appsettings.json

{
  "NVD": {
    "ApiKey": "your-nvd-api-key-here",
    "RateLimitDelay": 6000
  },
  "GitHub": {
    "Token": "your-github-token-here"
  }
}

Step 3: Build the Tool

dotnet restore
dotnet build

Step 4: Scrape CVE Data

# Scrape last 365 days (recommended for first run)
dotnet run -- scrape --days 365

# Or scrape from specific sources
dotnet run -- scrape --sources nvd github nuget npm --days 30

Expected output:

🔒 Primus Security CVE Aggregator
==================================================
📥 Starting CVE data scraping...
   Sources: nvd, github, nuget, npm
   Days: 365

🌐 Scraping NVD for last 365 days...
✅ NVD scraping complete: 12,345 vulnerabilities

🌐 Scraping GitHub Advisory Database...
✅ GitHub Advisory scraping complete: 2,456 vulnerabilities

✅ Scraping complete!

Step 5: Build the Database

dotnet run -- build --output cve-database.db

Expected output:

🔨 Building CVE database...
   Input: raw-data/
   Output: cve-database.db
   Compress: true

✅ Database built successfully!
🗜️  Compressing database...
✅ Compression complete!

📊 Final size: 52.3 MB

Step 6: Copy to Your Project

# Copy to your project's SecurityData folder
cp cve-database.db ../../SecurityData/

# Or specify custom path in your app
cp cve-database.db /path/to/your/project/SecurityData/

Step 7: Verify Database

# Show database statistics
dotnet run -- stats --database cve-database.db

Expected output:

📊 CVE Database Statistics
   Database: cve-database.db

Total Vulnerabilities: 14,801
By Source:
  NVD: 12,345
  GitHub: 2,456
  NuGet: 567
  NPM: 1,433

By Severity:
  Critical: 1,234
  High: 3,456
  Medium: 6,789
  Low: 3,322

---

Updating the Database

CVE databases should be updated regularly to catch new vulnerabilities.

Recommended Update Schedule

Environment	Update Frequency
Development	Monthly
Staging	Weekly
Production	Weekly

Update Process

cd tools/CveAggregator

# Scrape only recent vulnerabilities (faster)
dotnet run -- scrape --days 30

# Rebuild database
dotnet run -- build --output cve-database.db

# Copy to your project
cp cve-database.db ../../SecurityData/

Automated Updates (CI/CD)

# .github/workflows/update-cve-db.yml
name: Update CVE Database

on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday

jobs:
  update-cve:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        
      - name: Build CVE Database
        env:
          NVD__ApiKey: ${{ secrets.NVD_API_KEY }}
        run: |
          cd tools/CveAggregator
          dotnet run -- scrape --days 30
          dotnet run -- build
          
      - name: Upload Database
        uses: actions/upload-artifact@v4
        with:
          name: cve-database
          path: tools/CveAggregator/cve-database.db

---

Troubleshooting

Database File Not Found

Error:

⚠️ CVE database not found: ./SecurityData/cve-database.db
Dependency scanning disabled.

Solution:

1. Check if file exists: ls ./SecurityData/cve-database.db
2. Verify path in configuration matches actual file location
3. Download or build the database (see options above)

Dependency Scanning Not Working

Symptoms:

• No dependency vulnerabilities reported
• Only secret detection findings shown

Checklist:

• EnableDependencyScanning = true
• CveDatabasePath is set
• Database file exists at specified path
• Database file is not corrupted (check file size > 10MB)

Test:

# Check if database is valid
sqlite3 SecurityData/cve-database.db "SELECT COUNT(*) FROM vulnerabilities;"

Should return a number > 1000.

NVD API Key Not Working

Error:

❌ NVD API authentication failed

Solutions:

1. Verify API key is correct (no extra spaces)
2. Check if API key is approved (email from NVD)
3. Wait 24 hours after approval for activation
4. Check rate limits (6 requests per minute with key)

Database Too Large

Problem: CVE database is 200+ MB

Solutions:

1. Compress the database:

   dotnet run -- build --compress true

2. Filter by date:

   # Only last 180 days
   dotnet run -- scrape --days 180

3. Filter by source:

   # Only NuGet and NPM (skip NVD)
   dotnet run -- scrape --sources nuget npm

---

Configuration Reference

PrimusSecurityOptions

public class PrimusSecurityOptions
{
    // CVE Database path (optional)
    public string CveDatabasePath { get; set; } = "./SecurityData/cve-database.db";
    
    // Enable dependency scanning (requires CVE database)
    public bool EnableDependencyScanning { get; set; } = false;
    
    // Other options...
    public bool EnableSecretDetection { get; set; } = true;
    public bool EnableStaticAnalysis { get; set; } = true;
}

Example Configurations

Minimal (No CVE Database):

builder.Services.AddPrimusSecurity(options =>
{
    options.EnableSecretDetection = true;
    options.EnableStaticAnalysis = true;
    // Dependency scanning disabled by default
});

Full (With CVE Database):

builder.Services.AddPrimusSecurity(options =>
{
    options.EnableStaticAnalysis = true;
    options.EnableSecretDetection = true;
    options.EnableDependencyScanning = true;
    options.CveDatabasePath = "./SecurityData/cve-database.db";
    options.ComplianceStandards = new[] { "OWASP", "PCI-DSS" };
});

Custom Path:

builder.Services.AddPrimusSecurity(options =>
{
    options.EnableDependencyScanning = true;
    options.CveDatabasePath = "/var/security/cve-db.sqlite";
});

---

FAQ

Is the CVE database included in the NuGet package?

No. The CVE database is a separate 50-100MB file that must be downloaded or built separately. This keeps the NuGet package small and allows you to update the database independently.

How often should I update the database?

Weekly for production, monthly for development. New vulnerabilities are published daily, so regular updates ensure you catch the latest threats.

Can I use a shared CVE database across multiple projects?

Yes! Point multiple projects to the same database file:

options.CveDatabasePath = "C:\\SharedSecurity\\cve-database.db";

What happens if the database is missing?

Dependency scanning is automatically disabled. All other security features continue to work normally.

Can I use a different vulnerability database?

Yes. Implement the IVulnerabilityProvider interface:

public class CustomVulnerabilityProvider : IVulnerabilityProvider
{
    public Task<List<Vulnerability>> GetVulnerabilitiesAsync(string packageName, string version)
    {
        // Your custom logic
    }
}

Then register it:

builder.Services.AddSingleton<IVulnerabilityProvider, CustomVulnerabilityProvider>();

---

Next Steps

Want to...	See Guide
Get started without CVE database	Security Quick Start →
Understand all security features	Security Overview →
Use AI-powered security	Security AI →
Set up CI/CD scanning	Pipeline Integration →

---

Summary

✅ CVE database is optional - only needed for dependency scanning
✅ Three options: Skip it, download pre-built, or build your own
✅ Update weekly for production environments
✅ All other features work without the database