vulncheck: adds doc.go with a brief overview of vulncheck
A more detailed overview is expected to be landed at
go.dev/security/vulncheck
Change-Id: Ie35e4a14306425789c7f9d3747ea6767ac965150
Reviewed-on: https://go-review.googlesource.com/c/vuln/+/403137
Reviewed-by: Julie Qiu <julie@golang.org>
Run-TryBot: Zvonimir Pavlinovic <zpavlinovic@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
diff --git a/vulncheck/doc.go b/vulncheck/doc.go
new file mode 100644
index 0000000..2de96ac
--- /dev/null
+++ b/vulncheck/doc.go
@@ -0,0 +1,58 @@
+// 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
diff --git a/vulncheck/vulncheck.go b/vulncheck/vulncheck.go
index d073536..2d1b997 100644
--- a/vulncheck/vulncheck.go
+++ b/vulncheck/vulncheck.go
@@ -2,8 +2,6 @@
// 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 binaries and source code.
package vulncheck
import (
