| // 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 |
| // https://golang.org/x/vuln/client#Client. The vulnerabilities |
| // are modeled using the shared https://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 |
