From 04a854c3373952cc555bb4c2877d7cb0c4eb8335 Mon Sep 17 00:00:00 2001 From: Itay Shakury Date: Thu, 12 Sep 2024 10:10:23 +0300 Subject: [PATCH] docs: refine go docs (#7442) Signed-off-by: knqyf263 Co-authored-by: knqyf263 --- docs/docs/coverage/language/golang.md | 109 +++++++++++++++----------- 1 file changed, 62 insertions(+), 47 deletions(-) diff --git a/docs/docs/coverage/language/golang.md b/docs/docs/coverage/language/golang.md index f2cbff03255a..cd1a30c53e9c 100644 --- a/docs/docs/coverage/language/golang.md +++ b/docs/docs/coverage/language/golang.md @@ -1,32 +1,31 @@ # Go -## Data Sources -The data sources are listed [here](../../scanner/vulnerability.md#data-sources-1). -Trivy uses Go Vulnerability Database for standard packages, such as `net/http`, and uses GitHub Advisory Database for third-party packages. - -## Features +## Overview Trivy supports two types of Go scanning, Go Modules and binaries built by Go. The following scanners are supported. -| Artifact | SBOM | Vulnerability | License | -| -------- | :---: | :-----------: | :-----: | -| Modules | ✓ | ✓ | ✓[^2] | -| Binaries | ✓ | ✓ | - | +| Artifact | SBOM | Vulnerability | License | +|----------|:----:|:-------------:|:-------------:| +| Modules | ✓ | ✓ | [✓](#license) | +| Binaries | ✓ | ✓ | - | The table below provides an outline of the features Trivy offers. -| Artifact | Offline[^1] | Dev dependencies | [Dependency graph][dependency-graph] | Stdlib | [Detection Priority][detection-priority] | -|----------|:-----------:|:-----------------|:------------------------------------:|:------:|:----------------------------------------:| -| Modules | ✅ | Include | ✅[^2] | ✅[^6] | [✅](#stdlib) | -| Binaries | ✅ | Exclude | - | ✅[^4] | Not needed | +| Artifact | Offline[^1] | Dev dependencies | [Dependency graph][dependency-graph] | Stdlib | [Detection Priority][detection-priority] | +|----------|:-----------:|:-----------------|:------------------------------------:|:------------------------:|:----------------------------------------:| +| Modules | ✅ | Include | [✅](#dependency-graph) | [✅](#standard-library) | [✅](#standard-library) | +| Binaries | ✅ | Exclude | - | [✅](#standard-library-1) | Not needed | !!! note - Trivy scans only dependencies of the Go project. - Let's say you scan the Docker binary, Trivy doesn't detect vulnerabilities of Docker itself. - Also, when you scan go.mod in Kubernetes, the Kubernetes vulnerabilities will not be found. + When scanning Go projects (go.mod or binaries built with Go), Trivy scans only dependencies of the project, and does not detect vulnerabilities of application itself. + For example, when scanning the Docker project (Docker's source code with go.mod or the Docker binary), Trivy might find vulnerabilities in Go modules that Docker depends on, but won't find vulnerabilities of Docker itself. Moreover, when scanning the Trivy project, which happens to use Docker, Docker's vulnerabilities might be detected as dependencies of Trivy. -### Go Modules +## Data Sources +The data sources are listed [here](../../scanner/vulnerability.md#data-sources-1). +Trivy uses Go Vulnerability Database for [standard library](https://pkg.go.dev/std) and uses GitHub Advisory Database for other Go modules. + +## Go Module Depending on Go versions, the required files are different. | Version | Required files | Offline | @@ -42,7 +41,7 @@ Go 1.17+ holds actually needed indirect dependencies in `go.mod`, and it reduces If you want to have better detection, please consider updating the Go version in your project. !!! note - The Go version doesn't mean your CLI version, but the Go version in your go.mod. + The Go version doesn't mean your Go tool version, but the Go version in your go.mod. ``` module github.com/aquasecurity/trivy @@ -61,32 +60,37 @@ If you want to have better detection, please consider updating the Go version in $ go mod tidy -go=1.18 ``` -To identify licenses and dependency relationships, you need to download modules to local cache beforehand, -such as `go mod download`, `go mod tidy`, etc. -Trivy traverses `$GOPATH/pkg/mod` and collects those extra information. - -#### stdlib -If [--detection-priority comprehensive][detection-priority] is passed, Trivy determines the minimum version of `Go` and saves it as a `stdlib` dependency. - -By default, `Go` selects the higher version from of `toolchan` or local version of `Go`. -See [toolchain] for more details. +### Main Module +Trivy scans only dependencies of the project, and does not detect vulnerabilities of the main module. +For example, when scanning the Docker project (Docker's source code with go.mod), Trivy might find vulnerabilities in Go modules that Docker depends on, but won't find vulnerabilities of Docker itself. +Moreover, when scanning the Trivy project, which happens to use Docker, Docker's vulnerabilities might be detected as dependencies of Trivy. -To obtain reproducible scan results Trivy doesn't check the local version of `Go`. -Trivy shows the minimum required version for the `go.mod` file, obtained from `toolchain` line (or from the `go` line, if `toolchain` line is omitted). +### Standard Library +Detecting the version of Go used in the project can be tricky. +The go.mod file include hints that allows Trivy to guess the Go version but it eventually depends on the Go tool version in the build environment. +Since this strategy is not fully deterministic and accurate, it is enabled only in [--detection-priority comprehensive][detection-priority] mode. +When enabled, Trivy detects stdlib version as the minimum between the `go` and the `toolchain` directives in the `go.mod` file. +To obtain reproducible scan results Trivy doesn't check the locally installed version of `Go`. !!! note Trivy detects `stdlib` only for `Go` 1.21 or higher. The version from the `go` line (for `Go` 1.20 or early) is not a minimum required version. For details, see [this](https://go.googlesource.com/proposal/+/master/design/57001-gotoolchain.md). - - -### Go binaries -Trivy scans binaries built by Go, which include [module information](https://tip.golang.org/doc/go1.18#go-version). -If there is a Go binary in your container image, Trivy automatically finds and scans it. +It possibly produces false positives. +See [the caveat](#stdlib-vulnerabilities) for details. + +### License +To identify licenses, you need to download modules to local cache beforehand, such as `go mod download`, `go mod tidy`, etc. +Trivy traverses `$GOPATH/pkg/mod` and collects those extra information. + +### Dependency Graph +Same as licenses, you need to download modules to local cache beforehand. -Also, you can scan your local binaries. +## Go Binary +Trivy scans Go binaries when it encounters them during scans such as container images or file systems. +When scanning binaries built by Go, Trivy finds dependencies and Go version information as [embedded in the binary by Go tool at build time](https://tip.golang.org/doc/go1.18#go-version). ``` $ trivy rootfs ./your_binary @@ -95,22 +99,33 @@ $ trivy rootfs ./your_binary !!! note It doesn't work with UPX-compressed binaries. -#### Empty versions -There are times when Go uses the `(devel)` version for modules/dependencies. +### Main Module +Go binaries installed using the `go install` command contains correct (semver) version for the main module and therefor are detected by Trivy. +In other cases, Go uses the `(devel)` version[^2]. +In this case, Trivy will attempt to parse any `-ldflags` as it's a common practice to pass versions this way. +If unsuccessful, the version will be empty[^3]. + +### Standard Library +Trivy detects the Go version used to compile the binary and detects its vulnerabilities in the standard libraries. +It possibly produces false positives. +See [the caveat](#stdlib-vulnerabilities) for details. + +## Caveats + +### Stdlib Vulnerabilities +Trivy does not know if or how you use stdlib functions, therefore it is possible that stdlib vulnerabilities are not applicable to your use case. +There are a few ways to mitigate this: -- Only Go binaries installed using the `go install` command contain correct (semver) version for the main module. - In other cases, Go uses the `(devel)` version[^3]. -- Dependencies replaced with local ones use the `(devel)` versions. +1. Analyze vulnerability reachability using a tool such as [govulncheck](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck). This will ensure that reported vulnerabilities are applicable to your project. +2. Suppress non-applicable vulnerabilities using either [ignore file](../../configuration/filtering.md) for self-use or [VEX Hub](../../supply-chain/vex/repo.md) for public use. -In the first case, Trivy will attempt to parse any `-ldflags` as a secondary source, and will leave the version -empty if it cannot do so[^5]. For the second case, the version of such packages is empty. +### Empty Version +As described in the [Main Module](#main-module-1) section, the main module of Go binaries might have an empty version. +Also, dependencies replaced with local ones will have an empty version. [^1]: It doesn't require the Internet access. -[^2]: Need to download modules to local cache beforehand -[^3]: See https://github.com/aquasecurity/trivy/issues/1837#issuecomment-1832523477 -[^4]: Identify the Go version used to compile the binary and detect its vulnerabilities -[^5]: See https://github.com/golang/go/issues/63432#issuecomment-1751610604 -[^6]: Only available if `toolchain` directive exists +[^2]: See https://github.com/aquasecurity/trivy/issues/1837#issuecomment-1832523477 +[^3]: See https://github.com/golang/go/issues/63432#issuecomment-1751610604 [dependency-graph]: ../../configuration/reporting.md#show-origins-of-vulnerable-dependencies [toolchain]: https://go.dev/doc/toolchain