vulncheck

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Apr 15, 2024 License: BSD-3-Clause Imports: 29 Imported by: 0

Documentation

Overview

Package vulncheck detects uses of known vulnerabilities in Go programs.

Vulncheck identifies vulnerability uses in Go programs at the level of call graph, package import graph, and module requires graph. For instance, vulncheck identifies which vulnerable functions and methods are transitively called from the program entry points. vulncheck also detects transitively imported packages and required modules that contain known vulnerable functions and methods.

We recommend using the command line tool govulncheck to detect vulnerabilities in your code.

Usage

The two main APIs of vulncheck, Source and Binary, allow vulnerability detection in Go source code and binaries, respectively.

Source accepts a list of [Package] objects, which are a trimmed version of golang.org/x/tools/go/packages.Package objects to reduce memory consumption. Binary accepts a path to a Go binary file that must have been compiled with Go 1.18 or greater.

Both Source and Binary require information about known vulnerabilities in the form of a vulnerability database, specifically a golang.org/x/vuln/internal/client.Client. The vulnerabilities are modeled using the golang.org/x/vuln/internal/osv format.

Results

The results of vulncheck are slices of the call graph, package imports graph, and module requires graph leading to the use of an identified vulnerability. The parts of these graphs not related to any vulnerabilities are omitted.

The [CallStacks] and [ImportChains] functions search the returned slices for user-friendly representative call stacks and import chains. These call stacks and import chains are provided as examples of vulnerability uses in the client code.

Limitations

There are some limitations with vulncheck. Please see the documented limitations for more information.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Binary

func Binary(ctx context.Context, handler govulncheck.Handler, bin *Bin, cfg *govulncheck.Config, client *client.Client) error

Binary detects presence of vulnerable symbols in bin and emits findings to handler.

func FixedVersion added in v1.0.2

func FixedVersion(modulePath, version string, affected []osv.Affected) string

func IsStdPackage added in v1.0.2

func IsStdPackage(pkg string) bool

func Source

func Source(ctx context.Context, handler govulncheck.Handler, cfg *govulncheck.Config, client *client.Client, graph *PackageGraph) error

Source detects vulnerabilities in pkgs and emits the findings to handler.

Types

type Bin added in v1.0.2

type Bin struct {
	Modules    []*packages.Module `json:"modules,omitempty"`
	PkgSymbols []buildinfo.Symbol `json:"pkgSymbols,omitempty"`
	GoVersion  string             `json:"goVersion,omitempty"`
	GOOS       string             `json:"goos,omitempty"`
	GOARCH     string             `json:"goarch,omitempty"`
}

Bin is an abstraction of Go binary containing minimal information needed by govulncheck.

type CallSite

type CallSite struct {
	// Parent is the enclosing function where the call is made.
	Parent *FuncNode

	// Name stands for the name of the function (variable) being called.
	Name string

	// RecvType is the full path of the receiver object type, if any.
	RecvType string

	// Position describes the position of the function in the file.
	Pos *token.Position

	// Resolved indicates if the called function can be statically resolved.
	Resolved bool
}

A CallSite describes a function call.

type CallStack

type CallStack []StackEntry

CallStack is a call stack starting with a client function or method and ending with a call to a vulnerable symbol.

type FuncNode

type FuncNode struct {
	// Name is the name of the function.
	Name string

	// RecvType is the receiver object type of this function, if any.
	RecvType string

	// Package is the package the function is part of.
	Package *packages.Package

	// Position describes the position of the function in the file.
	Pos *token.Position

	// CallSites is a set of call sites where this function is called.
	CallSites []*CallSite
}

A FuncNode describes a function in the call graph.

func (*FuncNode) Receiver

func (fn *FuncNode) Receiver() string

Receiver returns the FuncNode's receiver, with package path removed. Pointers are preserved if present.

func (*FuncNode) String

func (fn *FuncNode) String() string

type ModVulns

