report

package
v0.0.0-...-210767f Latest Latest
Warning

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

 Go to latest Published: Oct 24, 2023 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package report contains functionality for parsing and linting YAML reports in reports/.

Index

Constants

View Source 
const (
	NISTPrefix = "https://nvd.nist.gov/vuln/detail/"
)

Variables

View Source 
var (
	// osvDir is the name of the directory in the vulndb repo that
	// contains reports.
	OSVDir = "data/osv"

	// SchemaVersion is used to indicate which version of the OSV schema a
	// particular vulnerability was exported with.
	SchemaVersion = "1.3.1"
)
View Source 
var (
	// YAMLDir is the name of the directory in the vulndb repo that
	// contains reports.
	YAMLDir = "data/reports"

	// ExcludedDir is the name of the directory in the vulndb repo that
	// contains excluded reports.
	ExcludedDir = "data/excluded"
)
View Source 
var ExcludedReasons = []ExcludedReason{
	"NOT_IMPORTABLE",
	"NOT_GO_CODE",
	"NOT_A_VULNERABILITY",
	"EFFECTIVELY_PRIVATE",
	"DEPENDENT_VULNERABILITY",
}

ExcludedReasons are the set of reasons a report may be excluded from the database. These are described in detail at https://go.googlesource.com/vulndb/+/refs/heads/master/doc/format.md.

View Source 
var (
	// The universal unique identifier for the Go Project CNA, which
	// needs to be included CVE JSON 5.0 records.
	GoOrgUUID = "1bb62c36-49e3-4200-9d77-64a1400537cc"
)

Functions

func AffectedRanges 

func AffectedRanges(versions []VersionRange) []osv.Range

func Aliases 

func Aliases(repo *git.Repository) (_ []string, err error)

Aliases returns a sorted list of all aliases (CVEs and GHSAs) in vulndb, including those in the excluded directory.

func All 

func All(repo *git.Repository) (byIssue map[int]*Report, byFile map[string]*Report, err error)

All returns all the reports in the repo, indexed by issue and by filename.

func GoAdvisory 

func GoAdvisory(id string) string

func GoID 

func GoID(filename string) string

GoID returns the Go ID from the given filename, assuming the filename is of the form "*/<goID>.<ext>".

func ModulesForEntry 

func ModulesForEntry(entry osv.Entry) []string

ModulesForEntry returns the list of modules affected by an OSV entry.

func ParseFilepath 

func ParseFilepath(path string) (folder, filename string, issueID int, err error)

func ReadOSV 

func ReadOSV(filename string) (entry osv.Entry, err error)

ReadOSV reads an osv.Entry from a file.

func UnmarshalFromFile 

func UnmarshalFromFile(path string, v any) (err error)

func XRef 

func XRef(r *Report, existingByFile map[string]*Report) (matches map[string][]string)

XRef returns cross-references for a report: in this case, a map from filenames to aliases (CVE & GHSA IDs) and modules (excluding std and cmd).

Types

type CVEMeta 

type CVEMeta struct {
	ID          string `yaml:",omitempty"`
	CWE         string `yaml:",omitempty"`
	Description string `yaml:",omitempty"`
	// Additional references that should be included in the CVE record
	// but not the OSV. This is used to preserve references that have been
	// added to a CVE by the CVE program that the Go team does not want
	// to display via OSV. An example that uses this is GO-2022-0476.
	References []string `yaml:",omitempty"`
}

type ExcludedReason 

type ExcludedReason string

ExcludedReason is the reason a report is excluded from the database.

It must be one of the values in ExcludedReasons.

type Module 

type Module struct {
	Module   string         `yaml:",omitempty"`
	Versions []VersionRange `yaml:",omitempty"`
	// Version types that exist in OSV, but we don't support.
	// These may be added when automatically creating a report,
	// but must be deleted in order to pass lint checks.
	UnsupportedVersions []UnsupportedVersion `yaml:"unsupported_versions,omitempty"`
	// Known-vulnerable version, to use when performing static analysis or
	// other techniques on a vulnerable version of the package.
	//
	// In general, we want to use the most recent vulnerable version of
	// the package. Determining this programmatically is difficult, especially
	// for packages without tagged versions, so we specify it manually here.
	VulnerableAt string `yaml:"vulnerable_at,omitempty"`
	// Additional list of module@version to require when performing static analysis.
	// It is rare that we need to specify this.
	VulnerableAtRequires []string   `yaml:"vulnerable_at_requires,omitempty"`
	Packages             []*Package `yaml:",omitempty"`
}

func (*Module) FixVersions 

func (m *Module) FixVersions(pc *proxy.Client)

FixVersions replaces each version with its canonical form (if possible), sorts version ranges, and collects version ranges into a compact form.

func (*Module) IsFirstParty 

func (m *Module) IsFirstParty() bool

type Package 

type Package struct {
	Package string   `yaml:",omitempty"`
	GOOS    []string `yaml:"goos,omitempty"`
	GOARCH  []string `yaml:"goarch,omitempty"`
	// Symbols originally identified as vulnerable.
	Symbols []string `yaml:",omitempty"`
	// Additional vulnerable symbols, computed from Symbols via static analysis
	// or other technique.
	DerivedSymbols []string `yaml:"derived_symbols,omitempty"`
	// Reason the package is already considered fixed and should not be automatically updated.
	SkipFix string `yaml:"skip_fix,omitempty"`
}

