osv

package
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 30, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package osv implements an engine.Auditor backed by the OSV (Open Source Vulnerabilities) API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MapVulnerability

func MapVulnerability(v Vulnerability) sdk.Vulnerability

MapVulnerability converts one OsvVulnerability into an OSV-aligned sdk.Vulnerability, carrying the spec fields through verbatim and computing Bomly enrichment extensions (parsed severity band, CVSS scores, CWEs, fix).

Types

type Affected

type Affected struct {
	Versions []string `json:"versions"`
	Ranges   []Range  `json:"ranges"`
}

Affected holds version ranges and specific affected versions.

type BatchQuery

type BatchQuery struct {
	Package json.RawMessage `json:"package"`
	Version string          `json:"version,omitempty"`
}

BatchQuery is one entry in the OSV batch request wire format. Exactly one of PurlPkg or NamePkg will be set inside the Package field.

type BatchRequest

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

BatchRequest is the wire body for POST /v1/querybatch.

type BatchResponse

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

BatchResponse is the top-level response from POST /v1/querybatch.

type BatchResult

type BatchResult struct {
	Vulns []VulnRef `json:"vulns"`
}

BatchResult is the result for one query in the batch. The /v1/querybatch endpoint returns only the ID and modified timestamp; use Client.GetVuln to retrieve the full vulnerability detail.

type Client

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

Client is an HTTP client for the OSV batch API.

func NewClient

func NewClient(config ClientConfig) *Client

NewClient creates a new OSV client.

func (*Client) GetVuln

func (c *Client) GetVuln(id string) (*Vulnerability, error)

GetVuln fetches the full vulnerability record for the given OSV ID. Use this after query batch to enrich the minimal VulnRef data.

func (*Client) QueryBatch

func (c *Client) QueryBatch(queries []BatchQuery) ([]BatchResult, error)

QueryBatch sends a batch of queries to OSV and returns one result per query. Automatically splits queries into chunks of config.BatchSize.

type ClientConfig

type ClientConfig struct {
	APIBase            string
	Timeout            time.Duration
	BatchSize          int
	HTTPClient         *http.Client
	HTTPClientProvider *sdk.HTTPClientProvider
}

ClientConfig configures the OSV HTTP client.

func DefaultClientConfig

func DefaultClientConfig() ClientConfig

DefaultClientConfig returns a production-ready default config.

type Config

type Config struct {
	// APIBase overrides the OSV API base URL. Defaults to https://api.osv.dev.
	APIBase string
	// CacheDir overrides the cache directory. Defaults to ~/.bomly/cache/osv.
	CacheDir string
	// CacheTTL is the time-to-live for cached results. Defaults to 24 hours.
	CacheTTL time.Duration
	// BypassCache forces a fresh fetch even when a cached result exists.
	BypassCache bool
	// EnableKEV enables the KEV enrichment pass. Defaults to true.
	EnableKEV bool
	// KEVCacheDir overrides the KEV cache directory. Defaults to ~/.bomly/cache/kev.
	KEVCacheDir string
	// KEVCacheTTL is the TTL for the cached KEV catalog. Defaults to 6 hours.
	KEVCacheTTL time.Duration
	// VulnDetailCacheDir overrides the vuln-detail cache directory.
	// Defaults to ~/.bomly/cache/osv-vulns.
	VulnDetailCacheDir string
	// VulnDetailCacheTTL is the TTL for cached per-vuln detail records.
	// Defaults to 7 days (vuln records seldom change once published).
	VulnDetailCacheTTL time.Duration
	// Logger receives diagnostic messages. Maybe nil (no-op).
	Logger *zap.Logger
	// Stderr is used for progress messages. Maybe nil.
	Stderr io.Writer
	// Client overrides the OSV HTTP client. Maybe nil.
	Client *http.Client
	// KEVClient overrides the CISA KEV HTTP client. Maybe nil.
	KEVClient *http.Client
	// HTTPClientProvider supplies shared HTTP clients when Client/KEVClient are nil.
	HTTPClientProvider *sdk.HTTPClientProvider
}

Config configures the OSV matcher.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a production-ready OSV matcher config.

type DatabaseSpecific

type DatabaseSpecific struct {
	CweIDs []string `json:"cwe_ids,omitempty"`
	// Severity is GitHub Security Advisory's textual rating (LOW / MODERATE /
	// HIGH / CRITICAL). GHSA-sourced OSV entries frequently omit a CVSS vector
	// in the top-level `severity` array, so this is the only severity signal
	// available for them.
	Severity string `json:"severity,omitempty"`
}

DatabaseSpecific holds ecosystem-specific metadata (e.g., CWE IDs from GitHub).

type Event

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

Event holds introduced/fixed/last_affected markers.

type KEVCatalog

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

KEVCatalog is the in-memory representation of the CISA KEV catalog.

func FetchKEVCatalog

func FetchKEVCatalog(cache *audcache.FileCache, clients ...*http.Client) (*KEVCatalog, error)

FetchKEVCatalog downloads the CISA KEV catalog, using the provided cache when available. Cache may be nil — in that case the catalog is always fetched fresh. Returns (nil, nil) if the request fails — callers treat absence as informational.

func (*KEVCatalog) Contains

func (k *KEVCatalog) Contains(id string, aliases []string) bool

Contains reports whether id (or any alias) is in the KEV catalog.

type Matcher

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

Matcher implements matchers.Matcher using the OSV API.

func New

func New(config Config) (*Matcher, error)

New creates a new OSV matcher. Returns an error if the cache directory cannot be created.

func (*Matcher) Applicable

func (a *Matcher) Applicable(_ context.Context, _ sdk.MatchRequest) (bool, error)

Applicable reports whether this matcher applies to the given request.

func (*Matcher) Descriptor

func (a *Matcher) Descriptor() sdk.MatcherDescriptor

Descriptor returns the matcher registration metadata.

func (*Matcher) Match

Match resolves vulnerabilities for all dependencies in the graph and attaches them to the PURL-keyed package registry.

func (*Matcher) Ready

Ready reports whether this matcher can run. OSV requires no local binary.

type NamePackage

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

NamePackage is the wire shape for name+ecosystem OSV queries.

type PurlPackage

type PurlPackage struct {
	Purl string `json:"purl"`
}

PurlPackage is the wire shape for PURL-based OSV queries.

type Range

type Range struct {
	Events []Event `json:"events"`
}

Range holds a single range entry.

type Severity

type Severity struct {
	Type  string `json:"type"`  // e.g. "CVSS_V3", "CVSS_V4"
	Score string `json:"score"` // vector string or numeric score
}

Severity holds a CVSS vector and type.

type VulnRef

type VulnRef struct {
	ID       string `json:"id"`
	Modified string `json:"modified"`
}

VulnRef is the minimal vulnerability entry returned by POST /v1/querybatch.

type Vulnerability

type Vulnerability struct {
	ID               string            `json:"id"`
	Summary          string            `json:"summary"`
	Details          string            `json:"details"`
	Aliases          []string          `json:"aliases"`
	Severity         []Severity        `json:"severity"`
	Affected         []Affected        `json:"affected"`
	Published        string            `json:"published"`
	Modified         string            `json:"modified"`
	DatabaseSpecific *DatabaseSpecific `json:"database_specific,omitempty"`
}

Vulnerability is the full vulnerability as returned by GET /v1/vulns/{id}.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL