diff --git a/docs/detectors/go.md b/docs/detectors/go.md index 4a30caa98..4052632bf 100644 --- a/docs/detectors/go.md +++ b/docs/detectors/go.md @@ -4,32 +4,32 @@ Go detection runs when one of the following files is found in the project: -- `go.mod` or `go.sum` +- `go.mod` or `go.sum` ## Default Detection strategy Default Go detection depends on the following to successfully run: -- Go v1.11+. +- Go v1.11+. Full dependency graph generation is supported if Go v1.11+ is present on the build agent. If no Go v1.11+ is present, fallback detection strategy is performed. -Go detection is performed by parsing output from executing -[go list -mod=readonly -m -json all](1). To generate the graph, the command -[go mod graph](2) is executed. This only adds edges between the components +Go detection is performed by parsing output from executing +[go list -mod=readonly -m -json all](1). To generate the graph, the command +[go mod graph](2) is executed. This only adds edges between the components that were already registered by `go list`. ## Fallback Detection strategy -The fallback detections trategy is known to overreport (see the -[known limitations](#known-limitations)). Read through the +The fallback detections trategy is known to overreport (see the +[known limitations](#known-limitations)). Read through the [troubleshooting section](#troubleshooting-failures-to-run-the-default-go-detection-strategy) -for tips on how to ensure that the newer, more accurate default -detection strategy runs successfully. +for tips on how to ensure that the newer, more accurate default +detection strategy runs successfully. -To force the fallback detection strategy, set the environment +To force the fallback detection strategy, set the environment variable: `DisableGoCliScan=true` ### `go.mod` before go 1.17 @@ -37,10 +37,8 @@ variable: `DisableGoCliScan=true` Go detection is performed by parsing any `go.mod` or `go.sum` found under the scan directory. -Only root dependency information is generated in the fallback detection -strategy. The full graph is not detected. Given a dependency tree `A->B->C`, -only `A`, `C`'s root dependency, is detected. - +Only root dependency information is generated in the fallback detection +strategy. The full graph is not detected. ### `go.mod` after 1.17 @@ -51,96 +49,102 @@ dependencies, including transitive ones. [^3] Similarly, no graph is generated. ## Troubleshooting failures to run the default Go detection strategy -The fallback detection strategy is known to overreport by nature of -parsing `go.sum` files which contain historical component information. - -If you are experiencing overdetection from `go.sum` files or have -otherwise been made aware that you are using the fallback Go detection -strategy, search Component Detection output for the following to determine -what action is needed: - -| CD output | Solution | -| --------------------------------------------- | ---------------------------------------------------------------------- | -| `Go CLI was not found in the system` | [Ensure that Go v1.17+ is installed](#ensure-that-go-v117-is-installed-on-the-build-agent) | -| `#[error]Go CLI command "go list -m -json all" failed with error:` | [Resolve `go list` errors](#resolve-go-list-errors) | -| `Go cli scan was manually disabled, fallback strategy performed.` | [Remove the `DisableGoCliScan` environment variable](#remove-the-disablegocliscan-environment-variable) | -| _Timeouts in Go detection_ | [Fetch Go modules](#fetch-go-modules-before-the-component-detection-build-task-runs) | +The fallback detection strategy is known to overreport by nature of +parsing `go.sum` files which contain historical component information. -If you do not believe that Go is used in your project but Go detection is running, +If you are experiencing overdetection from `go.sum` files or have +otherwise been made aware that you are using the fallback Go detection +strategy, search Component Detection output for the following to determine +what action is needed: + +| CD output | Solution | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| `Go CLI was not found in the system` | [Ensure that Go v1.17+ is installed](#ensure-that-go-v117-is-installed-on-the-build-agent) | +| `#[error]Go CLI command "go list -m -json all" failed with error:` | [Resolve `go list` errors](#resolve-go-list-errors) | +| `Go cli scan was manually disabled, fallback strategy performed.` | [Remove the `DisableGoCliScan` environment variable](#remove-the-disablegocliscan-environment-variable) | +| _Timeouts in Go detection_ | [Fetch Go modules](#fetch-go-modules-before-the-component-detection-build-task-runs) | + +If you do not believe that Go is used in your project but Go detection is running, it is likely that you need to [clean up extraneous build files](#clean-up-extraneous-build-files). ### Ensure that Go v1.17+ is installed on the build agent -Install Go CLI tools v1.17+ and ensure that it is available at the -Component Detection step. -If Go CLI tools are installed in a prior build step but -Component Detection is not finding them, ensure that they -are not cleaned up or installed inside a container. +Install Go CLI tools v1.17+ and ensure that it is available at the +Component Detection step. + +If Go CLI tools are installed in a prior build step but +Component Detection is not finding them, ensure that they +are not cleaned up or installed inside a container. -### Resolve `go list` errors. +### Resolve `go list` errors. -Errors are logged in the Component Detection build task output and begin with -`#[error]Go CLI command "go list -m -json all" failed with error:`. These errors -are typically caused by version resolution problems or incorrectly formatted `go.mod` -files. +Errors are logged in the Component Detection build task output and begin with +`#[error]Go CLI command "go list -m -json all" failed with error:`. These errors +are typically caused by version resolution problems or incorrectly formatted `go.mod` +files. ### Remove the `DisableGoCliScan` environment variable + The variable should not be set or should be set to `false`. -### Fetch Go modules before the Component Detection build task runs. -If modules are not fetched, `go list` will pull the modules and may -negatively impact performance at detection time. +### Fetch Go modules before the Component Detection build task runs. + +If modules are not fetched, `go list` will pull the modules and may +negatively impact performance at detection time. + +If you are still experiencing timouts, the fallback strategy might be more +appropriate for your project: -If you are still experiencing timouts, the fallback strategy might be more -appropriate for your project: 1. Set `DisableGoCli=true`. 1. Run `go mod tidy` to clean your `go.mod` and `go.sum`s to reduce overreporting. 1. Install Go v1.17+ to bypass go.sum scanning. ### Clean up extraneous build files -Go detection runs when a `go.sum` or `go.mod` file is encountered. If -you do not use Go in your project, search for the following in Component -Detection build output to find the paths to the Go files CD has detected. -Component Detection must be running in debug mode to see these logs: - -`##[debug]Found Go.mod:` or + +Go detection runs when a `go.sum` or `go.mod` file is encountered. If +you do not use Go in your project, search for the following in Component +Detection build output to find the paths to the Go files CD has detected. +Component Detection must be running in debug mode to see these logs: + +`##[debug]Found Go.mod:` or `##[debug]Found Go.sum:` -When you have found the affected files, you may: +When you have found the affected files, you may: + 1. Delete the files if they exist but are not necessary in your project. -2. Add a clean-up step to your build to remove the files if they are -generated prior to the Component Detection build step but are not related -to your project. -3. [Exclude the directory](../detector-arguments.md) if it should not be scanned by Component -Detection. +2. Add a clean-up step to your build to remove the files if they are + generated prior to the Component Detection build step but are not related + to your project. +3. [Exclude the directory](../detector-arguments.md) if it should not be scanned by Component + Detection. ## Known limitations -- If the default strategy is used and go modules are not present in -the system before the detector is executed, the go cli will fetch all -modules to generate the dependency graph. This will incur additional -detector time execution. +- If the default strategy is used and go modules are not present in + the system before the detector is executed, the go cli will fetch all + modules to generate the dependency graph. This will incur additional + detector time execution. -- Dev dependency tagging is not supported. +- Dev dependency tagging is not supported. -- Go detection will fallback if no Go v1.11+ is present. +- Go detection will fallback if no Go v1.11+ is present. -- (Prior to Go 1.17) Due to the nature of `go.sum` containing -references for all dependencies, including historical, -no-longer-needed dependencies; the fallback strategy can result in -over detection. Executing [go mod -tidy](https://go.dev/ref/mod#go-mod-tidy) before detection via the -fallback strategy is encouraged. +- (Prior to Go 1.17) Due to the nature of `go.sum` containing + references for all dependencies, including historical, + no-longer-needed dependencies; the fallback strategy can result in + over detection. Executing [go mod + tidy](https://go.dev/ref/mod#go-mod-tidy) before detection via the + fallback strategy is encouraged. -- Some legacy dependencies may report stale transitive dependencies in -their manifests, in this case you can remove them safely from your -binaries by using [exclude -directive](https://go.dev/doc/modules/gomod-ref#exclude). +- Some legacy dependencies may report stale transitive dependencies in + their manifests, in this case you can remove them safely from your + binaries by using [exclude + directive](https://go.dev/doc/modules/gomod-ref#exclude). ## Environment Variables -If the environment variable `DisableGoCliScan` is set to `true`, the +If the environment variable `DisableGoCliScan` is set to `true`, the Go detector forcibly executes the [fallback strategy](#fallback-detection-strategy). ## Go Overview @@ -168,20 +172,20 @@ of Go's module system.[^4] It serves several crucial purposes: Dependencies are listed with their module paths and version constraints. - ``` - go module example.com/myproject + ``` + go module example.com/myproject - go 1.17 + go 1.17 - require ( - github.com/somepackage v1.2.3 golang.org/x/someotherpackage v0.4.0 - ) + require ( + github.com/somepackage v1.2.3 golang.org/x/someotherpackage v0.4.0 + ) - ``` + ``` - Here, `github.com/somepackage` and `golang.org/x/someotherpackage` - are declared as project dependencies with specific version - constraints. + Here, `github.com/somepackage` and `golang.org/x/someotherpackage` + are declared as project dependencies with specific version + constraints. 3. **Semantic Versioning**: Go uses Semantic Versioning (Semver) to specify version constraints for dependencies. You can specify @@ -342,7 +346,7 @@ The main change for the go detector was not in the parsing of the go.mod files, but rather simply filtering `go.sum` files if an adjacent `go.mod` file specified a version higher than 1.17. -[1]: https://go.dev/ref/mod#go-list-m +[1]: https://go.dev/ref/mod#go-list-m [2]: https://go.dev/ref/mod#go-mod-graph [3]: https://go.dev/doc/modules/gomod-ref#go-notes [4]: https://go.dev/doc/modules/gomod-ref