v2

package
v0.23.5 Latest Latest
Warning

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

 Go to latest Published: Sep 5, 2024 License: Apache-2.0 Imports: 18 Imported by: 3

Documentation

Index

Constants

View Source 
const (
	DetectionTypeManual = "manual"
	DetectionTypeNVDAPI = "nvdapi"
	DetectionTypeScanV1 = "scan/v1"
)
View Source 
const (
	EventTypeDetection                  = "detection"
	EventTypeTruePositiveDetermination  = "true-positive-determination"
	EventTypeFixed                      = "fixed"
	EventTypeFalsePositiveDetermination = "false-positive-determination"
	EventTypeAnalysisNotPlanned         = "analysis-not-planned"
	EventTypeFixNotPlanned              = "fix-not-planned"
	EventTypePendingUpstreamFix         = "pending-upstream-fix"
)
View Source 
const (
	// FPTypeVulnerabilityRecordAnalysisContested indicates that the distro
	// maintainers view the vulnerability record itself to be describing a behavior
	// that is not a security concern or that misattributes security fault to the
	// software in the distro package.
	//
	// VEX compatibility note: this type should be mapped to the
	// "vulnerable_code_not_present" justification.
	FPTypeVulnerabilityRecordAnalysisContested = "vulnerability-record-analysis-contested"

	// FPTypeComponentVulnerabilityMismatch indicates that the component referred to
	// by the vulnerability record is not the component found in the distribution
	// package. (For example, perhaps a vulnerability scanner found a vulnerability
	// for a package with the same name, but for a different language ecosystem.)
	//
	// VEX compatibility note: this type should be mapped to the
	// "component_not_present" justification.
	FPTypeComponentVulnerabilityMismatch = "component-vulnerability-mismatch"

	// FPTypeVulnerableCodeVersionNotUsed indicates that the vulnerability was
	// correctly matched to the component, except that the version(s) of the
	// component referred to by the vulnerability record have never been present in
	// a release of the distribution package.
	//
	// VEX compatibility note: this type should be mapped to the
	// "vulnerable_code_not_present" justification.
	FPTypeVulnerableCodeVersionNotUsed = "vulnerable-code-version-not-used"

	// FPTypeVulnerableCodeNotIncludedInPackage indicates that the vulnerable code
	// (e.g. a particular function) may have been available for use or retrieved
	// during the package build process but ultimately was not included in the
	// distro package.
	//
	// VEX compatibility note: this type should be mapped to the
	// "vulnerable_code_not_present" justification.
	FPTypeVulnerableCodeNotIncludedInPackage = "vulnerable-code-not-included-in-package"

	// FPTypeVulnerableCodeNotInExecutionPath indicates that the vulnerable code (e.g.
	// a particular function) is present in the package, but it is impossible for
	// this code to be executed in the package.
	//
	// VEX compatibility note: this type should be mapped to the
	// "vulnerable_code_not_in_execute_path" justification.
	FPTypeVulnerableCodeNotInExecutionPath = "vulnerable-code-not-in-execution-path"

	// FPTypeVulnerableCodeCannotBeControlledByAdversary indicates that the
	// vulnerable code is present and able to be executed, but not in a way that can
	// be exploited by an adversary.
	//
	// VEX compatibility note: this type should be mapped to the
	// "vulnerable_code_cannot_be_controlled_by_adversary" justification.
	FPTypeVulnerableCodeCannotBeControlledByAdversary = "vulnerable-code-cannot-be-controlled-by-adversary"

	// FPTypeInlineMitigationsExist indicates that the vulnerable code is present
	// and able to be exploited by an adversary, but that the vulnerability is
	// mitigated by other code in the package.
	//
	// VEX compatibility note: this type should be mapped to the
	// "inline_mitigations_already_exist" justification.
	FPTypeInlineMitigationsExist = "inline-mitigations-exist"
)
View Source 
const SchemaVersion = "2.0.2"

SchemaVersion is the latest known schema version for advisory documents. Wolfictl can only operate on documents that use a schema version that is equal to or earlier than this version and that is not earlier than this version's MAJOR number.

Variables

