[vuln] cmd/govulncheck: package documentation
Jonathan Amsterdam (Gerrit)
Attention is currently required from: Julie Qiu, Zvonimir Pavlinovic.
Jonathan Amsterdam would like Zvonimir Pavlinovic and Julie Qiu to review this change.
cmd/govulncheck: package documentation
Change-Id: I46a9acec2b4c8147b5b1eb588072231f072fbe4a
---
A cmd/govulncheck/doc.go
M cmd/govulncheck/main.go
2 files changed, 79 insertions(+), 10 deletions(-)
diff --git a/cmd/govulncheck/doc.go b/cmd/govulncheck/doc.go
new file mode 100644
index 0000000..5c8e200
--- /dev/null
+++ b/cmd/govulncheck/doc.go
@@ -0,0 +1,70 @@
+// 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.
+
+//go:build go1.18
+// +build go1.18
+
+/*
+Command govulncheck reports known vulnerabilities that affect Go code. It uses
+static analysis or a binary's symbol table to narrow down reports to only those
+that potentially affect the application.
+
+By default, govulncheck uses the Go vulnerability database at
+https://vuln.go.dev. Set the GOVULNDB environment variable to specify a different database.
+The database must follow the specification at https://golang.org/design/draft-vulndb.
+
+Govulncheck requires Go version 1.18 or higher to run.
+
+WARNING: govulncheck is still EXPERIMENTAL and neither its output or the vulnerability
+database should be relied on to be stable or comprehensive.
+
+# Usage
+
+To analyze source code, run govulncheck from the module directory, using the
+same package path syntax that the go command uses:
+
+ $ cd my-module
+ $ govulncheck ./...
+
+If no vulnerabilities are found, govulncheck produces no output and exits with code 0.
+If there are vulnerabilities, each is displayed briefly, with a summary of a call stack,
+and govulncheck exits with code 3.
+
+To control which files are processed, use the -tags flag to provide a
+comma-separate list of build tags, and the -tests flag to indicate that test
+files should be included.
+
+To run govulncheck on a compiled binary, pass it the path to the binary file:
+
+ $ govulncheck $HOME/go/bin/my-go-program
+
+Govulncheck uses the binary's symbol information to find mentions of vulnerable functions.
+Its output and exit codes are as described above, except that without source it cannot
+produce call stacks.
+
+# Other Modes
+
+A few flags control govulncheck's output. Regardless of output, govulncheck
+exits with code 0 if there are no vulnerabilities and 3 if there are.
+
+The -v flag outputs more information about call stacks when run on source. It has
+no effect when run on a binary.
+
+The -html flag outputs HTML instead of plain text.
+
+The -json flag outputs a JSON object with vulnerability information. The output
+corresponds to the type golang.org/x/vuln/vulncheck.Result.
+
+# Weaknesses
+
+Govulncheck uses static analysis, which is inherently imprecise. If govulncheck
+identifies a sequence of calls in your program that leads to a vulnerable
+function, that path may never be executed because of conditions in the code, or
+it may call the vulnerable function with harmless input.
+
+The call graph analysis that govulncheck performs cannot find calls that use
+Go's reflect or unsafe packages. It is possible for govulncheck to miss
+vulnerabilities in programs that call functions in these unusual ways.
+*/
+package main
diff --git a/cmd/govulncheck/main.go b/cmd/govulncheck/main.go
index 02b7e79..ccbe1a7 100644
--- a/cmd/govulncheck/main.go
+++ b/cmd/govulncheck/main.go
@@ -5,16 +5,6 @@
//go:build go1.18
// +build go1.18
-// Command govulncheck reports known vulnerabilities filed in a vulnerability database
-// (see https://golang.org/design/draft-vulndb) that affect a given package or binary.
-//
-// It uses static analysis or the binary's symbol table to narrow down reports to only
-// those that potentially affect the application.
-//
-// # WARNING WARNING WARNING
-//
-// govulncheck is still experimental and neither its output or the vulnerability
-// database should be relied on to be stable or comprehensive.
package main
import (
To view, visit change 406578. To unsubscribe, or for help writing mail filters, visit settings.
Zvonimir Pavlinovic (Gerrit)
Attention is currently required from: Jonathan Amsterdam, Julie Qiu.
1 comment:
File cmd/govulncheck/doc.go:
Patch Set #1, Line 31:
call stackIt might be worth explaining briefly what the call stack shows.
To view, visit change 406578. To unsubscribe, or for help writing mail filters, visit settings.
Jonathan Amsterdam (Gerrit)
Attention is currently required from: Jonathan Amsterdam, Julie Qiu, Zvonimir Pavlinovic.
Jonathan Amsterdam uploaded patch set #2 to this change.
The following approvals got outdated and were removed: Run-TryBot+1 by Jonathan Amsterdam, TryBot-Result+1 by Gopher Robot
cmd/govulncheck: package documentation
Change-Id: I46a9acec2b4c8147b5b1eb588072231f072fbe4a
---
A cmd/govulncheck/doc.go
M cmd/govulncheck/main.go
2 files changed, 86 insertions(+), 10 deletions(-)
To view, visit change 406578. To unsubscribe, or for help writing mail filters, visit settings.
Jonathan Amsterdam (Gerrit)
Attention is currently required from: Jonathan Amsterdam, Julie Qiu, Zvonimir Pavlinovic.
1 comment:
File cmd/govulncheck/doc.go:
Patch Set #1, Line 31:
call stackIt might be worth explaining briefly what the call stack shows.
Done
To view, visit change 406578. To unsubscribe, or for help writing mail filters, visit settings.
Zvonimir Pavlinovic (Gerrit)
Attention is currently required from: Jonathan Amsterdam, Julie Qiu.
Patch set 2:Code-Review +2
Julie Qiu (Gerrit)
Attention is currently required from: Jonathan Amsterdam.
Patch set 2:Code-Review +2
2 comments:
File cmd/govulncheck/doc.go:
Patch Set #2, Line 11:
that potentially affect the application.Maybe add "For more information about the API behind govulncheck, see https://go.dev/security/vulncheck"
Patch Set #2, Line 15:
https://golang.org/design/draft-vulndbchange this to https://go.dev/security/vulndb (which is where this spec will eventually live)
To view, visit change 406578. To unsubscribe, or for help writing mail filters, visit settings.
Jonathan Amsterdam (Gerrit)
Attention is currently required from: Jonathan Amsterdam, Julie Qiu.
2 comments:
File cmd/govulncheck/doc.go:
Patch Set #2, Line 11:
that potentially affect the application.
Maybe add "For more information about the API behind govulncheck, see https://go. […]
Done
change this to https://go. […]
Done
To view, visit change 406578. To unsubscribe, or for help writing mail filters, visit settings.
Jonathan Amsterdam (Gerrit)
Attention is currently required from: Jonathan Amsterdam, Julie Qiu.
Jonathan Amsterdam uploaded patch set #3 to this change.
The following approvals got outdated and were removed: Run-TryBot+1 by Jonathan Amsterdam, TryBot-Result+1 by Gopher Robot
cmd/govulncheck: package documentation
Change-Id: I46a9acec2b4c8147b5b1eb588072231f072fbe4a
---
A cmd/govulncheck/doc.go
M cmd/govulncheck/main.go
2 files changed, 88 insertions(+), 10 deletions(-)
To view, visit change 406578. To unsubscribe, or for help writing mail filters, visit settings.
Jonathan Amsterdam (Gerrit)
Jonathan Amsterdam submitted this change.
2 is the latest approved patch-set.
The change was submitted with unreviewed changes in the following files:
```
The name of the file: cmd/govulncheck/doc.go
Insertions: 4, Deletions: 2.
@@ -8,11 +8,13 @@
/*
Command govulncheck reports known vulnerabilities that affect Go code. It uses
static analysis or a binary's symbol table to narrow down reports to only those
-that potentially affect the application.
+that potentially affect the application. For more information about the API
+behind govulncheck, see https://go.dev/security/vulncheck.
+
By default, govulncheck uses the Go vulnerability database at
https://vuln.go.dev. Set the GOVULNDB environment variable to specify a different database.
-The database must follow the specification at https://golang.org/design/draft-vulndb.
+The database must follow the specification at https://go.dev/security/vulndb.
Govulncheck requires Go version 1.18 or higher to run.
```
cmd/govulncheck: package documentation
Change-Id: I46a9acec2b4c8147b5b1eb588072231f072fbe4a
Reviewed-on: https://go-review.googlesource.com/c/vuln/+/406578
Reviewed-by: Zvonimir Pavlinovic <zpavl...@google.com>
Run-TryBot: Jonathan Amsterdam <j...@google.com>
Reviewed-by: Julie Qiu <ju...@golang.org>
---
A cmd/govulncheck/doc.go
M cmd/govulncheck/main.go
2 files changed, 92 insertions(+), 10 deletions(-)
diff --git a/cmd/govulncheck/doc.go b/cmd/govulncheck/doc.go
new file mode 100644
index 0000000..387c80d
--- /dev/null
+++ b/cmd/govulncheck/doc.go
@@ -0,0 +1,79 @@
+// 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.
+
+//go:build go1.18
+// +build go1.18
+
+/*
+Command govulncheck reports known vulnerabilities that affect Go code. It uses
+static analysis or a binary's symbol table to narrow down reports to only those
+that potentially affect the application. For more information about the API
+behind govulncheck, see https://go.dev/security/vulncheck.
+
+
+By default, govulncheck uses the Go vulnerability database at
+https://vuln.go.dev. Set the GOVULNDB environment variable to specify a different database.
+The database must follow the specification at https://go.dev/security/vulndb.
+
+Govulncheck requires Go version 1.18 or higher to run.
+
+WARNING: govulncheck is still EXPERIMENTAL and neither its output or the vulnerability
+database should be relied on to be stable or comprehensive.
+
+# Usage
+
+To analyze source code, run govulncheck from the module directory, using the
+same package path syntax that the go command uses:
+
+ $ cd my-module
+ $ govulncheck ./...
+
+If no vulnerabilities are found, govulncheck produces no output and exits with code 0.
+If there are vulnerabilities, each is displayed briefly, with a summary of a call stack,
+and govulncheck exits with code 3.
+
+The call stack summary shows in brief how the package calls a vulnerable function.
+For example, it might say
+
+ mypackage.main calls golang.org/x/text/language.Parse
+
+For more detailed call path that resemble Go panic stack traces, use the -v flag.
index 545c104..5cfbada 100644
--- a/cmd/govulncheck/main.go
+++ b/cmd/govulncheck/main.go
@@ -5,16 +5,6 @@
//go:build go1.18
// +build go1.18
-// Command govulncheck reports known vulnerabilities filed in a vulnerability database
-// (see https://golang.org/design/draft-vulndb) that affect a given package or binary.
-//
-// It uses static analysis or the binary's symbol table to narrow down reports to only
-// those that potentially affect the application.
-//
-// # WARNING WARNING WARNING
-//
-// govulncheck is still experimental and neither its output or the vulnerability
-// database should be relied on to be stable or comprehensive.
package main
import (
To view, visit change 406578. To unsubscribe, or for help writing mail filters, visit settings.