Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: refine go docs #7442

Merged
merged 5 commits into from
Sep 12, 2024
Merged

docs: refine go docs #7442

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8f8dd78
docs: refine go docs
itaysk Sep 4, 2024
ea2506b
address comments
itaysk Sep 9, 2024
e708970
note about not detecting vulns in app
itaysk Sep 11, 2024
1218538
note about stdlib FP
itaysk Sep 11, 2024
3e6540a
docs: add more sections
knqyf263 Sep 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 12 additions & 28 deletions docs/docs/coverage/language/golang.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## 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.
Trivy uses Go Vulnerability Database for [standard library](https://pkg.go.dev/std) and uses GitHub Advisory Database for other Go modules.

## Features
Trivy supports two types of Go scanning, Go Modules and binaries built by Go.
Expand All @@ -22,9 +22,8 @@ The table below provides an outline of the features Trivy offers.
| Binaries | ✅ | Exclude | - | ✅[^4] | 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.
knqyf263 marked this conversation as resolved.
Show resolved Hide resolved
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
Depending on Go versions, the required files are different.
Expand All @@ -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
Expand All @@ -65,28 +64,20 @@ To identify licenses and dependency relationships, you need to download modules
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.

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][^6] 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).


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.

Also, you can scan your local binaries.
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
Expand All @@ -96,14 +87,7 @@ $ trivy rootfs ./your_binary
It doesn't work with UPX-compressed binaries.

#### Empty versions
There are times when Go uses the `(devel)` version for modules/dependencies.

- 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.

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.
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[^3]. 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[^5].

[^1]: It doesn't require the Internet access.
[^2]: Need to download modules to local cache beforehand
Expand Down