View Source 
var (
	ErrAdvisoryIDDuplicated    = errors.New("advisory ID is not unique")
	ErrAdvisoryAliasDuplicated = errors.New("advisory alias is not unique")
)
View Source 
var (
	DetectionScannerGrype = "grype"
)
View Source 
var DetectionScanners = []string{
	DetectionScannerGrype,
}
View Source 
var (
	// DetectionTypes is a list of all valid detection types.
	DetectionTypes = []string{
		DetectionTypeManual,
		DetectionTypeNVDAPI,
		DetectionTypeScanV1,
	}
)
View Source 
var (
	// EventTypes is a list of all valid event types.
	EventTypes = []string{
		EventTypeDetection,
		EventTypeTruePositiveDetermination,
		EventTypeFixed,
		EventTypeFalsePositiveDetermination,
		EventTypeAnalysisNotPlanned,
		EventTypeFixNotPlanned,
		EventTypePendingUpstreamFix,
	}
)
View Source 
var FPTypes = []string{
	FPTypeVulnerabilityRecordAnalysisContested,
	FPTypeComponentVulnerabilityMismatch,
	FPTypeVulnerableCodeVersionNotUsed,
	FPTypeVulnerableCodeNotIncludedInPackage,
	FPTypeVulnerableCodeNotInExecutionPath,
	FPTypeVulnerableCodeCannotBeControlledByAdversary,
	FPTypeInlineMitigationsExist,
}

Functions

func NewAdvisoriesSectionUpdater 

func NewAdvisoriesSectionUpdater(
	updater configs.SectionUpdater[Advisories, Document],
) configs.EntryUpdater[Document]

func NewIndex 

func NewIndex(ctx context.Context, fsys rwfs.FS) (*configs.Index[Document], error)

func NewIndexFromPaths 

func NewIndexFromPaths(ctx context.Context, fsys rwfs.FS, paths ...string) (*configs.Index[Document], error)

func NewSchemaVersionSectionUpdater added in v0.7.1 

func NewSchemaVersionSectionUpdater(newSchemaVersion string) configs.EntryUpdater[Document]

Types

type Advisories 

type Advisories []Advisory

func (Advisories) Get 

func (advs Advisories) Get(id string) (Advisory, bool)

Get returns the advisory with the given ID. If such an advisory does not exist, the second return value will be false; otherwise it will be true.

func (Advisories) GetByAnyVulnerability added in v0.23.0 

func (advs Advisories) GetByAnyVulnerability(ids ...string) (Advisory, bool)

GetByAnyVulnerability returns the first advisory that references any of the given vulnerability IDs as its advisory ID or as one of the advisory's aliases. This allows the caller to look up a particular advisory of interest if the caller knows the underlying vulnerability by multiple IDs (e.g. both a CVE ID and a GHSA ID), and the advisory itself has recorded at least one of those IDs.

If such an advisory does not exist in the collection, the second return value will be false; otherwise it will be true.

func (Advisories) GetByVulnerability 

func (advs Advisories) GetByVulnerability(id string) (Advisory, bool)

GetByVulnerability returns the advisory that references the given vulnerability ID as its advisory ID or as one of the advisory's aliases. If such an advisory does not exist, the second return value will be false; otherwise it will be true.

func (Advisories) Len 

func (advs Advisories) Len() int

func (Advisories) Less 

func (advs Advisories) Less(i, j int) bool

func (Advisories) Swap 

func (advs Advisories) Swap(i, j int)

func (Advisories) Update 

func (advs Advisories) Update(id string, advisory Advisory) Advisories

Update returns a new Advisories slice with the advisory with the given ID replaced with the given advisory. If no advisory with the given ID exists in the slice, the original slice is returned.

func (Advisories) Validate 

func (advs Advisories) Validate() error

type Advisory 

type Advisory struct {
	ID string `yaml:"id"`

	// Aliases lists any known IDs of this vulnerability in databases.
	Aliases []string `yaml:"aliases,omitempty"`

	// Events is a list of timestamped events that occurred during the investigation
	// and resolution of the vulnerability.
	Events []Event `yaml:"events"`
}

func (Advisory) ConcludedAtVersion added in v0.14.2 

func (adv Advisory) ConcludedAtVersion(version, packageType string) bool

ConcludedAtVersion returns true if the advisory indicates that the vulnerability has been solved, or those where no change is expected to fix the CVE in the upstream code.

func (Advisory) DescribesVulnerability added in v0.5.0 

func (adv Advisory) DescribesVulnerability(vulnID string) bool