type ModVulns struct {
	Module *packages.Module
	Vulns  []*osv.Entry
}

ModVulns groups vulnerabilities per module.

func FetchVulnerabilities

func FetchVulnerabilities(ctx context.Context, c *client.Client, modules []*packages.Module) ([]*ModVulns, error)

FetchVulnerabilities fetches vulnerabilities that affect the supplied modules.

type PackageGraph added in v0.2.0

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

PackageGraph holds a complete module and package graph. Its primary purpose is to allow fast access to the nodes by path and make sure all(stdlib) packages have a module.

func NewPackageGraph added in v0.2.0

func NewPackageGraph(goVersion string) *PackageGraph

func (*PackageGraph) AddModules added in v0.2.0

func (g *PackageGraph) AddModules(mods ...*packages.Module)

AddModules adds the modules and any replace modules provided. It will ignore modules that have duplicate paths to ones the graph already holds.

func (*PackageGraph) AddPackages added in v0.2.0

func (g *PackageGraph) AddPackages(pkgs ...*packages.Package)

AddPackages adds the packages and their full graph of imported packages. It also adds the modules of the added packages. It will ignore packages that have duplicate paths to ones the graph already holds.

func (*PackageGraph) DepPkgs added in v1.1.0

func (g *PackageGraph) DepPkgs() []*packages.Package

DepPkgs returns the number of packages that graph.TopPkgs() strictly depend on. This does not include topPkgs even if they are dependency of each other.

func (*PackageGraph) GetModule added in v0.2.0

func (g *PackageGraph) GetModule(path string) *packages.Module

GetModule gets module at path if one exists. Otherwise, it creates a module and returns it.

func (*PackageGraph) GetPackage added in v0.2.0

func (g *PackageGraph) GetPackage(path string) *packages.Package

GetPackage returns the package matching the path. If the graph does not already know about the package, a new one is added.

func (*PackageGraph) LoadPackagesAndMods added in v1.0.3

func (g *PackageGraph) LoadPackagesAndMods(cfg *packages.Config, tags []string, patterns []string) error

LoadPackages loads the packages specified by the patterns into the graph. See golang.org/x/tools/go/packages.Load for details of how it works.

func (*PackageGraph) Modules added in v1.1.0

func (g *PackageGraph) Modules() []*packages.Module

func (*PackageGraph) TopPkgs added in v1.1.0

func (g *PackageGraph) TopPkgs() []*packages.Package

type Result

type Result struct {
	// EntryFunctions are a subset of Functions representing vulncheck entry points.
	EntryFunctions []*FuncNode

	// Vulns contains information on detected vulnerabilities.
	Vulns []*Vuln
}

Result contains information on detected vulnerabilities. For call graph analysis, it provides information on reachability of vulnerable symbols through entry points of the program.

type StackEntry

type StackEntry struct {
	// Function whose frame is on the stack.
	Function *FuncNode

	// Call is the call site inducing the next stack frame.
	// nil when the frame represents the last frame in the stack.
	Call *CallSite
}

StackEntry is an element of a call stack.

type Vuln

type Vuln struct {
	// OSV contains information on the detected vulnerability in the shared
	// vulnerability format.
	//
	// OSV, Symbol, and Package identify a vulnerability.
	//
	// Note that *osv.Entry may describe multiple symbols from multiple
	// packages.
	OSV *osv.Entry

	// Symbol is the name of the detected vulnerable function or method.
	Symbol string

	// CallSink is the FuncNode corresponding to Symbol.
	//
	// When analyzing binaries, Symbol is not reachable, or cfg.ScanLevel
	// is symbol, CallSink will be unavailable and set to nil.
	CallSink *FuncNode

	// Package of Symbol.
	//
	// When the package of symbol is not imported, Package will be
	// unavailable and set to nil.
	Package *packages.Package
}

Vuln provides information on a detected vulnerability. For call graph mode, Vuln will also contain the information on how the vulnerability is reachable in the user call graph.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL