osv

Documentation

Overview

Package osv provides a client for the OSV.dev vulnerability database API.

OSV.dev (https://osv.dev) is a free, open vulnerability database that covers all major package ecosystems: npm, PyPI, Go, crates.io, Maven, RubyGems, and Packagist.

API

This client uses the batch query endpoint for efficient scanning:

POST https://api.osv.dev/v1/querybatch

A single batch request can check hundreds of packages at once, making it suitable for scanning entire dependency trees.

Usage

client := osv.NewClient(nil)  // nil = default HTTP client
resp, err := client.QueryBatch(ctx, []osv.Query{
    {Package: osv.PackageQuery{Name: "requests", Ecosystem: "PyPI"}, Version: "2.28.0"},
})

Rate Limits

OSV.dev has generous rate limits for the public API. No authentication is required. The client does not implement its own rate limiting; callers should handle integrations.RateLimitedError if needed.

Index

• Constants
• type Affected
• type AffectedPackage
• type BatchRequest
• type BatchResponse
• type Client
  • func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client
  • func (c *Client) GetVulnerability(ctx context.Context, id string, refresh bool) (*Vulnerability, error)
  • func (c *Client) QueryBatch(ctx context.Context, queries []Query, refresh bool) ([]QueryResult, error)
• type Event
• type PackageQuery
• type Query
• type QueryResult
• type Range
• type Reference
• type SeverityEntry
• type Vulnerability

Constants

const (
	// DefaultBaseURL is the OSV.dev API endpoint.
	DefaultBaseURL = "https://api.osv.dev"

	// DefaultTimeout is the HTTP request timeout for OSV API calls.
	// Batch queries can take longer than single-package lookups.
	DefaultTimeout = 30 * time.Second

	// MaxBatchSize is the maximum number of queries per batch request.
	// OSV.dev supports up to 1000 queries per batch.
	MaxBatchSize = 1000

	// DefaultCacheTTL is how long vulnerability data is cached.
	// Vulnerability data changes less frequently than package metadata.
	DefaultCacheTTL = 6 * time.Hour
)

Types

type Affected

type Affected struct {
	Package  AffectedPackage `json:"package"`
	Ranges   []Range         `json:"ranges,omitempty"`
	Versions []string        `json:"versions,omitempty"`
}

Affected describes the affected package versions.

type AffectedPackage

type AffectedPackage struct {
	Name      string `json:"name"`
	Ecosystem string `json:"ecosystem"`
}

AffectedPackage identifies an affected package.

type BatchRequest

type BatchRequest struct {
	Queries []Query `json:"queries"`
}

BatchRequest is the request body for the /v1/querybatch endpoint.

type BatchResponse

type BatchResponse struct {
	Results []QueryResult `json:"results"`
}

BatchResponse is the response from the /v1/querybatch endpoint.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client queries the OSV.dev vulnerability database. It supports response caching and proactive rate limiting.

Client is safe for concurrent use by multiple goroutines.

func NewClient

func NewClient(backend cache.Cache, cacheTTL time.Duration) *Client

NewClient creates an OSV.dev client with optional caching.

Parameters:

• backend: Cache backend for response caching. If nil, no caching is performed.
• cacheTTL: How long to cache responses. If <= 0, uses DefaultCacheTTL.

Rate limits are configured via integrations.DefaultRateLimits["osv"].

func (*Client) GetVulnerability

func (c *Client) GetVulnerability(ctx context.Context, id string, refresh bool) (*Vulnerability, error)

GetVulnerability fetches full vulnerability details for a single OSV ID.

Unlike querybatch, this endpoint usually includes rich fields such as summary/details/references and complete affected ranges.

func (*Client) QueryBatch

func (c *Client) QueryBatch(ctx context.Context, queries []Query, refresh bool) ([]QueryResult, error)

QueryBatch queries OSV.dev for vulnerabilities affecting the given packages. If len(queries) exceeds MaxBatchSize, the request is automatically split into multiple batches and results are merged.

Results are cached based on the query contents. Set refresh=true to bypass cache.

Returns a slice of QueryResult in the same order as the input queries. Each result contains the vulnerabilities found for that query (may be empty).

Returns an error for network failures or non-200 API responses.

type Event

type Event struct {
	Introduced string `json:"introduced,omitempty"`
	Fixed      string `json:"fixed,omitempty"`
}

Event marks a point in the version history where the vulnerability was introduced or fixed.

type PackageQuery

type PackageQuery struct {
	Name      string `json:"name"`
	Ecosystem string `json:"ecosystem"`
}

PackageQuery identifies a package in a specific ecosystem.

type Query

type Query struct {
	Package PackageQuery `json:"package"`
	Version string       `json:"version,omitempty"`
}

Query represents a single vulnerability lookup.

type QueryResult

type QueryResult struct {
	Vulns []Vulnerability `json:"vulns,omitempty"`
}

QueryResult contains vulnerabilities found for a single query.

type Range

type Range struct {
	Type   string  `json:"type"` // "SEMVER", "GIT", "ECOSYSTEM"
	Events []Event `json:"events,omitempty"`
}

Range describes a version range for the vulnerability.

type Reference

type Reference struct {
	Type string `json:"type"` // "ADVISORY", "FIX", "WEB", etc.
	URL  string `json:"url"`
}

Reference is a link to an advisory, patch, or other resource.

type SeverityEntry

type SeverityEntry struct {
	Type  string `json:"type"`  // e.g., "CVSS_V3"
	Score string `json:"score"` // e.g., "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
}

SeverityEntry contains a CVSS score or severity string.

type Vulnerability

type Vulnerability struct {
	ID       string    `json:"id"`
	Summary  string    `json:"summary"`
	Details  string    `json:"details,omitempty"`
	Aliases  []string  `json:"aliases,omitempty"`
	Modified time.Time `json:"modified"`

	// Severity from the database_specific or ecosystem_specific fields.
	Severity []SeverityEntry `json:"severity,omitempty"`

	// Affected packages and version ranges.
	Affected []Affected `json:"affected,omitempty"`

	// References to advisories, patches, etc.
	References []Reference `json:"references,omitempty"`
}

Vulnerability represents a single OSV vulnerability record.