Documentation
¶
Overview ¶
Package osv implements an engine.Auditor backed by the OSV (Open Source Vulnerabilities) API.
Index ¶
- func MapVulnerability(v Vulnerability) sdk.Vulnerability
- type Affected
- type BatchQuery
- type BatchRequest
- type BatchResponse
- type BatchResult
- type Client
- type ClientConfig
- type Config
- type DatabaseSpecific
- type Event
- type KEVCatalog
- type Matcher
- type NamePackage
- type PurlPackage
- type Range
- type Severity
- type VulnRef
- type Vulnerability
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 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 *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"`
}
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 matchers.Matcher using the OSV API.
func New ¶
New creates a new OSV matcher. Returns an error if the cache directory cannot be created.
func (*Matcher) Applicable ¶
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 ¶
func (a *Matcher) Match(_ context.Context, req sdk.MatchRequest) (sdk.MatchResult, error)
Match resolves vulnerabilities for all dependencies in the graph and attaches them to the PURL-keyed package registry.
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}.