func (*Package) AllSymbols 

func (a *Package) AllSymbols() []string

AllSymbols returns both original and derived symbols.

type Reference 

type Reference osv.Reference

A Reference is a link to some external resource.

For ease of typing, References are represented in the YAML as a single-element mapping of type to URL.

func (*Reference) MarshalYAML 

func (r *Reference) MarshalYAML() (interface{}, error)

func (*Reference) UnmarshalYAML 

func (r *Reference) UnmarshalYAML(n *yaml.Node) (err error)

type Report 

type Report struct {
	ID string `yaml:",omitempty"`

	// Excluded indicates an excluded report.
	Excluded ExcludedReason `yaml:",omitempty"`

	Modules []*Module `yaml:",omitempty"`

	// Summary is a short phrase describing the vulnerability.
	Summary string `yaml:",omitempty"`

	// Description is the CVE description from an existing CVE. If we are
	// assigning a CVE ID ourselves, use CVEMetadata.Description instead.
	Description string     `yaml:",omitempty"`
	Published   time.Time  `yaml:",omitempty"`
	Withdrawn   *time.Time `yaml:",omitempty"`

	// CVE are CVE IDs for existing CVEs.
	// If we are assigning a CVE ID ourselves, use CVEMetadata.ID instead.
	CVEs []string `yaml:",omitempty"`
	// GHSAs are the IDs of GitHub Security Advisories that match
	// the above CVEs.
	GHSAs []string `yaml:",omitempty"`

	Credits    []string     `yaml:",omitempty"`
	References []*Reference `yaml:",omitempty"`

	// CVEMetadata is used to capture CVE information when we want to assign a
	// CVE ourselves. If a CVE already exists for an issue, use the CVE field
	// to fill in the ID string.
	CVEMetadata *CVEMeta `yaml:"cve_metadata,omitempty"`

	// Freeform notes about the report. This field is ignored when creating
	// OSV and CVE records. It can be used to document decisions made when
	// creating the report, outstanding issues, or anything else worth
	// mentioning.
	Notes []string `yaml:",omitempty"`
}

Report represents a vulnerability report in the vulndb. Remember to update doc/format.md when this structure changes.

func CVEToReport 

func CVEToReport(c *cveschema.CVE, modulePath string, pc *proxy.Client) *Report

CVEToReport creates a Report struct from a given CVE and modulePath.

func GHSAToReport 

func GHSAToReport(sa *ghsa.SecurityAdvisory, modulePath string, pc *proxy.Client) *Report

GHSAToReport creates a Report struct from a given GHSA SecurityAdvisory and modulePath.

func Read 

func Read(filename string) (_ *Report, err error)

Read reads a Report in YAML format from filename.

func ReadAndLint 

func ReadAndLint(filename string, pc *proxy.Client) (r *Report, err error)

ReadAndLint reads a Report in YAML format from filename, lints the Report, and errors if there are any lint warnings.

func (*Report) AddAliases 

func (r *Report) AddAliases(aliases []string) (added int)

AddAliases adds any GHSAs and CVEs in aliases that were not already present to the report.

func (*Report) Aliases 

func (r *Report) Aliases() []string

Aliases returns all aliases (e.g., CVEs, GHSAs) for a report.

func (*Report) AllCVEs 

func (r *Report) AllCVEs() []string

AllCVEs returns all CVE IDs for a report.

func (*Report) CVEFilename 

func (r *Report) CVEFilename() string

func (*Report) CheckFilename 

func (r *Report) CheckFilename(filename string) (err error)

CheckFilename errors if the filename is inconsistent with the report.

func (*Report) Fix 

func (r *Report) Fix(pc *proxy.Client)

func (*Report) GoCVE 

func (r *Report) GoCVE() string

GoCVE returns the CVE assigned to this report by the Go CNA, or the empty string if not applicable.

func (*Report) IsExcluded 

func (r *Report) IsExcluded() bool

func (*Report) Lint 

func (r *Report) Lint(pc *proxy.Client) []string

Lint checks the content of a Report and outputs a list of strings representing lint errors. TODO: It might make sense to include warnings or informational things alongside errors, especially during for use during the triage process.

func (*Report) LintOffline 

func (r *Report) LintOffline() []string

LintOffline performs all lint checks that don't require a network connection.

func (*Report) OSVFilename 

func (r *Report) OSVFilename() string

func (*Report) ToCVE5 

func (r *Report) ToCVE5() (_ *cveschema5.CVERecord, err error)

ToCVE5 creates a CVE in 5.0 format from a YAML report file.

func (*Report) ToOSV 

func (r *Report) ToOSV(lastModified time.Time) osv.Entry

ToOSV creates an osv.Entry for a report. lastModified is the time the report should be considered to have been most recently modified.

func (*Report) ToString 

func (r *Report) ToString() (string, error)

ToString encodes r to a YAML string.

func (*Report) Write 

func (r *Report) Write(filename string) (err error)

Write writes r to filename in YAML format.

func (*Report) YAMLFilename 

func (r *Report) YAMLFilename() (string, error)

type UnsupportedVersion 

type UnsupportedVersion struct {
	Version string `yaml:",omitempty"`
	Type    string `yaml:",omitempty"`
}

type VersionRange 

type VersionRange struct {
	Introduced string `yaml:"introduced,omitempty"`
	Fixed      string `yaml:"fixed,omitempty"`
}

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.