advisory

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

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

	URLPrefix string
	Archs     []string
	Repo      string
}

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

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

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

type DiffResult struct {
	ID string

	Added   v2.Advisory
	Removed v2.Advisory

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

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{}
}

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 struct {
	Name string

	Added   v2.Advisories
	Removed v2.Advisories

	Modified []DiffResult
}

type DocumentEncoder func(w io.Writer, doc v2.Document) error

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
}

type EventDiffResult struct {
	ID string

	Added   v2.Event
	Removed v2.Event
}

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

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

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

type Getter interface {
	// PackageNames returns the list of package names that have advisories. The
	// order of the results is not guaranteed.
	PackageNames(ctx context.Context) ([]string, error)

	// Advisories returns the advisories for the given package name. If no error is
	// returned, it is guaranteed that all elements of the result slice contain
	// valid, non-empty data.
	Advisories(ctx context.Context, packageName string) ([]v2.PackageAdvisory, error)
}

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

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

	Modified []DocumentDiffResult
}

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
}

type PullRequest struct {
	URL string
}

type Putter interface {
	// Upsert stores the advisory data from the given Request. Upsert creates a new
	// advisory or updates an existing advisory, depending on whether an advisory
	// already exists that matches the given Request.
	//
	// An existing advisory is considered to match the given Request if the named
	// package in the Request matches the package name in the advisory, and the
	// advisory ID or any of the aliases in the Request match the advisory ID or
	// aliases in the advisory, respectively. If the Request specified both an
	// advisory ID, the advisory referenced by the advisory ID must match the
	// package name in the Request, or an error should be returned.
	//
	// If the advisory ID in the Request is specified, only updating an existing
	// advisory (not creating a new advisory) is permitted.
	//
	// When updating an advisory, the updated set of aliases for the advisory is the
	// union of the existing aliases and the aliases in the Request.
	//
	// If the event specified in the Request is not zero (as determined by the
	// evaluation of the event's IsZero method), it is added to the advisory.
	//
	// If the advisory is unable to be created or updated because of the above rules
	// or because of an error encountered by the underlying implementation, an empty
	// string and the error are returned.
	//
	// Otherwise, the advisory ID for the newly created or updated advisory is
	// returned.
	Upsert(ctx context.Context, request Request) (string, error)
}

type RebaseOptions struct {
	SourceIndex      *configs.Index[v2.Document]
	DestinationIndex *configs.Index[v2.Document]

	// PackageName is the name of the package to rebase.
	PackageName string

	// Optionally filter to a single advisory by vulnerability ID (alias) or
	// advisory ID, and only the matching advisory in the specificed source advisory
	// document will be copied over.
	VulnerabilityID string

	// Used for any new events added to the destination.
	CurrentTime v2.Timestamp
}

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
}

type RequestParams struct {
	PackageNames, Vulns []string

	Timestamp, EventType, FixedVersion, FalsePositiveType, FalsePositiveNote, TruePositiveNote, Note string
}

type Store interface {
	Getter
	Putter
}

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

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
}