VulnersDotNet 1.1.0

VulnersDotNet

.NET SDK for the Vulners.com vulnerability intelligence API.

Features

• Search — Lucene full-text search (with auto-pagination), exploit search, bulletin lookup by ID, references, history, KB seeds/updates, query autocomplete, CPE search, web-path vulnerabilities
• Audit — Linux package audit (RPM/DEB/APK), Windows KB and software audit, CPE-based software and host audit (V4), CVE audit, library/SBOM/manifest audit, Smart Audit (preview), package metadata (V4)
• Archive — OS CVE archive download (ZIP), collection and family download, incremental updates, and archive state
• Subscriptions — V4 subscriptions, legacy email subscriptions, and webhook subscriptions
• Reports & STIX — Linux Audit reports and STIX 2.1 bundle export
• Secure by default — API key sent only via the X-Api-Key header where possible, HTTPS enforced, and credentials redacted from error messages
• Multi-target — net10.0, net8.0, netstandard2.0
• DI-friendly — integrates with Microsoft.Extensions.DependencyInjection

Installation

dotnet add package VulnersDotNet

Quick start

using Microsoft.Extensions.DependencyInjection;
using VulnersDotNet;
using VulnersDotNet.Extensions;
using VulnersDotNet.Models;

var apiKey = Environment.GetEnvironmentVariable("VULNERS_API_KEY")
    ?? throw new InvalidOperationException("Set the VULNERS_API_KEY environment variable.");

var services = new ServiceCollection();
services.AddVulners(options =>
{
    options.ApiKey = apiKey;
});

using var provider = services.BuildServiceProvider();
var client = provider.GetRequiredService<IVulnersClient>();

Usage examples

Search

// Lucene search
var results = await client.Search.SearchAsync("type:cve", limit: 5);
foreach (var doc in results.Documents)
{
    Console.WriteLine($"[{doc.Source.Id}] {doc.Source.Title} (CVSS: {doc.Source.Cvss?.Score})");
}

// Get bulletin by ID
var bulletin = await client.Search.GetBulletinAsync("CVE-2021-44228");
Console.WriteLine($"{bulletin.Id}: {bulletin.Title}");

// Autocomplete
var suggestions = await client.Search.AutocompleteAsync("heartbleed");

// CPE search
var cpes = await client.Search.SearchCpeAsync("chrome", vendor: "google", size: 5);
Console.WriteLine($"Best match: {cpes.BestMatch}");

Linux package audit (V3, typed)

AuditPackagesAsync provides typed RPM/DEB results. Use LinuxAuditAsync for the V4 endpoint, including APK packages and extended audit options.

var audit = await client.Audit.AuditPackagesAsync(
    os: "debian",
    version: "12",
    packages: new[] { "openssl 3.0.9-1 amd64" });

Console.WriteLine($"Vulnerabilities: {audit.Vulnerabilities.Count}");
Console.WriteLine($"Fix: {audit.CumulativeFix}");

CPE-based software audit (V4)

var results = await client.Audit.AuditSoftwareAsync(
    software: new CpeSoftwareInput[]
    {
        new CpeObject { Vendor = "openssl", Product = "openssl", Version = "3.0.9" }
    },
    match: "partial");

foreach (var item in results)
{
    Console.WriteLine($"CPE: {item.MatchedCriteria}");
    foreach (var vuln in item.Vulnerabilities)
    {
        Console.WriteLine($"  {vuln.Id}: {vuln.Title}");
    }
}

Host context audit (V4)

var results = await client.Audit.AuditHostAsync(
    software: new CpeSoftwareInput[]
    {
        new CpeObject { Part = "a", Vendor = "openssh", Product = "openssh", Version = "8.5" }
    },
    operatingSystem: new CpeObject
    {
        Part = "o", Vendor = "debian", Product = "debian_linux", Version = "12"
    });

Smart Audit (V4 preview)

Smart Audit resolves raw, free-form software descriptions to CPEs before auditing them. The preview contract may change and each submitted software string is billed.

var results = await client.Audit.AuditSmartAsync(
    software: new[] { "Adobe Reader 5.3", "OpenSSL 1.0.1" },
    catalog: "official"); // or "extended" for Vulners custom CPEs

foreach (var item in results)
{
    Console.WriteLine($"{item.Input} -> {item.Cpe} ({item.Confidence:P0})");
    foreach (var vulnerability in item.Vulnerabilities)
    {
        Console.WriteLine($"  {vulnerability.Id}: {vulnerability.Title}");
    }
}

Windows KB audit

var result = await client.Audit.AuditWindowsKbAsync(
    os: "Windows Server 2012 R2",
    kbList: new[] { "KB5009586", "KB5009624", "KB5008230" });

Console.WriteLine($"Missing KBs: {string.Join(", ", result.KbMissed)}");

Windows software audit

var result = await client.Audit.AuditWindowsAsync(
    os: "windows",
    osVersion: "10.0.19045",
    kbList: new[] { "KB5009586", "KB5009624" },
    software: new[]
    {
        new WindowsSoftwareEntry
        {
            Software = "7-Zip",
            Version = "19.00",
            TargetSw = "windows",
            TargetHw = "x64",
        },
    });

