vulncheck/doc.go

// Copyright 2022 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

/*
* Package vulncheck detects uses of known vulnerabilities
* in Go programs. The two main APIs of vulncheck, Source
* and Binary, allow vulnerability detection in Go source
* code and binaries, respectively.
*
* 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.
*
* TODO(zpavlinovic): add a link to a more detailed overview of vulncheck
*
* # Inputs
*
* Source accepts a list of vulncheck.Package objects, which
* are a trimmed version of 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. Otherwise,
* the list of modules used by the binary is unavailable and
* vulncheck hence might miss vulnerabilities present in the binary.
*
* Both Source and Binary require information about known
* vulnerabilities in the form of a vulnerability database
* golang.org/x/vuln/client.Client. The vulnerabilities
* are modeled using the shared golang.org/x/vuln/osv format.
*
* # Results
*
* The result of vulncheck are slices of the call graph, package
* imports graph, and module requires graph leading to the use
* of an identified vulnerability. Parts of these graphs not
* related to any vulnerabilities are omitted.
*
* # Vulnerability Witnesses
*
* CallStacks and ImportChains APIs search the returned slices
* for user-friendly representative call stacks and import chains.
* Clients of vulncheck can use these stacks and chains as a
* witness of a vulnerability use during, for instance, security
* review.
*
* # Limitations
*
* Note that since statically constructing an exact call graph of
* a program is impossible, the produced call graph information
* is over-approximate: the results might contain call stacks not
* realizable in practice. On the other hand, vulncheck might
* miss some call graph edges in the presence of unsafe and reflect.
 */
package vulncheck