DescribesVulnerability returns true if the advisory cites the given vulnerability ID in either its ID or its aliases.

func (Advisory) IsZero added in v0.9.0 

func (adv Advisory) IsZero() bool

IsZero returns true if the advisory has no data.

func (Advisory) Latest 

func (adv Advisory) Latest() Event

Latest returns the latest event in the advisory.

func (Advisory) MergeInAliases added in v0.23.0 

func (adv Advisory) MergeInAliases(aliases ...string) Advisory

MergeInAliases adds the input aliases to the advisory's list of aliases and returns the updated Advisory. The list of aliases is sorted and duplicates are removed.

func (Advisory) Resolved 

func (adv Advisory) Resolved() bool

Resolved returns true if the advisory indicates that the vulnerability does not presently affect the distro package and/or that no further investigation is planned.

func (Advisory) ResolvedAtVersion 

func (adv Advisory) ResolvedAtVersion(version, packageType string) bool

ResolvedAtVersion returns true if the advisory indicates that the vulnerability does not affect the distro package at the given package version, or that no further investigation is planned.

func (Advisory) SortedEvents 

func (adv Advisory) SortedEvents() []Event

SortedEvents returns the events in the advisory, sorted by timestamp, from oldest to newest.

func (Advisory) Validate 

func (adv Advisory) Validate() error

Validate returns an error if the advisory is invalid.

func (Advisory) VulnerabilityIDs added in v0.23.0 

func (adv Advisory) VulnerabilityIDs() []string

VulnerabilityIDs returns the list of vulnerability IDs for the advisory. This is a combination of the advisory's ID and its aliases.

type AnalysisNotPlanned 

type AnalysisNotPlanned struct {
	// Note should explain why there is no plan to analyze the vulnerability match.
	Note string `yaml:"note"`
}

AnalysisNotPlanned is an event type that indicates that the vulnerability's match to the package that this advisory refers to is not expected to be analyzed further by the distro maintainers.

func (AnalysisNotPlanned) Validate 

func (a AnalysisNotPlanned) Validate() error

Validate returns an error if the AnalysisNotPlanned data is invalid.

type Detection 

type Detection struct {
	// Type is the type of detection used to identify the vulnerability match.
	Type string `yaml:"type"`

	// Data is the data associated with the detection type.
	Data interface{} `yaml:"data,omitempty"`
}

Detection is an event that indicates that a potential vulnerability was detected for a distro package.

func (*Detection) UnmarshalYAML 

func (d *Detection) UnmarshalYAML(v *yaml.Node) error

UnmarshalYAML implements the yaml.Unmarshaler interface.

func (Detection) Validate 

func (d Detection) Validate() error

Validate returns an error if the Detection data is invalid.

type DetectionNVDAPI 

type DetectionNVDAPI struct {
	CPESearched string `yaml:"cpeSearched"`
	CPEFound    string `yaml:"cpeFound"`
}

DetectionNVDAPI is the data associated with DetectionTypeNVDAPI.

func (DetectionNVDAPI) Validate 

func (d DetectionNVDAPI) Validate() error

Validate returns an error if the DetectionNVDAPI data is invalid.

type DetectionScanV1 added in v0.11.0 

type DetectionScanV1 struct {
	SubpackageName    string `yaml:"subpackageName"`
	ComponentID       string `yaml:"componentID"` // TODO: consider namespacing this ID using the SBOM tool+format
	ComponentName     string `yaml:"componentName"`
	ComponentVersion  string `yaml:"componentVersion"`
	ComponentType     string `yaml:"componentType"`
	ComponentLocation string `yaml:"componentLocation"`
	Scanner           string `yaml:"scanner"` // TODO: it'd be nice for the scanner value to be automatically versioned
}

DetectionScanV1 is the data associated with DetectionTypeScanV1.

func (DetectionScanV1) Validate added in v0.11.0 

func (d DetectionScanV1) Validate() error

Validate returns an error if the DetectionScanV1 data is invalid.

type Document 

type Document struct {
	SchemaVersion string     `yaml:"schema-version"`
	Package       Package    `yaml:"package"`
	Advisories    Advisories `yaml:"advisories,omitempty"`
}

func (Document) Name 

func (doc Document) Name() string

func (Document) Validate 

func (doc Document) Validate() error

func (Document) ValidateSchemaVersion 

