vulncheck: clarifies documentation
Change-Id: I60af2c433262fc765af974d23550e4935563c792
Reviewed-on: https://go-review.googlesource.com/c/vuln/+/403138
Reviewed-by: Jonathan Amsterdam <jba@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Julie Qiu <julieqiu@google.com>
Run-TryBot: Zvonimir Pavlinovic <zpavlinovic@google.com>
diff --git a/vulncheck/vulncheck.go b/vulncheck/vulncheck.go
index 2d1b997..474f383 100644
--- a/vulncheck/vulncheck.go
+++ b/vulncheck/vulncheck.go
@@ -46,7 +46,7 @@
Replace *Module
}
-// Convert converts a slice of packages.Package to
+// Convert transforms a slice of packages.Package to
// a slice of corresponding vulncheck.Package.
func Convert(pkgs []*packages.Package) []*Package {
convertMod := newModuleConverter()
@@ -81,18 +81,18 @@
return vpkgs
}
-// Result contains information on which vulnerabilities are potentially
-// affecting user code and how are they affecting it via a call graph, package
-// imports graph, and module requires graph.
+// Result contains information on how known vulnerabilities are reachable
+// in the call graph, package imports graph, and module requires graph of
+// the user code.
type Result struct {
- // Calls is a call graph whose roots are program entry functions/methods and
- // sinks are vulnerable functions/methods. It is empty when
+ // Calls is a call graph whose roots are program entry functions and
+ // methods, and sinks are known vulnerable symbols. It is empty when
// Config.ImportsOnly is true or when no vulnerable symbols are reachable
// via the program call graph.
Calls *CallGraph
// Imports is a package dependency graph whose roots are entry user packages
- // and sinks are packages with some vulnerable symbols. It is empty when no
- // packages with vulnerabilities are imported in the program.
+ // and sinks are packages with some known vulnerable symbols. It is empty
+ // when no packages with vulnerabilities are imported in the program.
Imports *ImportGraph
// Requires is a module dependency graph whose roots are entry user modules
// and sinks are modules with some vulnerable packages. It is empty when no
@@ -127,24 +127,25 @@
ModPath string
// CallSink is the ID of the sink node in the Calls graph corresponding to
- // the use of Symbol. ID is not available (denoted with 0) in binary mode,
+ // the use of Symbol. ID is not available (denoted with 0) when analyzing binaries,
// or if Symbol is not reachable, or if Config.ImportsOnly is true.
CallSink int
// ImportSink is the ID of the sink node in the Imports graph corresponding
- // to the import of PkgPath. ID is not available (denoted with 0) in binary
- // mode or if PkgPath is not imported.
+ // to the import of PkgPath. ID is not available (denoted with 0) when analyzing
+ // binaries or when PkgPath is not imported.
ImportSink int
// RequireSink is the ID of the sink node in Requires graph corresponding
// to the require statement of ModPath. ID is not available (denoted with 0)
- // in binary mode.
+ // when analyzing binaries.
RequireSink int
}
// CallGraph is a slice of a full program call graph whose sinks are vulnerable
-// functions and sources are entry points of user packages. In order to support
-// succinct traversal of the slice related to a particular vulnerability,
+// functions and sources are entry points of user packages.
+//
// CallGraph is directed from vulnerable functions towards program entry
-// functions (see FuncNode).
+// functions (see FuncNode) for a more efficient traversal of the slice
+// related to a particular vulnerability.
type CallGraph struct {
// Functions contains all call graph nodes as a map: func node id -> func node.
Functions map[int]*FuncNode
@@ -186,9 +187,11 @@
// RequireGraph is a slice of a full program module requires graph whose sinks
// are modules with known vulnerabilities and sources are modules of user entry
-// packages. In order to support succinct traversal of the slice related to a
-// particular vulnerability, RequireGraph is directed from a vulnerable module
-// towards the program entry modules (see ModNode).
+// packages.
+//
+// RequireGraph is directed from a vulnerable module towards the program entry
+// modules (see ModNode) for a more efficient traversal of the slice related
+// to a particular vulnerability.
type RequireGraph struct {
// Modules contains all module nodes as a map: module node id -> module node.
Modules map[int]*ModNode
@@ -210,9 +213,11 @@
// ImportGraph is a slice of a full program package import graph whose sinks are
// packages with some known vulnerabilities and sources are user specified
-// packages. In order to support succinct traversal of the slice related to a
-// particular vulnerability, ImportGraph is directed from a vulnerable package
-// towards the program entry packages (see PkgNode).
+// packages.
+//
+// ImportGraph is directed from a vulnerable package towards the program entry
+// packages (see PkgNode) for a more efficient traversal of the slice related
+// to a particular vulnerability.
type ImportGraph struct {
// Packages contains all package nodes as a map: package node id -> package node.
Packages map[int]*PkgNode
diff --git a/vulncheck/witness.go b/vulncheck/witness.go
index 57c74ca..d642308 100644
--- a/vulncheck/witness.go
+++ b/vulncheck/witness.go
@@ -12,23 +12,24 @@
"sync"
)
-// ImportChain is sequence of import paths starting with
-// a client package and ending with a package with some
-// known vulnerabilities.
+// ImportChain is a slice of packages where each
+// subsequent package is imported by its immediate
+// predecessor. The chain starts with a client package
+// and ends in a package with some known vulnerabilities.
type ImportChain []*PkgNode
-// ImportChains lists import chains for each vulnerability in res. The
-// reported chains are ordered by how seemingly easy is to understand
-// them. Shorter import chains appear earlier in the returned slices.
+// ImportChains returns a slice of representative import chains for
+// each vulnerability in res. The returned chains are ordered
+// increasingly by their length.
//
-// ImportChains does not list all import chains for a vulnerability.
-// It performs a BFS search of res.RequireGraph starting at a vulnerable
-// package and going up until reaching an entry package in res.ImportGraph.Entries.
-// During this search, a package is visited only once to avoid analyzing
-// every possible import chain.
+// ImportChains performs a breadth-first search of res.RequireGraph starting
+// at a vulnerable package and going up until reaching an entry package
+// in res.ImportGraph.Entries. During this search, a package is visited
+// only once to avoid analyzing every possible import chain. Hence, not
+// all import chains are analyzed.
//
-// Note that the resulting map produces an import chain for each Vuln. Vulns
-// with the same PkgPath will have the same list of identified import chains.
+// Note that vulnerabilities from the same package will have the same
+// slice of identified import chains.
func ImportChains(res *Result) map[*Vuln][]ImportChain {
// Group vulns per package.
vPerPkg := make(map[int][]*Vuln)
@@ -115,31 +116,32 @@
return append([]*PkgNode{r.pkg}, r.child.ImportChain()...)
}
-// CallStack models a trace of function calls starting
-// with a client function or method and ending with a
-// call to a vulnerable symbol.
+// CallStack is a call stack starting with a client
+// function or method and ending with a call to a
+// vulnerable symbol.
type CallStack []StackEntry
-// StackEntry models an element of a call stack.
+// StackEntry is an element of a call stack.
type StackEntry struct {
- // Function provides information on the function whose frame is on the stack.
+ // Function whose frame is on the stack.
Function *FuncNode
- // Call provides information on the call site inducing this stack frame.
- // nil when the frame represents an entry point of the stack.
+ // Call is the call site inducing the stack frame.
+ // nil when the frame represents the stack entry point.
Call *CallSite
}
-// CallStacks lists call stacks for each vulnerability in res. The listed call
-// stacks are ordered by how seemingly easy is to understand them. In general,
-// shorter call stacks with less dynamic call sites appear earlier in the returned
-// call stack slices.
+// CallStacks returns representative call stacks for each
+// vulnerability in res. The returned call stacks are heuristically
+// ordered by how seemingly easy is to understand them: shorter
+// call stacks with less dynamic call sites appear earlier in the
+// returned slices.
//
-// CallStacks does not report every possible call stack for a vulnerable symbol.
-// It performs a BFS search of res.CallGraph starting at the symbol and going up
-// until reaching an entry function or method in res.CallGraph.Entries. During
-// this search, each function is visited at most once to avoid potential
-// exponential explosion, thus skipping some call stacks.
+// CallStacks performs a breadth-first search of res.CallGraph starting
+// at the vulnerable symbol and going up until reaching an entry
+// function or method in res.CallGraph.Entries. During this search,
+// each function is visited at most once to avoid potential
+// exponential explosion. Hence, not all call stacks are analyzed.
func CallStacks(res *Result) map[*Vuln][]CallStack {
var (
wg sync.WaitGroup
