blob: 169d3a08d4a4910242f5956ea5cd392eff76bf84 [file] [log] [blame]
// Copyright 2023 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package osvutils provides utilities for working with Go OSV entries.
// It is separated from package osv because that package
// promises to only import from the standard library.
package osvutils
import (
"errors"
"fmt"
"strings"
"golang.org/x/vulndb/internal/derrors"
"golang.org/x/vulndb/internal/idstr"
"golang.org/x/vulndb/internal/osv"
"golang.org/x/vulndb/internal/version"
)
// Validate errors if there are any problems with the OSV Entry.
// It is used to validate OSV entries before publishing them to the
// Go vulnerability database, and has stricter requirements than
// the general OSV format.
func Validate(e *osv.Entry) (err error) {
derrors.Wrap(&err, "Validate(%s)", e.ID)
return validate(e, true)
}
// ValidateExceptTimestamps errors if there are any problems with the
// OSV Entry, with the exception of the timestamps (published, modified and
// withdrawn) which are not checked.
// This is used to validate entries at CL submit time, before their timestamps
// are corrected.
func ValidateExceptTimestamps(e *osv.Entry) (err error) {
derrors.Wrap(&err, "ValidateExceptTimestamps(%s)", e.ID)
return validate(e, false)
}
var (
// Errors for incorrect timestamps.
errNoModified = errors.New("modified time must be non-zero")
errNoPublished = errors.New("published time must be non-zero")
errPublishedAfterModified = errors.New("published time cannot be after modified time")
// Errors for missing fields.
errNoID = errors.New("id field is empty")
errNoSchemaVersion = errors.New("schema_version field is empty")
errNoSummary = errors.New("summary field is empty")
errNoDetails = errors.New("details field is empty")
errNoAffected = errors.New("affected field is empty")
errNoReferences = errors.New("references field is empty")
errNoDatabaseSpecific = errors.New("database_specific field is empty")
errNoModule = errors.New("affected field missing module path")
errNotGoEcosystem = errors.New("affected ecosystem is not Go")
errNoRanges = errors.New("affected field contains no ranges")
errNoEcosystemSpecific = errors.New("affected field contains no ecosystem_specific field")
errNoPackagePath = errors.New("affected.ecosystem_specific.imports field has no package path")
// Errors for invalid fields.
errInvalidAlias = errors.New("alias must be CVE or GHSA ID")
errInvalidPkgsiteURL = errors.New("database_specific.URL must be a link to https://pkg.go.dev/vuln/<Go id>")
errInvalidPackagePath = errors.New("package path must be prefixed by module path")
errTooManyRanges = errors.New("each module should have exactly one version range")
errRangeTypeNotSemver = errors.New("range type must be SEMVER")
errNoRangeEvents = errors.New("range must contain one or more events")
errOutOfOrderRange = errors.New("introduced and fixed versions must alternate")
errUnsortedRange = errors.New("range events must be in strictly ascending order")
errNoIntroducedOrFixed = errors.New("introduced or fixed must be set")
errBothIntroducedAndFixed = errors.New("introduced and fixed cannot both be set in same event")
errInvalidSemver = errors.New("invalid or non-canonical semver version")
)
func validate(e *osv.Entry, checkTimestamps bool) (err error) {
if checkTimestamps {
switch {
case e.Modified.IsZero():
return errNoModified
case e.Published.IsZero():
return errNoPublished
case e.Published.After(e.Modified.Time):
return fmt.Errorf("%w (published=%s, modified=%s)", errPublishedAfterModified, e.Published, e.Modified)
}
}
// Check for missing required fields.
switch {
case e.ID == "":
return errNoID
case e.SchemaVersion == "":
return errNoSchemaVersion
case e.Summary == "":
return errNoSummary
case e.Details == "" && !hasAdvisory(e):
return errNoDetails
case len(e.Affected) == 0:
return errNoAffected
case len(e.References) == 0:
return errNoReferences
case e.DatabaseSpecific == nil:
return errNoDatabaseSpecific
}
for _, a := range e.Affected {
if err := validateAffected(&a); err != nil {
return err
}
}
for _, alias := range e.Aliases {
if !idstr.IsAliasType(alias) {
return fmt.Errorf("%w (found alias %s)", errInvalidAlias, alias)
}
}
return validateDatabaseSpecific(e.DatabaseSpecific)
}
func hasAdvisory(entry *osv.Entry) bool {
for _, ref := range entry.References {
if ref.Type == osv.ReferenceTypeAdvisory {
return true
}
}
return false
}
func validateAffected(a *osv.Affected) error {
switch {
case a.Module.Path == "":
return errNoModule
case a.Module.Ecosystem != osv.GoEcosystem:
return errNotGoEcosystem
}
if err := ValidateRanges(a.Ranges); err != nil {
return err
}
return validateEcosystemSpecific(a.EcosystemSpecific, a.Module.Path)
}
func ValidateRanges(ranges []osv.Range) error {
switch {
case len(ranges) == 0:
return errNoRanges
case len(ranges) > 1:
return fmt.Errorf("%w (found %d ranges)", errTooManyRanges, len(ranges))
}
return validateRange(&ranges[0])
}
func validateRange(r *osv.Range) error {
switch {
case r.Type != osv.RangeTypeSemver:
return fmt.Errorf("%w (found range type %q)",
errRangeTypeNotSemver, r.Type)
case len(r.Events) == 0:
return errNoRangeEvents
}
// Check that all the events are valid and sorted in ascending order.
prev, err := parseRangeEvent(&r.Events[0])
if err != nil {
return err
}
for _, event := range r.Events[1:] {
current, err := parseRangeEvent(&event)
if err != nil {
return fmt.Errorf("invalid range event: %w", err)
}
// Introduced and fixed versions must alternate.
if current.introduced == prev.introduced {
return errOutOfOrderRange
}
if !less(prev.v, current.v) {
return fmt.Errorf("%w (found %s>=%s)", errUnsortedRange, prev.v, current.v)
}
prev = current
}
return nil
}
func less(v, w string) bool {
// Ensure that version 0 is always lowest.
if v == "0" {
return true
}
if w == "0" {
return false
}
return version.Before(v, w)
}
type event struct {
v string
introduced bool
}
func parseRangeEvent(e *osv.RangeEvent) (*event, error) {
introduced, fixed := e.Introduced, e.Fixed
var v string
var isIntroduced bool
switch {
case introduced == "" && fixed == "":
return nil, errNoIntroducedOrFixed
case introduced != "" && fixed != "":
return nil, errBothIntroducedAndFixed
case introduced == "0":
return &event{v: "0", introduced: true}, nil
case introduced != "":
v = introduced
isIntroduced = true
case fixed != "":
v = fixed
isIntroduced = false
}
if !version.IsValid(v) || v != version.Canonical(v) {
return nil, fmt.Errorf("%w (found %s)", errInvalidSemver, v)
}
return &event{v: v, introduced: isIntroduced}, nil
}
func validateEcosystemSpecific(es *osv.EcosystemSpecific, module string) error {
if es == nil {
return errNoEcosystemSpecific
}
for _, pkg := range es.Packages {
if pkg.Path == "" {
return errNoPackagePath
}
// Package path must be prefixed by module path unless it is
// in the Go standard library or toolchain.
if (module != osv.GoStdModulePath && module != osv.GoCmdModulePath) &&
!strings.HasPrefix(pkg.Path, module) {
return fmt.Errorf("%w (found module=%q, package=%q)", errInvalidPackagePath, module, pkg.Path)
}
}
return nil
}
func validateDatabaseSpecific(d *osv.DatabaseSpecific) error {
if !idstr.IsGoAdvisory(d.URL) {
return fmt.Errorf("%w (found URL %q)", errInvalidPkgsiteURL, d.URL)
}
return nil
}