func (doc Document) ValidateSchemaVersion() error

type Event 

type Event struct {
	// Timestamp is the time at which the event occurred.
	Timestamp Timestamp `yaml:"timestamp"`

	// Type is a string that identifies the kind of event. This field is used to
	// determine how to unmarshal the Data field.
	Type string `yaml:"type"`

	// Data is the event-specific data. The type of this field is determined by the
	// Type field.
	Data interface{} `yaml:"data,omitempty"`
}

Event is a timestamped record of new information regarding the investigation and resolution of a potential vulnerability match.

func (Event) IsZero 

func (e Event) IsZero() bool

func (*Event) UnmarshalYAML 

func (e *Event) UnmarshalYAML(v *yaml.Node) error

func (Event) Validate 

func (e Event) Validate() error

type EventTypeData 

type EventTypeData interface {
	Detection |
		TruePositiveDetermination |
		Fixed |
		FalsePositiveDetermination |
		AnalysisNotPlanned |
		FixNotPlanned |
		PendingUpstreamFix
}

type FalsePositiveDetermination 

type FalsePositiveDetermination struct {
	Type string `yaml:"type"`
	Note string `yaml:"note,omitempty"`
}

FalsePositiveDetermination is an event that indicates that a previously detected vulnerability was determined to be a false positive.

func (FalsePositiveDetermination) Validate 

func (fp FalsePositiveDetermination) Validate() error

type FixNotPlanned 

type FixNotPlanned struct {
	// Note should explain why there is no plan to fix the vulnerability.
	Note string `yaml:"note"`
}

FixNotPlanned is an event type that indicates that the package is expected not to receive a fix for the vulnerability.

func (FixNotPlanned) Validate 

func (f FixNotPlanned) Validate() error

Validate returns an error if the FixNotPlanned data is invalid.

type Fixed 

type Fixed struct {
	// FixedVersion is the version of the distribution package that contains
	// the fix to the vulnerability.
	FixedVersion string `yaml:"fixed-version"`
}

Fixed is an event that indicates that a vulnerability has been remediated in an updated version of the distribution package.

func (Fixed) Validate 

func (f Fixed) Validate() error

Validate returns an error if the Fixed data is invalid.

type Package 

type Package struct {
	Name string `yaml:"name"`
}

func (Package) Validate 

func (p Package) Validate() error

type PendingUpstreamFix added in v0.7.1 

type PendingUpstreamFix struct {
	// Note should explain why an upstream fix is anticipated or necessary.
	Note string `yaml:"note"`
}

PendingUpstreamFix is an event type that indicates that the package is expected to remain unfixed until the maintainers of the package's upstream project implement a fix themselves.

This event type is distinct from FixNotPlanned, which signals an expectation that no fix is ever coming.

PendingUpstreamFix is used in cases where a fix requires nontrivial upstream changes that should be managed by the upstream maintainers.

func (PendingUpstreamFix) Validate added in v0.7.1 

func (f PendingUpstreamFix) Validate() error

Validate returns an error if the PendingUpstreamFix data is invalid.

type Timestamp 

type Timestamp time.Time

Timestamp is a time.Time that marshals to and from RFC3339 timestamps.

func Now 

func Now() Timestamp

Now returns the current time as a Timestamp.

func (Timestamp) After added in v0.15.19 

func (t Timestamp) After(u Timestamp) bool

After returns true if t is after u.

func (Timestamp) Before 

func (t Timestamp) Before(u Timestamp) bool

Before returns true if t is before u.

func (Timestamp) Equal 

func (t Timestamp) Equal(u Timestamp) bool

Equal returns true if t and u are equal.

func (Timestamp) IsZero 

func (t Timestamp) IsZero() bool

IsZero returns true if the timestamp is the zero value.

func (Timestamp) MarshalYAML 

func (t Timestamp) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler.

func (Timestamp) String 

func (t Timestamp) String() string

String returns the timestamp as an RFC3339 string.

func (*Timestamp) UnmarshalYAML 

func (t *Timestamp) UnmarshalYAML(v *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler.

type TruePositiveDetermination 

type TruePositiveDetermination struct {
	Note string `yaml:"note,omitempty"`
}

TruePositiveDetermination is an event that indicates that a previously detected vulnerability was acknowledged to be a true positive.

Source Files

View all Source files

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.