advisory

package
v0.26.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 1, 2024 License: Apache-2.0 Imports: 37 Imported by: 0

Documentation

Index

Constants

View Source 
const OSVEcosystem models.Ecosystem = "Chainguard"

OSVEcosystem is the name of the OSV ecosystem for Chainguard advisories.

Variables

View Source 
var (
	// ErrEmptyPackage is returned when the Package field is empty.
	ErrEmptyPackage = errors.New("package cannot be empty")

	// ErrInvalidAdvisoryID is returned when the AdvisoryID field value is not a
	// valid CGA ID.
	ErrInvalidAdvisoryID = errors.New("advisory ID must be a valid CGA ID when provided")

	// ErrInvalidVulnerabilityID is returned when an alias is not a valid vulnerability ID.
	ErrInvalidVulnerabilityID = errors.New("alias must be a valid vulnerability ID")

	// ErrCGAIDAsAlias is returned when a CGA ID is used as an alias.
	ErrCGAIDAsAlias = errors.New("CGA ID cannot be used as an alias")

	// ErrZeroEvent is returned when the Event field is zero.
	ErrZeroEvent = errors.New("event cannot be zero")
)
View Source 
var (
	ErrNoPackageSecurityData = errors.New("no package security data found")
	ErrorPackageCollision    = errors.New("found multiple advisory documents for the same package")
)

Functions

func BuildOSVDataset added in v0.18.0 

func BuildOSVDataset(ctx context.Context, opts OSVOptions) error

BuildOSVDataset produces an OSV dataset from Chainguard advisory data, using the given set of options.

func BuildSecurityDatabase added in v0.5.1 

func BuildSecurityDatabase(ctx context.Context, opts BuildSecurityDatabaseOptions) ([]byte, error)

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

func Create 

func Create(ctx context.Context, 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 added in v0.5.0 

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 added in v0.1.6 

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

ExportCSV returns a reader of advisory data encoded as CSV.

func ExportYAML added in v0.1.6 

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

ExportYAML returns a reader of advisory data encoded as YAML.

func GenerateCGAID added in v0.16.14 

func GenerateCGAID() (string, error)

func GenerateCGAIDWithSeed added in v0.16.14 

func GenerateCGAIDWithSeed(seed int64) (string, error)

func ImporAdvisoriesYAML added in v0.15.4 

func ImporAdvisoriesYAML(inputData []byte) (tempDir string, documents *configs.Index[v2.Document], err error)

ImporAdvisoriesYAML import and yaml Advisories data and present as a config index struct

func Update 

func Update(ctx context.Context, req Request, opts UpdateOptions) error

Update adds a new event to an existing advisory in the document at the provided path. If the request's AdvisoryID is set, the advisory with that ID is updated. Otherwise, the first advisory found for the package with the one of the provided aliases is updated.

func Validate 

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

Types

type AliasFinder added in v0.5.0 

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

type BuildSecurityDatabaseOptions added in v0.5.1 

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 DataSession added in v0.16.0 

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

func NewDataSession added in v0.16.0 

func NewDataSession(ctx context.Context, opts DataSessionOptions) (*DataSession, error)

NewDataSession initializes a new advisory data session for the specified distro and returns a reference to the session. This call will retrieve the data and manage it in a local temp directory until the session is closed. The session should be closed by calling Close() when it is no longer needed.

func (*DataSession) Append added in v0.16.0 

func (ds *DataSession) Append(ctx context.Context, req Request) error

Append creates a new event for an advisory if the advisory already exists, or creates a new advisory with the event if the advisory does not already exist.

func (DataSession) Close added in v0.16.0 

func (ds DataSession) Close() error

Close closes the advisory data session and cleans up any temporary data that was downloaded.

func (*DataSession) Create added in v0.16.0 

func (ds *DataSession) Create(ctx context.Context, req Request) error

Create creates a new advisory within the context of the data session.

func (DataSession) Dir added in v0.16.0 

func (ds DataSession) Dir() string

Dir returns the path to the temporary directory where the session's advisory data is currently stored.

func (DataSession) Index added in v0.16.0 

func (ds DataSession) Index() *configs.Index[v2.Document]

Index returns the index of advisory documents for the session.

func (DataSession) Modified added in v0.16.0 

func (ds DataSession) Modified() bool

Modified returns true if any changes have been made to the advisory data during the session.

func (DataSession) OpenPullRequest added in v0.16.0 

func (ds DataSession) OpenPullRequest(ctx context.Context) (*PullRequest, error)

OpenPullRequest opens a pull request for the changes made during the session.

func (DataSession) Push added in v0.16.0 

func (ds DataSession) Push(ctx context.Context) error

Push pushes the changes made during the session to the remote advisories repository.

func (*DataSession) Update added in v0.16.0 

func (ds *DataSession) Update(ctx context.Context, req Request) error

Update updates an existing advisory within the context of the data session.

type DataSessionOptions added in v0.16.0 

type DataSessionOptions struct {
	Distro       distro.Distro
	GitHubClient *github.Client
}

type DiffResult added in v0.9.0 

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 added in v0.9.0 

func (r DiffResult) IsZero() bool

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

type DiscoverAliasesOptions added in v0.5.0 

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 added in v0.9.0 

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 added in v0.9.0 

func (r DocumentDiffResult) IsZero() bool

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

type DuplicateAdvisoryIDError added in v0.5.0 

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 added in v0.5.0 

func (e DuplicateAdvisoryIDError) Error() string

type EventDiffResult added in v0.9.0 

type EventDiffResult struct {
	ID string

	Added   v2.Event
	Removed v2.Event
}

type ExportOptions 

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

type HTTPAliasFinder added in v0.5.0 

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

func NewHTTPAliasFinder added in v0.5.0 

func NewHTTPAliasFinder(client *http.Client) *HTTPAliasFinder

func NewHTTPAliasFinderWithToken added in v0.15.0 

func NewHTTPAliasFinderWithToken(client *http.Client, ghToken string) *HTTPAliasFinder

func (*HTTPAliasFinder) CVEForGHSA added in v0.5.0 

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

func (*HTTPAliasFinder) GHSAsForCVE added in v0.5.0 

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

type IndexDiffResult added in v0.9.0 

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

	Modified []DocumentDiffResult
}

