advisory

Documentation

Index

• Variables
• func BuildSecurityDatabase(opts BuildSecurityDatabaseOptions) ([]byte, error)
• func Create(req Request, opts CreateOptions) error
• func Discover(ctx context.Context, opts DiscoverOptions) error
• func DiscoverAliases(ctx context.Context, opts DiscoverAliasesOptions) error
• func ExportCSV(opts ExportOptions) (io.Reader, error)
• func ExportYAML(opts ExportOptions) (io.Reader, error)
• func Update(req Request, opts UpdateOptions) error
• func Validate(ctx context.Context, opts ValidateOptions) error
• type AliasFinder
• type BuildSecurityDatabaseOptions
• type CreateOptions
• type DiffResult
  • func (r DiffResult) IsZero() bool
• type DiscoverAliasesOptions
• type DiscoverOptions
• type DocumentDiffResult
  • func (r DocumentDiffResult) IsZero() bool
• type DuplicateAdvisoryIDError
  • func (e DuplicateAdvisoryIDError) Error() string
• type EventDiffResult
• type ExportOptions
• type HTTPAliasFinder
  • func NewHTTPAliasFinder(client *http.Client) *HTTPAliasFinder
  • func (f *HTTPAliasFinder) CVEForGHSA(ctx context.Context, ghsaID string) (string, error)
  • func (f *HTTPAliasFinder) GHSAsForCVE(ctx context.Context, cveID string) ([]string, error)
• type IndexDiffResult
  • func IndexDiff(a, b *configs.Index[v2.Document]) IndexDiffResult
  • func (r IndexDiffResult) IsZero() bool
• type Request
  • func (req Request) Validate() error
• type UpdateOptions
• type ValidateOptions

Variables

var (
	ErrNoPackageSecurityData = errors.New("no package security data found")
	ErrorPackageCollision    = errors.New("found multiple advisory documents for the same package")
)

Functions

func BuildSecurityDatabase

func BuildSecurityDatabase(opts BuildSecurityDatabaseOptions) ([]byte, error)

BuildSecurityDatabase builds an Alpine-style security database from the given options.

func Create

func Create(req Request, opts CreateOptions) error

Create creates a new advisory in the `advisories` section of the document at the provided path.

func Discover

func Discover(ctx context.Context, opts DiscoverOptions) error

Discover searches for new vulnerabilities that match packages in a config index, and adds new advisories to configs for vulnerabilities that haven't been noted yet.

func DiscoverAliases

func DiscoverAliases(ctx context.Context, opts DiscoverAliasesOptions) error

DiscoverAliases queries external data sources for aliases for the vulnerabilities described in the selected advisories and updates the advisory documents with the discovered aliases.

func ExportCSV

func ExportCSV(opts ExportOptions) (io.Reader, error)

ExportCSV returns a reader of advisory data encoded as CSV.

func ExportYAML

func ExportYAML(opts ExportOptions) (io.Reader, error)

ExportYAML returns a reader of advisory data encoded as YAML.

func Update

func Update(req Request, opts UpdateOptions) error

Update adds a new event to an existing advisory (named by the vuln parameter) in the document at the provided path.

func Validate

func Validate(ctx context.Context, opts ValidateOptions) error

Types

type AliasFinder

type AliasFinder interface {
	CVEForGHSA(ctx context.Context, ghsaID string) (string, error)
	GHSAsForCVE(ctx context.Context, cveID string) ([]string, error)
}

type BuildSecurityDatabaseOptions

type BuildSecurityDatabaseOptions struct {
	AdvisoryDocIndices []*configs.Index[v2.Document]

	URLPrefix string
	Archs     []string
	Repo      string
}

BuildSecurityDatabaseOptions contains the options for building a database.

type CreateOptions

type CreateOptions struct {
	// AdvisoryDocs is the Index of advisory documents on which to operate.
	AdvisoryDocs *configs.Index[v2.Document]
}

CreateOptions configures the Create operation.

type DiffResult

type DiffResult struct {
	ID string

	Added   v2.Advisory
	Removed v2.Advisory

	AddedEvents   []v2.Event
	RemovedEvents []v2.Event
}

DiffResult is the result of diffing two advisories.

func (DiffResult) IsZero

func (r DiffResult) IsZero() bool

IsZero returns true if there is no difference between the compared advisories.

type DiscoverAliasesOptions

type DiscoverAliasesOptions struct {
	// AdvisoryDocs is the Index of advisory documents on which to operate.
	AdvisoryDocs *configs.Index[v2.Document]

	// AliasFinder is the alias finder to use for discovering aliases for the given
	// vulnerabilities.
	AliasFinder AliasFinder

	// SelectedPackages is the set of packages to operate on. If empty, all packages
	// will be operated on.
	SelectedPackages map[string]struct{}
}

