govulncheck

README

internal/govulncheck package

This package is a literal copy of the cmd/govulncheck/internal/govulncheck package in the vuln repo (https://go.googlesource.com/vuln).

The copy.sh does the copying, after removing all .go files here. To use it:

1. Clone the vuln repo to a directory next to the directory holding this repo (tools). After doing that your directory structure should look something like

   ~/repos/x/tools/gopls/...
   ~/repos/x/vuln/...
   

2. cd to this directory.

3. Run copy.sh.

4. Re-add build tags for go1.18

Documentation

Overview

Package govulncheck supports the govulncheck command.

Index

• func AbsRelShorter(path string) string
• func FuncName(fn *vulncheck.FuncNode) string
• func FuncPos(call *vulncheck.CallSite) string
• func LatestFixed(as []osv.Affected) string
• func LoadPackages(cfg *packages.Config, patterns ...string) ([]*vulncheck.Package, error)
• func PkgPath(fn *vulncheck.FuncNode) string
• func SummarizeCallStack(cs vulncheck.CallStack, topPkgs map[string]bool, vulnPkg string) string
• type CallInfo
  • func GetCallInfo(r *vulncheck.Result, pkgs []*vulncheck.Package) *CallInfo
• type FSCache
  • func DefaultCache() *FSCache
  • func (c *FSCache) ReadEntries(dbName string, p string) ([]*osv.Entry, error)
  • func (c *FSCache) ReadIndex(dbName string) (client.DBIndex, time.Time, error)
  • func (c *FSCache) WriteEntries(dbName string, p string, entries []*osv.Entry) error
  • func (c *FSCache) WriteIndex(dbName string, index client.DBIndex, retrieved time.Time) error
• type PackageError
  • func (e *PackageError) Error() string
• type StackEntry
• type Summary
• type Trace
• type Vuln

Functions

func AbsRelShorter

func AbsRelShorter(path string) string

AbsRelShorter takes path and returns its path relative to the current directory, if shorter. Returns path when path is an empty string or upon any error.

func FuncName

func FuncName(fn *vulncheck.FuncNode) string

FuncName returns the function name from fn, adjusted to remove pointer annotations.

func FuncPos

func FuncPos(call *vulncheck.CallSite) string

FuncPos returns the function position from call.

func LatestFixed

func LatestFixed(as []osv.Affected) string

LatestFixed returns the latest fixed version in the list of affected ranges, or the empty string if there are no fixed versions.

func LoadPackages

func LoadPackages(cfg *packages.Config, patterns ...string) ([]*vulncheck.Package, error)

LoadPackages loads the packages matching patterns using cfg, after setting the cfg mode flags that vulncheck needs for analysis. If the packages contain errors, a PackageError is returned containing a list of the errors, along with the packages themselves.

func PkgPath

func PkgPath(fn *vulncheck.FuncNode) string

PkgPath returns the package path from fn.

func SummarizeCallStack

func SummarizeCallStack(cs vulncheck.CallStack, topPkgs map[string]bool, vulnPkg string) string

SummarizeCallStack returns a short description of the call stack. It uses one of two forms, depending on what the lowest function F in topPkgs calls:

• If it calls a function V from the vulnerable package, then summarizeCallStack returns "F calls V".
• If it calls a function G in some other package, which eventually calls V, it returns "F calls G, which eventually calls V".

If it can't find any of these functions, summarizeCallStack returns the empty string.

Types

type CallInfo

type CallInfo struct {
	// CallStacks contains all call stacks to vulnerable functions.
	CallStacks map[*vulncheck.Vuln][]vulncheck.CallStack

	// VulnGroups contains vulnerabilities grouped by ID and package.
	VulnGroups [][]*vulncheck.Vuln

	// ModuleVersions is a map of module paths to versions.
	ModuleVersions map[string]string

	// TopPackages contains the top-level packages in the call info.
	TopPackages map[string]bool
}

CallInfo is information about calls to vulnerable functions.

func GetCallInfo

func GetCallInfo(r *vulncheck.Result, pkgs []*vulncheck.Package) *CallInfo

GetCallInfo computes call stacks and related information from a vulncheck.Result. It also makes a set of top-level packages from pkgs.

type FSCache

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

FSCache is a thread-safe file-system cache implementing osv.Cache

TODO: use something like cmd/go/internal/lockedfile for thread safety?

func DefaultCache

func DefaultCache() *FSCache

func (*FSCache) ReadEntries

func (c *FSCache) ReadEntries(dbName string, p string) ([]*osv.Entry, error)

func (*FSCache) ReadIndex

func (c *FSCache) ReadIndex(dbName string) (client.DBIndex, time.Time, error)

func (*FSCache) WriteEntries

func (c *FSCache) WriteEntries(dbName string, p string, entries []*osv.Entry) error

func (*FSCache) WriteIndex

func (c *FSCache) WriteIndex(dbName string, index client.DBIndex, retrieved time.Time) error

type PackageError

type PackageError struct {
	Errors []packages.Error
}

A PackageError contains errors from loading a set of packages.

func (*PackageError) Error

func (e *PackageError) Error() string

type StackEntry

type StackEntry struct {
	FuncName string // Function name is the function name, adjusted to remove pointer annotation.
	CallSite string // Position of the call/reference site. It is one of the formats token.Pos.String() returns or empty if unknown.
}

StackEntry represents a call stack entry.

type Summary

type Summary struct {
	// Vulnerabilities affecting the analysis target binary or source code.
	Affecting []Vuln
	// Vulnerabilities that may be imported but the vulnerable symbols are
	// not called. For binary analysis, this will be always empty.
	NonAffecting []Vuln
}

Summary is the govulncheck result.

type Trace

type Trace struct {
	Symbol string       // Name of the detected vulnerable function or method.
	Desc   string       // One-line description of the callstack.
	Stack  []StackEntry // Call stack.
	Seen   int          // Number of similar call stacks.
}

Trace represents a sample trace for a vulnerable symbol.

type Vuln

type Vuln struct {
	OSV     *osv.Entry
	PkgPath string // Package path.
	ModPath string // Module path.
	FoundIn string // <package path>@<version> if we know when it was introduced. Empty otherwise.
	FixedIn string // <package path>@<version> if fix is available. Empty otherwise.
	// Trace contains a call stack for each affecting symbol.
	// For vulnerabilities found from binary analysis, and vulnerabilities
	// that are reported as Unaffecting ones, this will be always empty.
	Trace []Trace
}

Vuln represents a vulnerability relevant to a (module, package).