doc.go (5002B)
1 // Copyright 2022 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 /* 6 Govulncheck reports known vulnerabilities that affect Go code. It uses static 7 analysis of source code or a binary's symbol table to narrow down reports to 8 only those that could affect the application. 9 10 By default, govulncheck makes requests to the Go vulnerability database at 11 https://vuln.go.dev. Requests to the vulnerability database contain only module 12 paths with vulnerabilities already known to the database, not code or other 13 properties of your program. See https://vuln.go.dev/privacy.html for more. 14 Use the -db flag to specify a different database, which must implement the 15 specification at https://go.dev/security/vuln/database. 16 17 Govulncheck looks for vulnerabilities in Go programs using a specific build 18 configuration. For analyzing source code, that configuration is the Go version 19 specified by the “go” command found on the PATH. For binaries, the build 20 configuration is the one used to build the binary. Note that different build 21 configurations may have different known vulnerabilities. 22 23 # Usage 24 25 To analyze source code, run govulncheck from the module directory, using the 26 same package path syntax that the go command uses: 27 28 $ cd my-module 29 $ govulncheck ./... 30 31 If no vulnerabilities are found, govulncheck will display a short message. If 32 there are vulnerabilities, each is displayed briefly, with a summary of a call 33 stack. The summary shows in brief how the package calls a vulnerable function. 34 For example, it might say 35 36 main.go:[line]:[column]: mypackage.main calls golang.org/x/text/language.Parse 37 38 To control which files are processed, use the -tags flag to provide a 39 comma-separated list of build tags, and the -test flag to indicate that test 40 files should be included. 41 42 To include more detailed stack traces, pass '-show traces', this will cause it to 43 print the full call stack for each entry. 44 45 To include progress messages and more details on findings, pass '-show verbose'. 46 47 To run govulncheck on a compiled binary, pass it the path to the binary file 48 with the '-mode binary' flag: 49 50 $ govulncheck -mode binary $HOME/go/bin/my-go-program 51 52 Govulncheck uses the binary's symbol information to find mentions of vulnerable 53 functions. These functions can belong to binary's transitive dependencies and 54 also the main module of the binary. The latter functions are checked for only 55 when the precise version of the binary module is known. Govulncheck output on 56 binaries omits call stacks, which require source code analysis. 57 58 Govulncheck also supports '-mode extract' on a Go binary for extraction of minimal 59 information needed to analyze the binary. This will produce a blob, typically much 60 smaller than the binary, that can also be passed to govulncheck as an argument with 61 '-mode binary'. The users should not rely on the contents or representation of the blob. 62 63 # Integrations 64 65 Govulncheck supports streaming JSON. For more details, please see [golang.org/x/vuln/internal/govulncheck]. 66 67 Govulncheck also supports Static Analysis Results Interchange Format (SARIF) output 68 format, following the specification at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sarif. 69 For more details, please see [golang.org/x/vuln/internal/sarif]. 70 71 Govulncheck supports the Vulnerability EXchange (VEX) output format, following 72 the specification at https://github.com/openvex/spec. 73 For more details, please see [golang.org/x/vuln/internal/openvex]. 74 75 # Exit codes 76 77 Govulncheck exits successfully (exit code 0) if there are no vulnerabilities, 78 and exits unsuccessfully if there are. It also exits successfully if the 79 'format -json' ('-json'), '-format sarif', or '-format openvex' is provided, 80 regardless of the number of detected vulnerabilities. 81 82 # Limitations 83 84 Govulncheck has these limitations: 85 86 - Govulncheck analyzes function pointer and interface calls conservatively, 87 which may result in false positives or inaccurate call stacks in some cases. 88 - Calls to functions made using package reflect are not visible to static 89 analysis. Vulnerable code reachable only through those calls will not be 90 reported in source scan mode. Similarly, use of the unsafe package may 91 result in false negatives. 92 - Because Go binaries do not contain detailed call information, govulncheck 93 cannot show the call graphs for detected vulnerabilities. It may also 94 report false positives for code that is in the binary but unreachable. 95 - There is no support for silencing vulnerability findings. See https://go.dev/issue/61211 for 96 updates. 97 - Govulncheck reports only standard library vulnerabilities for binaries 98 built with Go versions prior to Go 1.18. 99 - For binaries where the symbol information cannot be extracted, govulncheck 100 reports vulnerabilities for all modules on which the binary depends. 101 102 # Feedback 103 104 To share feedback, see https://go.dev/security/vuln#feedback. 105 */ 106 package main