Console.WriteLine($"Vulnerabilities: {result.Vulnerabilities.Count}");

Supported OS list

var osList = await client.Audit.GetSupportedOsAsync();
Console.WriteLine(string.Join(", ", osList));

Archive download

using var zipStream = await client.Archive.DownloadDistributiveAsync("debian", "12");
using var fileStream = File.Create("debian-12-cves.zip");
await zipStream.CopyToAsync(fileStream);

Subscriptions (V4)

var subscriptions = await client.SubscriptionV4.GetListAsync();
var subscription = await client.SubscriptionV4.GetAsync("subscription-id");

Creation and updates accept the Vulners V4 subscription query and delivery dictionaries through CreateAsync and UpdateAsync; subscriptions can be removed with DeleteAsync.

Legacy email subscriptions (V3, deprecated)

// List subscriptions
var subs = await client.Subscription.ListAsync();

// Add a subscription
await client.Subscription.AddAsync(
    query: "type:cve AND cvss.score:[9 TO 10]",
    email: "alerts@example.com",
    format: "html");

// Edit a subscription
await client.Subscription.EditAsync(subscriptionId: "sub-id", active: "no");

// Delete a subscription
await client.Subscription.DeleteAsync(subscriptionId: "sub-id");

V4 audit (CVE, library, SBOM)

// Audit a single CVE
var cve = await client.Audit.AuditCveAsync("CVE-2021-44228");

// Audit library packages (purl or ecosystem strings)
var lib = await client.Audit.AuditLibraryAsync(new[] { "pkg:pypi/django@3.0.0" });

// Audit a package manifest (maven, pip, poetry, npm, golang, uv)
var pkg = await client.Audit.AuditPackageAsync("pip", "django==3.0.0\n");

// Audit an SBOM file (CycloneDX / SPDX)
using var sbom = File.OpenRead("sbom.json");
var sbomResult = await client.Audit.SbomAuditAsync(sbom, "sbom.json");

API key info

var info = await client.Misc.GetApiKeyInfoAsync();
Console.WriteLine($"{info.LicenseType} license, {info.Credit} credits (active: {info.Active})");

Webhooks

await client.Webhook.AddAsync("type:cve AND cvss.score:[9 TO 10]");
var hooks = await client.Webhook.ListAsync();
var pending = await client.Webhook.ReadAsync(subscriptionId: "hook-id", newestOnly: true);
await client.Webhook.EnableAsync(subscriptionId: "hook-id", active: false);
await client.Webhook.DeleteAsync(subscriptionId: "hook-id");

Archive incremental sync

// Current state (cursor + document count) of a collection
var state = await client.Archive.GetCollectionStateAsync("cve");
Console.WriteLine($"cursor: {state.Cursor}, docs: {state.TotalDocs}");

// Records changed in the last hour (max 25h window)
var updates = await client.Archive.GetCollectionUpdateAsync(
    "cve", DateTimeOffset.UtcNow.AddHours(-1));

STIX bundle

var bundle = await client.Stix.MakeBundleByIdAsync("CVE-2021-44228");

API coverage

Configuration

services.AddVulners(options =>
{
    options.ApiKey = "your-api-key";
    options.BaseUrl = "https://vulners.com/api/";  // default (version-agnostic root)
    // The "v3/" and "v4/" segments are appended automatically to form V3BaseUrl / V4BaseUrl.
    // Override them individually only for a proxy or non-standard layout:
    // options.V4BaseUrl = "https://proxy.example.com/api/v4/";
    options.Timeout = TimeSpan.FromSeconds(30);     // default
});

URLs must use HTTPS; plain http:// is rejected except for loopback hosts (localhost, 127.0.0.1, ::1) to support local testing.

Security

• The API key is attached to outbound requests via the X-Api-Key header on the configured HttpClient. A few legacy V3 endpoints (webhook create/read, Windows winaudit) additionally require the key in the query or body and are documented as exceptions in code.
• HTTPS is enforced for all non-loopback endpoints so the key is never sent over plaintext.
• HTTP error bodies are redacted (API keys, tokens) and truncated before being surfaced in VulnersException messages, so credentials do not leak into logs.
• The key is read from configuration/environment; never hardcode it. Keep .env out of version control.

Project structure

vulners-dotnet/
├── src/
│   ├── VulnersDotNet/              # SDK library (net10.0;net8.0;netstandard2.0)
│   └── VulnersDotNet.Examples/     # Usage examples
└── tests/
    └── VulnersDotNet.Tests/        # Unit & integration tests (xUnit v3)

Development

# Build
dotnet build

# Format code
dotnet csharpier format .

# Run tests (credential-free tests pass; live integration tests skip without a key)
dotnet test

# Run live integration tests (provide the key through your environment or secret manager)
VULNERS_API_KEY=your-key dotnet test

License

MIT — Aleksandr Pavlov ckidoz@gmail.com