Documentation
¶
Overview ¶
Package osv provides OSV integration and conversion into Deputy's vulnerability domain types. It owns:
- OSV API batch queries and vulnerability expansion
- GitHub Actions bucket ingestion and version resolution
- Conversion into internal/vulnerability domain models
This package is integration-focused; callers should rely on internal/vulnerability for domain logic.
Index ¶
- func FindBestSeverity(vulns []Vulnerability) (string, string)
- func NewClient() *osvdev.OSVClient
- func ProcessOSVVulnerabilityDomain(vuln osvschema.Vulnerability, input PkgInput) (vulnerabilityv1.Advisory, vulnerability.Finding)
- func Query(ctx context.Context, client Client, pkgs []PkgInput) ([]vulnerability.Finding, map[string]*vulnerabilityv1.Advisory, error)
- func QueryProto(ctx context.Context, client Client, pkgs []*dependencyv1.Package) ([]*vulnerabilityv1.Finding, map[string]*vulnerabilityv1.Advisory, error)
- func VulnerabilitiesToFindings(vulns []Vulnerability) []*vulnerabilityv1.Finding
- type Client
- type PackageContext
- type PkgInput
- type QueryKey
- type Vulnerability
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FindBestSeverity ¶
func FindBestSeverity(vulns []Vulnerability) (string, string)
FindBestSeverity chooses the most meaningful severity across related vulns. Prefers GHSA textual severities when HIGH/CRITICAL, otherwise the highest CVSS score.
func NewClient ¶
NewClient returns an osv.dev client configured with production-friendly HTTP timeouts and automatic retry for transient failures.
Callers should still pass a cancelable context; this function primarily protects against hung connections and slow/broken networks. The retryable HTTP client automatically handles 5xx errors and connection failures with exponential backoff.
Set DEPUTY_OSV_BASE_URL to point to a custom OSV API endpoint (e.g., a test server or mirror).
func ProcessOSVVulnerabilityDomain ¶
func ProcessOSVVulnerabilityDomain(vuln osvschema.Vulnerability, input PkgInput) (vulnerabilityv1.Advisory, vulnerability.Finding)
ProcessOSVVulnerabilityDomain converts a raw OSV vulnerability into the domain Advisory + Finding pair, keeping the advisory metadata separate from scan-time occurrence details.
func Query ¶
func Query(ctx context.Context, client Client, pkgs []PkgInput) ([]vulnerability.Finding, map[string]*vulnerabilityv1.Advisory, error)
Query performs a batched OSV vulnerability lookup and returns domain types. This is the primary API for scan operations that need findings and advisories.
func QueryProto ¶
func QueryProto(ctx context.Context, client Client, pkgs []*dependencyv1.Package) ([]*vulnerabilityv1.Finding, map[string]*vulnerabilityv1.Advisory, error)
QueryProto performs a batched OSV vulnerability lookup and returns proto types directly.
Parameters:
- pkgs: slice of proto Package messages representing the packages to scan
Returns:
- findings: slice of proto Finding messages
- advisories: map of advisory IDs to proto Advisory messages
- error: any error encountered during the query
func VulnerabilitiesToFindings ¶
func VulnerabilitiesToFindings(vulns []Vulnerability) []*vulnerabilityv1.Finding
VulnerabilitiesToFindings converts flat Vulnerability records to proto Findings.
Types ¶
type Client ¶
type Client interface {
QueryBatch(ctx context.Context, queries []*osvdev.Query) (*osvdev.BatchedResponse, error)
GetVulnByID(ctx context.Context, id string) (*osvschema.Vulnerability, error)
}
Client abstracts the subset of osv.dev client functionality required for batch querying and vulnerability expansion. It is satisfied by osvdev.DefaultClient enabling dependency injection in tests.
type PackageContext ¶
type PackageContext struct {
// IsDirect indicates if this is a direct dependency.
IsDirect bool
// Locations lists file paths where the dependency was found.
Locations []string
// ManifestRefs describes manifest files declaring this dependency.
ManifestRefs []dependencyv1.ManifestRef
// LayerDetails contains information about the container image layer where
// the package was found. Nil for non-container-image scans.
LayerDetails *containerv1.LayerDetails
}
PackageContext contains scan-time context about where a package was found. This information is not needed for OSV queries but is preserved for findings.
type PkgInput ¶
type PkgInput struct {
QueryKey
PackageContext
}
PkgInput represents a single package@version query along with scan-time context. It combines QueryKey (for OSV queries) with PackageContext (for findings).
For new code, prefer using QueryKey and PackageContext separately when possible.
func NewPkgInput ¶
func NewPkgInput(key QueryKey, ctx PackageContext) PkgInput
NewPkgInput creates a PkgInput from a QueryKey and PackageContext.
type QueryKey ¶
type QueryKey struct {
// Name is the package/module name (e.g., "github.com/foo/bar", "lodash").
Name string
// Version is the installed version string.
Version string
// Ecosystem identifies the package ecosystem for OSV queries (e.g., "Go", "npm").
Ecosystem string
// PURL is the Package URL providing a canonical identifier.
PURL string
}
QueryKey identifies a package for OSV queries. This is the cacheable, query-focused subset of package identity.
type Vulnerability ¶
type Vulnerability struct {
ID string
Aliases []string
Summary string
Details string
CVE string
Severity string
SeverityType string
Package string
Version string
IsDirect bool
Ecosystem string
PURL string
Published string
Modified string
References []string
FixedVersions []string
Affected bool
Locations []string
ManifestRefs []dependencyv1.ManifestRef
AffectedImports []vulnerabilityv1.AffectedImport
DatabaseSpecific map[string]string
LayerDetails *containerv1.LayerDetails
}
Vulnerability represents a security vulnerability found in a software package. This is the flattened output format used by the OSV query layer for backward compatibility. For new code, prefer using vulnerabilityv1.Advisory and vulnerability.Finding.
func ProcessOSVVulnerability ¶
func ProcessOSVVulnerability(vuln osvschema.Vulnerability, input PkgInput) Vulnerability
ProcessOSVVulnerability converts a raw OSV schema vulnerability into the internal Vulnerability representation scoped to a specific package@version. It selects a stable preferred identifier (CVE where present, else GO-/GHSA-), normalizes timestamp formatting, extracts reference URLs, severity score/type preference (favoring CVSS metrics unless GHSA severity is authoritative), and aggregates fixed version markers relevant to the matched package.
Source Files