cmd,vulncheck: minor documentation changes
Documentation changes are made for adherence to godoc conventions and
some things that were not documented now are.
Change-Id: Ia98c140eb6510d3d765380fe5b4ef5bdd1e5ea49
Reviewed-on: https://go-review.googlesource.com/c/vuln/+/408975
Reviewed-by: Zvonimir Pavlinovic <zpavlinovic@google.com>
Reviewed-by: Julie Qiu <julie@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
diff --git a/cmd/govulncheck/internal/govulncheck/source.go b/cmd/govulncheck/internal/govulncheck/source.go
index 752a831..6bac213 100644
--- a/cmd/govulncheck/internal/govulncheck/source.go
+++ b/cmd/govulncheck/internal/govulncheck/source.go
@@ -77,14 +77,21 @@
// CallInfo is information about calls to vulnerable functions.
type CallInfo struct {
- CallStacks map[*vulncheck.Vuln][]vulncheck.CallStack // all call stacks
- VulnGroups [][]*vulncheck.Vuln // vulns grouped by ID and package
- ModuleVersions map[string]string // map from module paths to versions
- TopPackages map[string]bool // top-level packages
+ // 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
}
// GetCallInfo computes call stacks and related information from a vulncheck.Result.
-// I also makes a set of top-level packages from pkgs.
+// It also makes a set of top-level packages from pkgs.
func GetCallInfo(r *vulncheck.Result, pkgs []*vulncheck.Package) *CallInfo {
pset := map[string]bool{}
for _, p := range pkgs {
diff --git a/cmd/govulncheck/main.go b/cmd/govulncheck/main.go
index 5cfbada..ace18df 100644
--- a/cmd/govulncheck/main.go
+++ b/cmd/govulncheck/main.go
@@ -51,7 +51,7 @@
govulncheck can be used with either one or more package patterns (i.e. golang.org/x/crypto/...
or ./...) or with a single path to a Go binary. In the latter case module and symbol
-information will be extracted from the binary in order to detect vulnerable symbols.
+information will be extracted from the binary to detect vulnerable symbols.
The environment variable GOVULNDB can be set to a comma-separated list of vulnerability
database URLs, with http://, https://, or file:// protocols. Entries from multiple
diff --git a/cmd/govulncheck/testdata/usage.ct b/cmd/govulncheck/testdata/usage.ct
index bfeaccb..b2db75b 100644
--- a/cmd/govulncheck/testdata/usage.ct
+++ b/cmd/govulncheck/testdata/usage.ct
@@ -19,7 +19,7 @@
govulncheck can be used with either one or more package patterns (i.e. golang.org/x/crypto/...
or ./...) or with a single path to a Go binary. In the latter case module and symbol
-information will be extracted from the binary in order to detect vulnerable symbols.
+information will be extracted from the binary to detect vulnerable symbols.
The environment variable GOVULNDB can be set to a comma-separated list of vulnerability
database URLs, with http://, https://, or file:// protocols. Entries from multiple
@@ -48,7 +48,7 @@
govulncheck can be used with either one or more package patterns (i.e. golang.org/x/crypto/...
or ./...) or with a single path to a Go binary. In the latter case module and symbol
-information will be extracted from the binary in order to detect vulnerable symbols.
+information will be extracted from the binary to detect vulnerable symbols.
The environment variable GOVULNDB can be set to a comma-separated list of vulnerability
database URLs, with http://, https://, or file:// protocols. Entries from multiple
diff --git a/vulncheck/binary.go b/vulncheck/binary.go
index 4c5013be..9fc97c5 100644
--- a/vulncheck/binary.go
+++ b/vulncheck/binary.go
@@ -18,8 +18,8 @@
"golang.org/x/vuln/vulncheck/internal/binscan"
)
-// Binary detects presence of vulnerable symbols in exe. The
-// imports, require, and call graph are all unavailable (nil).
+// Binary detects presence of vulnerable symbols in exe.
+// The Calls, Imports, and Requires fields on Result will be empty.
func Binary(ctx context.Context, exe io.ReaderAt, cfg *Config) (_ *Result, err error) {
defer derrors.Wrap(&err, "vulncheck.Binary")
diff --git a/vulncheck/source.go b/vulncheck/source.go
index 158f5ae..5a23e5c 100644
--- a/vulncheck/source.go
+++ b/vulncheck/source.go
@@ -17,13 +17,15 @@
"golang.org/x/vuln/osv"
)
-// Source detects vulnerabilities in pkgs and computes slices of
-// - imports graph related to an import of a package with some
-// known vulnerabilities
-// - requires graph related to a require of a module with a
-// package that has some known vulnerabilities
-// - call graph leading to the use of a known vulnerable function
-// or method
+// Source detects vulnerabilities in packages. The result will contain:
+//
+// 1) An ImportGraph related to an import of a package with some known
+// vulnerabilities.
+//
+// 2) A RequireGraph related to a require of a module with a package that has
+// some known vulnerabilities.
+//
+// 3) A CallGraph leading to the use of a known vulnerable function or method.
func Source(ctx context.Context, pkgs []*Package, cfg *Config) (_ *Result, err error) {
defer derrors.Wrap(&err, "vulncheck.Source")
diff --git a/vulncheck/vulncheck.go b/vulncheck/vulncheck.go
index 474f383..d785258 100644
--- a/vulncheck/vulncheck.go
+++ b/vulncheck/vulncheck.go
@@ -21,6 +21,7 @@
// If ImportsOnly is true, vulncheck analyzes import chains only.
// Otherwise, call chains are analyzed too.
ImportsOnly bool
+
// Client is used for querying data from a vulnerability database.
Client client.Client
}
@@ -90,10 +91,12 @@
// 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 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
// modules with vulnerabilities are required by the program.
@@ -113,30 +116,42 @@
// connecting it to the Result.{Calls,Imports,Requires} graphs. Vulnerabilities
// detected in Go binaries do not appear in the Result graphs.
type Vuln struct {
- // The next four fields identify a vulnerability. Note that *osv.Entry
- // describes potentially multiple symbols from multiple packages.
-
// OSV contains information on the detected vulnerability in the shared
// vulnerability format.
+ //
+ // OSV, Symbol, PkgPath, and ModPath 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
+
// PkgPath is the package path of the detected Symbol.
PkgPath string
+
// ModPath is the module path corresponding to PkgPath.
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) when analyzing binaries,
- // or if Symbol is not reachable, or if Config.ImportsOnly is true.
+ // CallSink is the ID of the FuncNode in Result.Calls corresponding to
+ // Symbol.
+ //
+ // When analyzing binaries, Symbol is not reachable, or Config.ImportsOnly
+ // is true, CallSink will be unavailable and set to 0.
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) when analyzing
- // binaries or when PkgPath is not imported.
+
+ // ImportSink is the ID of the PkgNode in Result.Imports corresponding to
+ // PkgPath.
+ //
+ // When analyzing binaries or PkgPath is not imported, ImportSink will be
+ // unavailable and set to 0.
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)
- // when analyzing binaries.
+
+ // RequireSink is the ID of the ModNode in Result.Requires corresponding to
+ // ModPath.
+ //
+ // When analyzing binaries, RequireSink will be unavailable and set to 0.
RequireSink int
}
@@ -147,20 +162,30 @@
// 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 contains all call graph nodes as a map: FuncNode.ID -> FuncNode.
Functions map[int]*FuncNode
+
// Entries are IDs of a subset of Functions representing vulncheck entry points.
Entries []int
}
// A FuncNode describes a function in the call graph.
type FuncNode struct {
- ID int
+ // ID is the id used to identify the FuncNode in CallGraph.
+ ID int
+
+ // Name is the name of the function.
Name string
+
// RecvType is the receiver object type of this function, if any.
RecvType string
- PkgPath string
- Pos *token.Position
+
+ // PkgPath is the import path of the package containing the function.
+ PkgPath string
+
+ // 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
}
@@ -176,11 +201,16 @@
type CallSite struct {
// Parent is ID of the enclosing function where the call is made.
Parent int
+
// 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
- Pos *token.Position
+
+ // 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
}
@@ -195,18 +225,26 @@
type RequireGraph struct {
// Modules contains all module nodes as a map: module node id -> module node.
Modules map[int]*ModNode
+
// Entries are IDs of a subset of Modules representing modules of vulncheck entry points.
Entries []int
}
// A ModNode describes a module in the requires graph.
type ModNode struct {
- ID int
- Path string
+ // ID is the id used to identify the ModNode in CallGraph.
+ ID int
+
+ // Path is the module path.
+ Path string
+
+ // Version is the module version.
Version string
+
// Replace is the ID of the replacement module node.
// A zero value means there is no replacement.
Replace int
+
// RequiredBy contains IDs of the modules requiring this module.
RequiredBy []int
}
@@ -221,18 +259,25 @@
type ImportGraph struct {
// Packages contains all package nodes as a map: package node id -> package node.
Packages map[int]*PkgNode
+
// Entries are IDs of a subset of Packages representing packages of vulncheck entry points.
Entries []int
}
// A PkgNode describes a package in the import graph.
type PkgNode struct {
+ // ID is the id used to identify the PkgNode in ImportGraph.
ID int
+
// Name is the package identifier as it appears in the source code.
Name string
+
+ // Path is the package path.
Path string
+
// Module holds ID of the corresponding module (node) in the Requires graph.
Module int
+
// ImportedBy contains IDs of packages directly importing this package.
ImportedBy []int
