From bf12c616091efdecd53406b825194fd517636fcb Mon Sep 17 00:00:00 2001 From: annaowens Date: Tue, 22 Aug 2023 15:51:03 -0700 Subject: [PATCH 1/3] docs(go): improve docs on troubleshooting default go detection strategy --- docs/detectors/go.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/detectors/go.md b/docs/detectors/go.md index ad288c88a..eb881f082 100644 --- a/docs/detectors/go.md +++ b/docs/detectors/go.md @@ -2,29 +2,38 @@ ## Requirements -Go detection depends on the following to successfully run: +Go detection runs when one of the following files is found in the project: -- `go.mod` or `go.sum` files +- `go.mod` or `go.sum` ## Default Detection strategy -Go detection depends on the following to successfully run: +Default Go detection depends on the following to successfully run: - 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 -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`. +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 Go detection is performed by parsing any `go.mod` or `go.sum` found under the scan directory. -Only root dependency information is generated instead of full graph. -I.e. tags the top level component or explicit dependency a given transitive dependency was brought by. -Given a dependency tree A -> B -> C, C's root dependency is A. +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. -**To force fallback detection strategy, create set environment variable `DisableGoCliScan=true`.** +To force fallback detection strategy, set the following environment variable: `DisableGoCliScan=true` + +## Troubleshooting failures to run the default detection strategy +The fallback detection strategy is known to overreport by nature of parsing `go.sum` files. To ensure the newer, more accurate default detection strategy runs successfully, it is encouraged to do the following: + +1. Ensure that Go v1.11+ is installed on the build agent. + +1. Resolve `go list` errors. Errors are logged in the 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. + +1. Ensure that `DisableGoCliScan` is **not** set to `true`. The variable should not be set or should be set to `false`. + +1. 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. ## 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. @@ -40,7 +49,7 @@ Executing [go mod tidy](https://go.dev/ref/mod#go-mod-tidy) before detection via ## Environment Variables -If the environment variable `DisableGoCliScan` is set to `true`, the Go detector parses `go.mod` and `go.sum` to discover dependencies. otherwise, it executes default strategy. +If the environment variable `DisableGoCliScan` is set to `true`, the Go detector forcibly executes the [fallback strategy](#fallback-detection-strategy). [1]: https://go.dev/ref/mod#go-list-m [2]: https://go.dev/ref/mod#go-mod-graph From 7ee3ccef6d14ca9e0c2433764b642fd6b71802dd Mon Sep 17 00:00:00 2001 From: annaowens Date: Tue, 22 Aug 2023 15:51:03 -0700 Subject: [PATCH 2/3] docs(go): improve docs on troubleshooting default go detection strategy --- docs/detectors/go.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/detectors/go.md b/docs/detectors/go.md index ad288c88a..eb881f082 100644 --- a/docs/detectors/go.md +++ b/docs/detectors/go.md @@ -2,29 +2,38 @@ ## Requirements -Go detection depends on the following to successfully run: +Go detection runs when one of the following files is found in the project: -- `go.mod` or `go.sum` files +- `go.mod` or `go.sum` ## Default Detection strategy -Go detection depends on the following to successfully run: +Default Go detection depends on the following to successfully run: - 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 -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`. +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 Go detection is performed by parsing any `go.mod` or `go.sum` found under the scan directory. -Only root dependency information is generated instead of full graph. -I.e. tags the top level component or explicit dependency a given transitive dependency was brought by. -Given a dependency tree A -> B -> C, C's root dependency is A. +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. -**To force fallback detection strategy, create set environment variable `DisableGoCliScan=true`.** +To force fallback detection strategy, set the following environment variable: `DisableGoCliScan=true` + +## Troubleshooting failures to run the default detection strategy +The fallback detection strategy is known to overreport by nature of parsing `go.sum` files. To ensure the newer, more accurate default detection strategy runs successfully, it is encouraged to do the following: + +1. Ensure that Go v1.11+ is installed on the build agent. + +1. Resolve `go list` errors. Errors are logged in the 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. + +1. Ensure that `DisableGoCliScan` is **not** set to `true`. The variable should not be set or should be set to `false`. + +1. 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. ## 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. @@ -40,7 +49,7 @@ Executing [go mod tidy](https://go.dev/ref/mod#go-mod-tidy) before detection via ## Environment Variables -If the environment variable `DisableGoCliScan` is set to `true`, the Go detector parses `go.mod` and `go.sum` to discover dependencies. otherwise, it executes default strategy. +If the environment variable `DisableGoCliScan` is set to `true`, the Go detector forcibly executes the [fallback strategy](#fallback-detection-strategy). [1]: https://go.dev/ref/mod#go-list-m [2]: https://go.dev/ref/mod#go-mod-graph From 94d22378288da64d57564af0c45f607c8a428dbe Mon Sep 17 00:00:00 2001 From: annaowens Date: Wed, 23 Aug 2023 08:13:51 -0700 Subject: [PATCH 3/3] docs(go): typo fixes --- docs/detectors/go.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detectors/go.md b/docs/detectors/go.md index eb881f082..6fe972989 100644 --- a/docs/detectors/go.md +++ b/docs/detectors/go.md @@ -29,7 +29,7 @@ The fallback detection strategy is known to overreport by nature of parsing `go. 1. Ensure that Go v1.11+ is installed on the build agent. -1. Resolve `go list` errors. Errors are logged in the 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. +1. 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. 1. Ensure that `DisableGoCliScan` is **not** set to `true`. The variable should not be set or should be set to `false`.