IndexDiffResult is the result of diffing two advisory document indexes.

func IndexDiff added in v0.9.0 

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 added in v0.9.0 

func (r IndexDiffResult) IsZero() bool

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

type OSVOptions added in v0.18.0 

type OSVOptions struct {
	// AdvisoryDocIndices is a list of indexes containing Chainguard advisory
	// documents.
	//
	// TODO(luhring): We should move toward unifying all advisory repositories into
	//  a single collection of all advisory documents. At that point, we won't need
	//  to use multiple advisory indices here.
	AdvisoryDocIndices []*configs.Index[v2.Document]

	// PackageConfigIndices is a list of indexes containing Chainguard package build
	// configurations. The address of each slice item is expected to correspond to
	// the address of the corresponding item in AdvisoryDocIndices.
	PackageConfigIndices []*configs.Index[config.Configuration]

	// AddedEcosystems is a list of ecosystems to be added to the OSV dataset. The
	// address of each slice item is expected to correspond to the address of the
	// corresponding item in AdvisoryDocIndices. The length of this slice is
	// expected to be the same as the length of AdvisoryDocIndices.
	//
	// Use an empty string at slice locations where no additional ecosystems are
	// needed.
	//
	// For example, to add the "wolfi" ecosystem to the advisories in the first
	// index, and no additional ecosystems to the advisories in the second index:
	//
	//   AddedEcosystems: []string{"wolfi", ""}
	//
	// TODO(luhring): We should move toward unifying the Chainguard and Wolfi
	//  ecosystems, so that we don't need to add the "wolfi" ecosystem here, and
	//  we'll just use "Chainguard" always. At that point, we can remove this
	//  option entirely.
	AddedEcosystems []string

	// OutputDirectory is the path to a local directory in which the generated OSV
	// dataset will be written.
	OutputDirectory string
}

OSVOptions contains the options for building an OSV dataset.

type PullRequest added in v0.16.0 

type PullRequest struct {
	URL string
}

type Request 

type Request struct {
	// Package is the name of the distro package for which the advisory is being
	// created.
	Package string

	// AdvisoryID is the ID for the advisory being updated. If this Request is for
	// creating a new advisory, this should be empty. If a value is provided, it
	// should be of the form "CGA-xxxx-xxxx-xxxx".
	AdvisoryID string

	// Aliases is a list of vulnerability IDs that are known aliases for the
	// advisory.
	Aliases []string

	// Event is the event to add to the advisory.
	Event v2.Event
}

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

func (Request) ResolveAliases added in v0.16.0 

func (req Request) ResolveAliases(ctx context.Context, af AliasFinder) (*Request, error)

ResolveAliases ensures that any CVE IDs and GHSA IDs for the request's vulnerability are discovered and stored as Aliases, based on the initial set of known aliases.

func (Request) Validate 

func (req Request) Validate() error

Validate returns an error if the Request is invalid.

func (Request) VulnerabilityIDs added in v0.23.0 

func (req Request) VulnerabilityIDs() []string

VulnerabilityIDs returns the list of vulnerability IDs for the Request. This is a combination of the Aliases and the AdvisoryID.

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
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.