Documentation ¶
Overview ¶
Package report contains functionality for parsing and linting YAML reports in reports/.
Index ¶
- Constants
- Variables
- func AffectedRanges(versions []VersionRange) []osv.Range
- func GoAdvisory(id string) string
- func GoID(filename string) string
- func IsGoID(s string) bool
- func ModulesForEntry(entry osv.Entry) []string
- func NewLinter(prefix string) *linter
- func ParseFilepath(path string) (folder, filename string, issueID int, err error)
- func ReadOSV(filename string) (entry osv.Entry, err error)
- func UnmarshalFromFile(path string, v any) (err error)
- type CVEMeta
- type Client
- func (c *Client) AliasHasReport(alias string) bool
- func (c *Client) HasReport(githubID int) (found bool)
- func (c *Client) List() []*Report
- func (c *Client) Report(filename string) (r *Report, ok bool)
- func (c *Client) ReportsByAlias(alias string) []*Report
- func (c *Client) XRef(r *Report) (matches map[string][]string)
- type Description
- type ExcludedReason
- type Module
- type Note
- type NoteType
- type Package
- type Reference
- type Report
- func CVE5ToReport(c *cveschema5.CVERecord, id, modulePath string, pc *proxy.Client) *Report
- func CVEToReport(c *cveschema.CVE, id, modulePath string, pc *proxy.Client) *Report
- func GHSAToReport(sa *ghsa.SecurityAdvisory, modulePath string, pc *proxy.Client) *Report
- func Read(filename string) (_ *Report, err error)
- func ReadAndLint(filename string, pc *proxy.Client) (r *Report, err error)
- func (r *Report) AddAliases(aliases []string) (added int)
- func (r *Report) AddNote(t NoteType, format string, v ...any)
- func (r *Report) Aliases() []string
- func (r *Report) AllCVEs() []string
- func (r *Report) CVEFilename() string
- func (r *Report) CheckFilename(filename string) (err error)
- func (r *Report) CommitLinks() (links []string)
- func (r *Report) Fix(pc *proxy.Client)
- func (r *Report) FixReferences()
- func (r *Report) FixText()
- func (r *Report) GoCVE() string
- func (r *Report) IsExcluded() bool
- func (r *Report) IsFirstParty() bool
- func (r *Report) Lint(pc *proxy.Client) []string
- func (r *Report) LintAsNotes(pc *proxy.Client) bool
- func (r *Report) LintOffline() []string
- func (r *Report) OSVFilename() string
- func (r *Report) ToCVE5() (_ *cveschema5.CVERecord, err error)
- func (r *Report) ToOSV(lastModified time.Time) osv.Entry
- func (r *Report) ToString() (string, error)
- func (r *Report) Write(filename string) (err error)
- func (r *Report) YAMLFilename() (string, error)
- type Source
- type Summary
- type UnsupportedVersion
- type VersionRange
Constants ¶
const (
NISTPrefix = "https://nvd.nist.gov/vuln/detail/"
)
const SourceGoTeam = "go-security-team"
Variables ¶
var ( // YAMLDir is the name of the directory in the vulndb repo that // contains reports. YAMLDir = filepath.Join(dataFolder, reportsFolder) // ExcludedDir is the name of the directory in the vulndb repo that // contains excluded reports. ExcludedDir = filepath.Join(dataFolder, excludedFolder) )
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" )
var ExcludedReasons = []ExcludedReason{
"NOT_IMPORTABLE",
"NOT_GO_CODE",
"NOT_A_VULNERABILITY",
"EFFECTIVELY_PRIVATE",
"DEPENDENT_VULNERABILITY",
"LEGACY_FALSE_POSITIVE",
}
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.
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 GoAdvisory ¶
func GoID ¶
GoID returns the Go ID from the given filename, assuming the filename is of the form "*/<goID>.<ext>".
func ModulesForEntry ¶
ModulesForEntry returns the list of modules affected by an OSV entry.
func NewLinter ¶
func NewLinter(prefix string) *linter
NewLinter creates a new linter. If prefix is set, all lints will have the given prefix when Errors is called.
func ParseFilepath ¶
func UnmarshalFromFile ¶
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 Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a client for accessing vulndb reports from a git repository.
func NewClient ¶
NewClient returns a Client for accessing the reports in the given repo, which must contain directories "data/reports" and "data/excluded".
func NewDefaultClient ¶
NewDefaultClient returns a Client that reads reports from https://github.com/golang/vulndb.
func NewTestClient ¶
NewTestClient returns a Client based on a map from filenames to reports.
Intended for testing.
func (*Client) AliasHasReport ¶
AliasHasReport returns whether the given alias exists in vulndb.
func (*Client) HasReport ¶
HasReport returns whether the Github issue id has a corresponding report in vulndb.
func (*Client) Report ¶
Report returns the report with the given filename in vulndb, or (nil, false) if not found.
func (*Client) ReportsByAlias ¶
ReportsByAlias returns a list of reports in vulndb with the given alias.
type Description ¶
type Description string
func (*Description) String ¶
func (d *Description) String() string
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.
func FromLabel ¶
func FromLabel(label string) (ExcludedReason, bool)
func (ExcludedReason) ToLabel ¶
func (er ExcludedReason) ToLabel() string
type Module ¶
type Module struct { Module string `yaml:",omitempty"` Versions []VersionRange `yaml:",omitempty"` // Versions that are not known to the module proxy, but // that may be useful to display to humans. NonGoVersions []VersionRange `yaml:"non_go_versions,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"` // Used to determine vulnerable symbols for a given module. If not populated, // the fix links found in the report's References field will be used. // Only auto-added if the -update flag is passed to vulnreport. FixLinks []string `yaml:"fix_links,omitempty"` }
func (*Module) AllPackages ¶
AllPkgs returns all affected packages in a given module.
func (*Module) FixVersions ¶
FixVersions replaces each version with its canonical form (if possible), sorts version ranges, and collects version ranges into a compact form.
func (*Module) IsFirstParty ¶
type Note ¶
A Note is a note about the report. May be typed or untyped (with Type left blank).
func (*Note) MarshalYAML ¶
func (*Note) UnmarshalYAML ¶
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"` // Symbols that may be considered vulnerable by automated tools, // but have been determined (by a human) to actually not be vulnerable. // For now, this field is respected only by the tool that finds derived // symbols, but is not published to OSV or elsewhere (so, for example, // govulncheck cannot consume it). ExcludedSymbols []string `yaml:"excluded_symbols,omitempty"` // Reason the package is already considered fixed and should not be automatically updated. SkipFix string `yaml:"skip_fix,omitempty"` }
func (*Package) AllSymbols ¶
AllSymbols returns both original and derived symbols.
type 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 (*Reference) UnmarshalYAML ¶
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 Summary `yaml:",omitempty"` // Description is the CVE description from an existing CVE. If we are // assigning a CVE ID ourselves, use CVEMetadata.Description instead. Description Description `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"` // Aliases from other databases that we don't (yet) know about. // Not published to OSV. UnknownAliases []string `yaml:"unknown_aliases,omitempty"` // Related is a list of identifiers (e.g. CVEs or GHSAs) // that are related to, but are not direct aliases of, this report. Related []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"` // 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 []*Note `yaml:",omitempty"` // Metadata about how this report was generated. // Not published to OSV. Source *Source `yaml:",omitempty"` }
Report represents a vulnerability report in the vulndb. Remember to update doc/format.md when this structure changes.
func CVE5ToReport ¶
func CVEToReport ¶
CVEToReport creates a Report struct from a given CVE and modulePath.
func GHSAToReport ¶
GHSAToReport creates a Report struct from a given GHSA SecurityAdvisory and modulePath.
func ReadAndLint ¶
ReadAndLint reads a Report in YAML format from filename, lints the Report, and errors if there are any lint warnings.
func (*Report) AddAliases ¶
AddAliases adds any GHSAs and CVEs in aliases that were not already present to the report.
func (*Report) CVEFilename ¶
func (*Report) CheckFilename ¶
CheckFilename errors if the filename is inconsistent with the report.
func (*Report) CommitLinks ¶
CommitLinks returns all commit fix links in report.References
func (*Report) FixReferences ¶
func (r *Report) FixReferences()
func (*Report) GoCVE ¶
GoCVE returns the CVE assigned to this report by the Go CNA, or the empty string if not applicable.
func (*Report) IsExcluded ¶
func (*Report) IsFirstParty ¶
func (*Report) Lint ¶
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) LintAsNotes ¶
LintAsNotes works like Lint, but modifies r by adding any lints found to the notes section, instead of returning them. Removes any pre-existing lint notes. Returns true if any lints were found.
func (*Report) LintOffline ¶
LintOffline performs all lint checks that don't require a network connection.
func (*Report) OSVFilename ¶
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 ¶
ToOSV creates an osv.Entry for a report. lastModified is the time the report should be considered to have been most recently modified.