DiscoverAliasesOptions is the set of options for the DiscoverAliases function.

type DiscoverOptions

type DiscoverOptions struct {
	// SelectedPackages is a list of packages to include in search. If empty, all
	// packages will be included in search.
	SelectedPackages []string

	// BuildCfgs is the Index of build configurations on which to operate.
	BuildCfgs *configs.Index[config.Configuration]

	// AdvisoryDocs is the Index of advisory documents on which to operate.
	AdvisoryDocs *configs.Index[v2.Document]

	// PackageRepositoryURL is the URL to the distro's package repository (e.g.
	// "https://packages.wolfi.dev/os").
	PackageRepositoryURL string

	// The Arches to select during discovery (e.g. "x86_64").
	Arches []string

	// VulnerabilityDetector is how Discover finds vulnerabilities for packages.
	VulnerabilityDetector vuln.Detector

	// VulnEvents is a channel of events that occur during vulnerability discovery.
	VulnEvents chan<- interface{}
}

type DocumentDiffResult

type DocumentDiffResult struct {
	Name string

	Added   v2.Advisories
	Removed v2.Advisories

	Modified []DiffResult
}

DocumentDiffResult is the result of diffing two advisory documents.

func (DocumentDiffResult) IsZero

func (r DocumentDiffResult) IsZero() bool

IsZero returns true if there is no difference between the compared advisory documents.

type DuplicateAdvisoryIDError

type DuplicateAdvisoryIDError struct {
	// Package is the name of the package that already has an advisory with the same
	// ID.
	Package string

	// AdvisoryID is the ID of the advisory that already exists in the document.
	AdvisoryID string
}

DuplicateAdvisoryIDError is returned when an attempt is made to add an advisory with an ID that already exists in the document.

func (DuplicateAdvisoryIDError) Error

func (e DuplicateAdvisoryIDError) Error() string

type EventDiffResult

type EventDiffResult struct {
	ID string

	Added   v2.Event
	Removed v2.Event
}

type ExportOptions

type ExportOptions struct {
	AdvisoryDocIndices []*configs.Index[v2.Document]
}

type HTTPAliasFinder

type HTTPAliasFinder struct {
	// contains filtered or unexported fields
}

func NewHTTPAliasFinder

func NewHTTPAliasFinder(client *http.Client) *HTTPAliasFinder

func (*HTTPAliasFinder) CVEForGHSA

func (f *HTTPAliasFinder) CVEForGHSA(ctx context.Context, ghsaID string) (string, error)

func (*HTTPAliasFinder) GHSAsForCVE

func (f *HTTPAliasFinder) GHSAsForCVE(ctx context.Context, cveID string) ([]string, error)

type IndexDiffResult

type IndexDiffResult struct {
	Added   []v2.Document
	Removed []v2.Document

	Modified []DocumentDiffResult
}

IndexDiffResult is the result of diffing two advisory document indexes.

func IndexDiff

func IndexDiff(a, b *configs.Index[v2.Document]) IndexDiffResult

IndexDiff takes two advisory document indexes and returns a diff of the advisory data between them.

func (IndexDiffResult) IsZero

func (r IndexDiffResult) IsZero() bool

IsZero returns true there is no difference between the compared advisory document indexes.

type Request

type Request struct {
	Package         string
	VulnerabilityID string
	Aliases         []string
	Event           v2.Event
}

Request specifies the parameters for creating a new advisory or updating an existing advisory.

func (Request) Validate

func (req Request) Validate() error

Validate returns an error if the Request is invalid.

type UpdateOptions

type UpdateOptions struct {
	// AdvisoryDocs is the Index of advisory documents on which to operate.
	AdvisoryDocs *configs.Index[v2.Document]
}

UpdateOptions configures the Update operation.

type ValidateOptions

type ValidateOptions struct {
	// AdvisoryDocs is the Index of advisories on which to operate.
	AdvisoryDocs *configs.Index[v2.Document]

	// BaseAdvisoryDocs is the Index of advisories used as a comparison basis to
	// understand what is changing in AdvisoryDocs. If nil, no comparison-based
	// validation will be performed.
	BaseAdvisoryDocs *configs.Index[v2.Document]

	// SelectedPackages is the set of packages to operate on. If empty, all packages
	// will be operated on.
	SelectedPackages map[string]struct{}

	// Now is the time to use as the current time for recency validation.
	Now time.Time

	// AliasFinder is the alias finder to use for discovering aliases for the given
	// vulnerabilities.
	AliasFinder AliasFinder

	// PackageConfigurations is the index of distro package configurations to use
	// for validating the advisories.
	PackageConfigurations *configs.Index[config.Configuration]

	// APKIndex is the index of APK packages to use for validating the advisories.
	APKIndex *apk.APKIndex
	// contains filtered or unexported fields
}