vulns

vulns

Go library for fetching vulnerability data from multiple sources using Package URLs (PURLs) as the primary identifier.

Installation

go get github.com/git-pkgs/vulns

Usage

Query vulnerabilities for a package:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/git-pkgs/purl"
    "github.com/git-pkgs/vulns"
    "github.com/git-pkgs/vulns/osv"
)

func main() {
    ctx := context.Background()
    source := osv.New()

    p := purl.MakePURL("npm", "lodash", "4.17.20")

    results, err := source.Query(ctx, p)
    if err != nil {
        log.Fatal(err)
    }

    for _, v := range results {
        fmt.Printf("%s: %s (severity: %s)\n", v.ID, v.Summary, v.SeverityLevel())
        if fixed := v.FixedVersion("npm", "lodash"); fixed != "" {
            fmt.Printf("  Fixed in: %s\n", fixed)
        }
    }
}

Sources

OSV (Open Source Vulnerabilities)

Free, public API from Google. No authentication required. Supports batch queries up to 1000 packages.

import "github.com/git-pkgs/vulns/osv"

source := osv.New()

// Batch query
results, err := source.QueryBatch(ctx, []*purl.PURL{p1, p2, p3})

deps.dev

Free API from Google with no authentication. Covers npm, PyPI, Go, Maven, Cargo, NuGet, RubyGems. Supports batch queries up to 5000 packages.

import "github.com/git-pkgs/vulns/depsdev"

source := depsdev.New()

GitHub Security Advisories (GHSA)

Free public API. Authentication optional but recommended to avoid rate limits.

import "github.com/git-pkgs/vulns/ghsa"

source := ghsa.New()

// With authentication for higher rate limits:
source := ghsa.New(ghsa.WithToken("ghp_xxxx"))

NVD (National Vulnerability Database)

NIST's CVE database. Free but rate-limited. API key recommended.

• Without key: 5 requests per 30 seconds
• With key: 50 requests per 30 seconds

import "github.com/git-pkgs/vulns/nvd"

source := nvd.New()

// With API key for higher rate limits:
source := nvd.New(nvd.WithAPIKey("your-api-key"))

Note: NVD uses CVE/CPE identifiers, so PURL-to-package matching is approximate.

Grype Database

Local SQLite database from Anchore. Updated every few hours at grype.anchore.io. No network requests after initial download.

import "github.com/git-pkgs/vulns/grypedb"

// Auto-download if missing
source, err := grypedb.New("/path/to/cache", grypedb.WithAutoDownload())
if err != nil {
    log.Fatal(err)
}
defer source.Close()

// Or download manually
dbPath, err := grypedb.Download(ctx, "/path/to/cache")
source, err := grypedb.New(dbPath)

VulnCheck

Commercial API with native PURL support. Requires authentication.

import "github.com/git-pkgs/vulns/vulncheck"

source := vulncheck.New(vulncheck.WithToken("your-api-token"))

Vulnerability-Lookup

Free, public API from vulnerability-lookup.org. Queries by vendor/product, so PURL mapping may be approximate.

import "github.com/git-pkgs/vulns/vl"

source := vl.New()

Data Model

All sources return vulnerabilities in OSV format:

type Vulnerability struct {
    ID        string
    Summary   string
    Details   string
    Aliases   []string     // Other IDs (CVE, GHSA, etc.)
    Published time.Time
    Modified  time.Time
    Severity  []Severity
    Affected  []Affected
    References []Reference
}

Working with CVSS

The library includes a CVSS parser supporting v2.0, v3.0, v3.1, and v4.0:

// Get severity level
level := vuln.SeverityLevel() // "critical", "high", "medium", "low", "unknown"

// Get numeric score
score := vuln.CVSSScore() // 0.0-10.0, or -1 if unavailable

// Get full CVSS details
cvss := vuln.CVSS()
if cvss != nil {
    fmt.Printf("CVSS %s: %.1f (%s)\n", cvss.Version, cvss.Score, cvss.Level)
}

// Parse a CVSS vector directly
cvss, err := vulns.ParseCVSS("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:N")

Version Matching

Check if a specific version is affected:

if vuln.IsVersionAffected("npm", "lodash", "4.17.20") {
    fmt.Println("Version is vulnerable")
}

if fixed := vuln.FixedVersion("npm", "lodash"); fixed != "" {
    fmt.Printf("Upgrade to %s\n", fixed)
}

Source Interface

All sources implement the same interface:

type Source interface {
    Name() string
    Query(ctx context.Context, p *purl.PURL) ([]Vulnerability, error)
    QueryBatch(ctx context.Context, purls []*purl.PURL) ([][]Vulnerability, error)
    Get(ctx context.Context, id string) (*Vulnerability, error)
}

Supported Ecosystems

License

MIT