Documentation
¶
Index ¶
- Constants
- func CanonicalModuleVersion(modulePath, version string) string
- func CompareMavenVersions(a, b string) int
- func EnsureVPrefix(v string) string
- func ImportsLinked(imports []VulnerableImport, linked map[string]struct{}) bool
- func PreferVersion(a, b string) string
- func PreferredID(r *osvschema.Vulnerability) string
- func SeverityRank(severity string) int
- type Package
- type ScanResult
- type SecurityBump
- type Vulnerability
- type VulnerabilityCache
- func (c *VulnerabilityCache) Clear()
- func (c *VulnerabilityCache) Get(key string) ([]*osvschema.Vulnerability, bool)
- func (c *VulnerabilityCache) GetAdvisory(id string) (*osvschema.Vulnerability, bool)
- func (c *VulnerabilityCache) Set(key string, vulns []*osvschema.Vulnerability)
- func (c *VulnerabilityCache) SetAdvisory(id string, record *osvschema.Vulnerability)
- func (c *VulnerabilityCache) Size() int
- type VulnerabilityScanner
- func (vs *VulnerabilityScanner) Advisories(ctx context.Context, pkgs []Package) ([]*osvschema.Vulnerability, error)
- func (vs *VulnerabilityScanner) Advisory(ctx context.Context, id string) (*osvschema.Vulnerability, error)
- func (vs *VulnerabilityScanner) ScanPackages(ctx context.Context, pkgs []Package) (*ScanResult, error)
- type VulnerableImport
Constants ¶
const TargetGOOS = "linux"
TargetGOOS is the platform CHOAM's artifacts are built for - melange builds linux packages, period. An advisory whose vulnerable code is GOOS-constrained to other platforms can never affect anything CHOAM manages.
Variables ¶
This section is empty.
Functions ¶
func CanonicalModuleVersion ¶ added in v0.4.0
CanonicalModuleVersion returns version in the only spelling Go accepts for modulePath: a path without a major suffix (/vN, gopkg.in's .vN) can carry a v2+ version only as +incompatible, which OSV fix events and hand-written pins often omit. Anything else (v0/v1, a suffixed path, a version already carrying build metadata, a non-semver string) is returned unchanged.
func CompareMavenVersions ¶ added in v0.3.0
CompareMavenVersions is a best-effort Maven version comparator: it splits on '.' and '-' and compares each segment numerically when both sides parse as integers, falling back to lexical comparison otherwise. It does not implement Maven's qualifier ordering (e.g. alpha < beta < milestone < rc < (release) < sp) - only good enough to pick a plausible "newer" fix version. Exported for reuse by the Java/Maven ecosystem's own bump-filtering logic.
func EnsureVPrefix ¶ added in v0.3.0
EnsureVPrefix normalizes a version string for golang.org/x/mod/semver, which requires a "v" prefix. Exported for reuse by ecosystems comparing semver-ish versions (e.g. crates.io versions, which lack the prefix).
func ImportsLinked ¶ added in v0.4.0
func ImportsLinked(imports []VulnerableImport, linked map[string]struct{}) bool
ImportsLinked reports whether an advisory's vulnerable imports intersect linked, an artifact's import graph (built for TargetGOOS). It fails open (true) when linked is nil (graph unknown), when imports is empty (no metadata), and on a pathless entry (the whole module is vulnerable on that platform). An entry GOOS-constrained away from TargetGOOS is ignored: its code can never be in a TargetGOOS artifact, so it never counts as linked (an advisory whose entries are all excluded is unreachable here anyway - processVulnerability drops it, see applicableToTarget).
func PreferVersion ¶ added in v0.4.0
PreferVersion picks which of two spellings of the same version to keep (semver ignores build metadata, so v2.8.2 and v2.8.2+incompatible compare equal): the one carrying build metadata, else the lexically greater. The choice is a total order, so it never depends on which spelling was seen first. Versions may be bare or "v"-prefixed.
func PreferredID ¶ added in v0.4.0
func PreferredID(r *osvschema.Vulnerability) string
PreferredID is the identifier an advisory is reported by: its smallest CVE-, else its smallest GHSA-, else the record ID. Only the representative record (ID + aliases) is consulted, so the choice cannot drift between a baseline scan and a rescan that hydrates a different set of alias records.
func SeverityRank ¶ added in v0.3.0
SeverityRank orders severity labels most-critical-first for sorting: CRITICAL < HIGH < MEDIUM < LOW < everything else (UNKNOWN, empty).
Types ¶
type Package ¶ added in v0.3.0
type Package struct {
Name string // OSV package name: Go module path, bare crate name, "groupId:artifactId", etc.
Version string
Ecosystem string // OSV.dev ecosystem id: "Go", "crates.io", "Maven", ...
}
Package identifies a single dependency to query OSV for. Version may carry a leading "v" (Go's convention) or not (most other ecosystems') - it is normalized internally as needed for comparison.
type ScanResult ¶
type ScanResult struct {
Vulnerabilities []Vulnerability `json:"vulnerabilities"`
SecurityBumps []SecurityBump `json:"security_bumps"`
Error string `json:"error,omitempty"`
}
ScanResult contains the results of a vulnerability scan
type SecurityBump ¶ added in v0.3.0
type SecurityBump struct {
Name string `json:"name"`
Ecosystem string `json:"ecosystem"`
CurrentVersion string `json:"current_version"`
FixedVersion string `json:"fixed_version"`
VulnIDs []string `json:"vuln_ids,omitempty"` // advisories addressed by this bump
// Severity is the most severe normalized level (see SeverityRank) among
// the addressed advisories; empty when none carries severity data.
Severity string `json:"severity,omitempty"`
}
SecurityBump is a recommended fix: bump Name from CurrentVersion to FixedVersion.
type Vulnerability ¶
type Vulnerability struct {
ID string `json:"id"` // CVE first, see PreferredID
Module string `json:"module"`
Ecosystem string `json:"ecosystem"`
CurrentVersion string `json:"current_version"`
FixedVersion string `json:"fixed_version,omitempty"`
Severity string `json:"severity,omitempty"`
Summary string `json:"summary,omitempty"`
DatabaseSpecific any `json:"database_specific,omitempty"`
// VulnerableImports are the packages the vulnerable code actually lives
// in, from the Go vulndb's ecosystem_specific.imports metadata (Go
// advisories only; empty when the record carries none). Consumers use
// this for artifact-level reachability: a module can be linked into a
// binary while the specific vulnerable package is not.
VulnerableImports []VulnerableImport `json:"vulnerable_imports,omitempty"`
// Aliases are every other identifier of this advisory (the collapsed
// group's record IDs and their aliases, minus ID), sorted.
Aliases []string `json:"aliases,omitempty"`
}
Vulnerability represents a security vulnerability with fix information
type VulnerabilityCache ¶
type VulnerabilityCache struct {
// contains filtered or unexported fields
}
VulnerabilityCache provides a thread-safe per-run cache of OSV lookups: batch-query results by package@version, and full advisory records by ID (one advisory typically affects many packages and recurs across files). Cached values are shared pointers returned directly to callers - treat them as read-only; mutating a cached *osvschema.Vulnerability corrupts every other holder.
func GetGlobalCache ¶
func GetGlobalCache() *VulnerabilityCache
GetGlobalCache returns the shared global vulnerability cache
func NewVulnerabilityCache ¶
func NewVulnerabilityCache() *VulnerabilityCache
NewVulnerabilityCache creates a new vulnerability cache
func (*VulnerabilityCache) Clear ¶
func (c *VulnerabilityCache) Clear()
Clear removes all entries from the cache
func (*VulnerabilityCache) Get ¶
func (c *VulnerabilityCache) Get(key string) ([]*osvschema.Vulnerability, bool)
Get retrieves cached vulnerability results for a package@version key Returns the vulnerabilities and true if found, empty slice and false if not found
func (*VulnerabilityCache) GetAdvisory ¶ added in v0.4.0
func (c *VulnerabilityCache) GetAdvisory(id string) (*osvschema.Vulnerability, bool)
GetAdvisory returns the cached full record for an advisory ID.
func (*VulnerabilityCache) Set ¶
func (c *VulnerabilityCache) Set(key string, vulns []*osvschema.Vulnerability)
Set stores vulnerability results for a package@version key
func (*VulnerabilityCache) SetAdvisory ¶ added in v0.4.0
func (c *VulnerabilityCache) SetAdvisory(id string, record *osvschema.Vulnerability)
SetAdvisory caches the full record for an advisory ID.
func (*VulnerabilityCache) Size ¶
func (c *VulnerabilityCache) Size() int
Size returns the number of entries in the cache
type VulnerabilityScanner ¶
type VulnerabilityScanner struct {
// contains filtered or unexported fields
}
VulnerabilityScanner handles scanning package dependencies for security vulnerabilities
func NewVulnerabilityScanner ¶
func NewVulnerabilityScanner(httpClient *http.Client) *VulnerabilityScanner
NewVulnerabilityScanner creates a new vulnerability scanner with the global cache The httpClient parameter is required and should be obtained from httpclient.NewHTTPClientWithTimeout()
func (*VulnerabilityScanner) Advisories ¶ added in v0.4.0
func (vs *VulnerabilityScanner) Advisories(ctx context.Context, pkgs []Package) ([]*osvschema.Vulnerability, error)
Advisories returns the full OSV records affecting pkgs, unclassified: hydrated, withdrawn records dropped, deduplicated by ID (one advisory listed under several packages - e.g. a CGA- record under both Wolfi and Chainguard - is returned once), in first-seen order. Like ScanPackages it fails closed: an incomplete page or a failed lookup is an error.
func (*VulnerabilityScanner) Advisory ¶ added in v0.4.0
func (vs *VulnerabilityScanner) Advisory(ctx context.Context, id string) (*osvschema.Vulnerability, error)
Advisory returns the full OSV record for id (cached per run), or nil when OSV has no such record.
func (*VulnerabilityScanner) ScanPackages ¶ added in v0.3.0
func (vs *VulnerabilityScanner) ScanPackages(ctx context.Context, pkgs []Package) (*ScanResult, error)
ScanPackages scans a set of packages for known vulnerabilities via the OSV batch API, using the cache to avoid duplicate lookups within a run. This is the ecosystem-agnostic entry point: callers (one per language) are responsible for turning their own manifest format into a []Package list, having already applied any ecosystem-specific rewriting (e.g. Go's replace directives, or skipping local/vendored dependencies).
type VulnerableImport ¶ added in v0.3.0
type VulnerableImport struct {
Path string `json:"path,omitempty"`
GOOS []string `json:"goos,omitempty"`
}
VulnerableImport is one ecosystem_specific.imports entry of a Go advisory: the import path containing the vulnerable code, and the platforms it is constrained to (empty GOOS = all platforms).
Source Files