Documentation
¶
Overview ¶
Package osv implements an engine.Auditor backed by the OSV (Open Source Vulnerabilities) API.
Index ¶
- Constants
- func MapVulnerability(v Vulnerability) model.Vulnerability
- func Module() sdkplugin.Module
- type Affected
- type BatchQuery
- type BatchRequest
- type BatchResponse
- type BatchResult
- type Client
- type ClientConfig
- type Config
- type DatabaseSpecific
- type Event
- type KEVCatalog
- type Matcher
- func (a *Matcher) Applicable(_ context.Context, _ sdkplugin.MatchRequest) (bool, error)
- func (a *Matcher) Descriptor() sdkplugin.MatcherDescriptor
- func (a *Matcher) Match(_ context.Context, req sdkplugin.MatchRequest) (sdkplugin.MatchResult, error)
- func (a *Matcher) Ready(context.Context, sdkplugin.MatchRequest) error
- type NamePackage
- type PurlPackage
- type Range
- type Severity
- type VulnRef
- type Vulnerability
Constants ¶
const Name = "osv"
Name is the plugin's identity. It MUST equal the "id" field in bomly-plugin.json — Bomly refuses to load a plugin whose manifest id and runtime descriptor name disagree. It is also the descriptor name the Bomly CLI composition keys on when it embeds this matcher.
Variables ¶
This section is empty.
Functions ¶
func MapVulnerability ¶
func MapVulnerability(v Vulnerability) model.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 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 (*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 *httpkit.ClientProvider
}
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 *httpkit.ClientProvider
}
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 ¶
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.
type Matcher ¶
type Matcher struct {
// contains filtered or unexported fields
}
Matcher implements sdk.Matcher using the OSV API.
func New ¶
New creates a new OSV matcher. Returns an error if a configured package cache directory cannot be created; with no home directory and no configured one, it runs without that cache.
func (*Matcher) Applicable ¶
Applicable reports whether this matcher applies to the given request.
func (*Matcher) Descriptor ¶
func (a *Matcher) Descriptor() sdkplugin.MatcherDescriptor
Descriptor returns the matcher registration metadata.
func (*Matcher) Match ¶
func (a *Matcher) Match(_ context.Context, req sdkplugin.MatchRequest) (sdkplugin.MatchResult, error)
Match resolves vulnerabilities for all dependencies in the graph and attaches them to the PURL-keyed package registry.
Two response shapes exist. Legacy hosts get the request registry back, enriched in place (the protocol v1 baseline). When the request sets AcceptPackageUpdates, the registry is left untouched and the result carries PackageUpdates instead: one delta per enriched package holding only the PURL, Matched, and the vulnerability list. The host merges deltas by PURL; Package.MergeFrom unions vulnerabilities by (Source, ID) and ORs Matched in, so applying the deltas reproduces the in-place enrichment.
type NamePackage ¶
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 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 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}.