feat: add HTTP request/response tracing support (#9125)

knqyf263 · DmitriyLewen · web-flow · commit aa5b32a19f4d · 2025-07-10T06:48:19.000Z
Co-authored-by: DmitriyLewen &lt;91113035+DmitriyLewen@users.noreply.github.com&gt;
diff --git a/docs/docs/advanced/telemetry-flags.md b/docs/docs/advanced/telemetry-flags.md
@@ -35,6 +35,7 @@
 --slow
 --tf-exclude-downloaded-modules
 --timeout
---trace
+--trace-http
+--trace-rego
 --vuln-severity-source
 ```
diff --git a/docs/docs/references/configuration/cli/trivy_config.md b/docs/docs/references/configuration/cli/trivy_config.md
@@ -76,7 +76,7 @@ trivy config [flags] DIR
   -t, --template string                   output template
       --tf-exclude-downloaded-modules     exclude misconfigurations for downloaded terraform modules
       --tf-vars strings                   specify paths to override the Terraform tfvars files
-      --trace                             enable more verbose trace output for custom queries
+      --trace-rego                        enable more verbose trace output for custom queries
       --username strings                  username. Comma-separated usernames allowed.
 ```
 
diff --git a/docs/docs/references/configuration/cli/trivy_filesystem.md b/docs/docs/references/configuration/cli/trivy_filesystem.md
@@ -135,7 +135,7 @@ trivy filesystem [flags] PATH
       --tf-vars strings                   specify paths to override the Terraform tfvars files
       --token string                      for authentication in client/server mode
       --token-header string               specify a header name for token in client/server mode (default "Trivy-Token")
-      --trace                             enable more verbose trace output for custom queries
+      --trace-rego                        enable more verbose trace output for custom queries
       --username strings                  username. Comma-separated usernames allowed.
       --vex strings                       [EXPERIMENTAL] VEX sources ("repo", "oci" or file path)
       --vuln-severity-source strings      order of data sources for selecting vulnerability severity level
diff --git a/docs/docs/references/configuration/cli/trivy_image.md b/docs/docs/references/configuration/cli/trivy_image.md
@@ -156,7 +156,7 @@ trivy image [flags] IMAGE_NAME
       --tf-exclude-downloaded-modules     exclude misconfigurations for downloaded terraform modules
       --token string                      for authentication in client/server mode
       --token-header string               specify a header name for token in client/server mode (default "Trivy-Token")
-      --trace                             enable more verbose trace output for custom queries
+      --trace-rego                        enable more verbose trace output for custom queries
       --username strings                  username. Comma-separated usernames allowed.
       --vex strings                       [EXPERIMENTAL] VEX sources ("repo", "oci" or file path)
       --vuln-severity-source strings      order of data sources for selecting vulnerability severity level
diff --git a/docs/docs/references/configuration/cli/trivy_kubernetes.md b/docs/docs/references/configuration/cli/trivy_kubernetes.md
@@ -144,7 +144,7 @@ trivy kubernetes [flags] [CONTEXT]
   -t, --template string                   output template
       --tf-exclude-downloaded-modules     exclude misconfigurations for downloaded terraform modules
       --tolerations strings               specify node-collector job tolerations (example: key1=value1:NoExecute,key2=value2:NoSchedule)
-      --trace                             enable more verbose trace output for custom queries
+      --trace-rego                        enable more verbose trace output for custom queries
       --username strings                  username. Comma-separated usernames allowed.
       --vex strings                       [EXPERIMENTAL] VEX sources ("repo", "oci" or file path)
       --vuln-severity-source strings      order of data sources for selecting vulnerability severity level
diff --git a/docs/docs/references/configuration/cli/trivy_repository.md b/docs/docs/references/configuration/cli/trivy_repository.md
@@ -134,7 +134,7 @@ trivy repository [flags] (REPO_PATH | REPO_URL)
       --tf-vars strings                   specify paths to override the Terraform tfvars files
       --token string                      for authentication in client/server mode
       --token-header string               specify a header name for token in client/server mode (default "Trivy-Token")
-      --trace                             enable more verbose trace output for custom queries
+      --trace-rego                        enable more verbose trace output for custom queries
       --username strings                  username. Comma-separated usernames allowed.
       --vex strings                       [EXPERIMENTAL] VEX sources ("repo", "oci" or file path)
       --vuln-severity-source strings      order of data sources for selecting vulnerability severity level
diff --git a/docs/docs/references/configuration/cli/trivy_rootfs.md b/docs/docs/references/configuration/cli/trivy_rootfs.md
@@ -136,7 +136,7 @@ trivy rootfs [flags] ROOTDIR
       --tf-vars strings                   specify paths to override the Terraform tfvars files
       --token string                      for authentication in client/server mode
       --token-header string               specify a header name for token in client/server mode (default "Trivy-Token")
-      --trace                             enable more verbose trace output for custom queries
+      --trace-rego                        enable more verbose trace output for custom queries
       --username strings                  username. Comma-separated usernames allowed.
       --vex strings                       [EXPERIMENTAL] VEX sources ("repo", "oci" or file path)
       --vuln-severity-source strings      order of data sources for selecting vulnerability severity level
diff --git a/docs/docs/references/configuration/config-file.md b/docs/docs/references/configuration/config-file.md
@@ -504,7 +504,7 @@ rego:
   # Same as '--skip-check-update'
   skip-check-update: false
 
-  # Same as '--trace'
+  # Same as '--trace-rego'
   trace: false
 
 ```
diff --git a/docs/docs/references/troubleshooting.md b/docs/docs/references/troubleshooting.md
@@ -267,6 +267,25 @@ $ brew install aquasecurity/trivy/trivy
 ```
 
 
+## Debugging
+### HTTP Request/Response Tracing
+
+For debugging network issues, connection problems, or authentication failures, you can enable HTTP request/response tracing using the `--trace-http` flag.
+
+!!! danger "Security Warning"
+    While Trivy attempts to redact known sensitive information such as authentication headers and common secrets, the `--trace-http` flag may still expose sensitive data in HTTP requests and responses.
+    
+    **Never use this flag in production environments or CI/CD pipelines.**
+    This flag is automatically disabled in CI environments for security.
+
+```bash
+# Enable HTTP tracing for debugging registry issues
+$ trivy image --trace-http registry.example.com/my-image:latest
+
+# HTTP tracing with other debugging options
+$ trivy image --trace-http --debug --insecure my-image:tag
+```
+
 ## Others
 ### Unknown error
 
diff --git a/docs/docs/scanner/misconfiguration/custom/debug.md b/docs/docs/scanner/misconfiguration/custom/debug.md
@@ -1,13 +1,13 @@
 # Debugging checks
 When working on more complex queries (or when learning Rego), it's useful to see exactly how the policy is applied.
-For this purpose you can use the `--trace` flag.
+For this purpose you can use the `--trace-rego` flag.
 This will output a large trace from Open Policy Agent like the following:
 
 !!! tip
     Only failed checks show traces. If you want to debug a passed check, you need to make it fail on purpose.
 
 ```shell
-$ trivy config --trace configs/
+$ trivy config --trace-rego configs/
 2022-05-16T13:47:58.853+0100	INFO	Detected config files: 1
 
 Dockerfile (dockerfile)
diff --git a/pkg/commands/artifact/run.go b/pkg/commands/artifact/run.go
@@ -121,8 +121,9 @@ func NewRunner(ctx context.Context, cliOptions flag.Options, opts ...RunnerOptio
 
 	// Set the default HTTP transport
 	xhttp.SetDefaultTransport(xhttp.NewTransport(xhttp.Options{
-		Insecure: cliOptions.Insecure,
-		Timeout:  cliOptions.Timeout,
+		Insecure:  cliOptions.Insecure,
+		Timeout:   cliOptions.Timeout,
+		TraceHTTP: cliOptions.TraceHTTP,
 	}))
 	// get the sub command that is being used or fallback to "trivy"
 	commandName := lo.Ternary(len(os.Args) > 1, os.Args[1], "trivy")
@@ -711,7 +712,7 @@ func initMisconfScannerOption(ctx context.Context, opts flag.Options) (misconf.S
 	}
 
 	misconfOpts := misconf.ScannerOption{
-		Trace:                    opts.Trace,
+		Trace:                    opts.RegoOptions.Trace,
 		Namespaces:               append(opts.CheckNamespaces, rego.BuiltinNamespaces()...),
 		PolicyPaths:              policyPaths,
 		DataPaths:                opts.DataPaths,
diff --git a/pkg/flag/global_flags.go b/pkg/flag/global_flags.go
@@ -70,6 +70,14 @@ var (
 		Usage:      "write the default config to trivy-default.yaml",
 		Persistent: true,
 	}
+	TraceHTTPFlag = Flag[bool]{
+		Name:          "trace-http",
+		ConfigName:    "trace.http",
+		Usage:         "[DANGEROUS] enable HTTP request/response trace logging (may expose sensitive data)",
+		Persistent:    true,
+		TelemetrySafe: true,
+		Internal:      true, // Hidden from help output, intended for maintainer debugging only
+	}
 )
 
 // GlobalFlagGroup composes global flags
@@ -82,6 +90,7 @@ type GlobalFlagGroup struct {
 	Timeout               *Flag[time.Duration]
 	CacheDir              *Flag[string]
 	GenerateDefaultConfig *Flag[bool]
+	TraceHTTP             *Flag[bool]
 }
 
 // GlobalOptions defines flags and other configuration parameters for all the subcommands
@@ -94,6 +103,7 @@ type GlobalOptions struct {
 	Timeout               time.Duration
 	CacheDir              string
 	GenerateDefaultConfig bool
+	TraceHTTP             bool
 }
 
 func NewGlobalFlagGroup() *GlobalFlagGroup {
@@ -106,6 +116,7 @@ func NewGlobalFlagGroup() *GlobalFlagGroup {
 		Timeout:               TimeoutFlag.Clone(),
 		CacheDir:              CacheDirFlag.Clone(),
 		GenerateDefaultConfig: GenerateDefaultConfigFlag.Clone(),
+		TraceHTTP:             TraceHTTPFlag.Clone(),
 	}
 }
 
@@ -123,6 +134,7 @@ func (f *GlobalFlagGroup) Flags() []Flagger {
 		f.Timeout,
 		f.CacheDir,
 		f.GenerateDefaultConfig,
+		f.TraceHTTP,
 	}
 }
 
@@ -156,6 +168,7 @@ func (f *GlobalFlagGroup) ToOptions(opts *Options) error {
 		Timeout:               f.Timeout.Value(),
 		CacheDir:              f.CacheDir.Value(),
 		GenerateDefaultConfig: f.GenerateDefaultConfig.Value(),
+		TraceHTTP:             f.TraceHTTP.Value(),
 	}
 	return nil
 }
diff --git a/pkg/flag/rego_flags.go b/pkg/flag/rego_flags.go
@@ -26,19 +26,32 @@ var (
 		},
 		TelemetrySafe: true,
 	}
-	TraceFlag = Flag[bool]{
-		Name:          "trace",
+	TraceRegoFlag = Flag[bool]{
+		Name:          "trace-rego",
 		ConfigName:    "rego.trace",
 		Usage:         "enable more verbose trace output for custom queries",
+		Persistent:    true,
 		TelemetrySafe: true,
+		Aliases: []Alias{
+			{
+				Name:       "trace",
+				Deprecated: true,
+			},
+		},
 	}
 	ConfigCheckFlag = Flag[[]string]{
 		Name:       "config-check",
 		ConfigName: "rego.check",
 		Usage:      "specify the paths to the Rego check files or to the directories containing them, applying config files",
 		Aliases: []Alias{
-			{Name: "policy", Deprecated: true},
-			{Name: "config-policy", Deprecated: true},
+			{
+				Name:       "policy",
+				Deprecated: true,
+			},
+			{
+				Name:       "config-policy",
+				Deprecated: true,
+			},
 		},
 	}
 	ConfigDataFlag = Flag[[]string]{
@@ -55,7 +68,10 @@ var (
 		Usage:      "Rego namespaces",
 		Aliases: []Alias{
 			{Name: "namespaces"},
-			{Name: "policy-namespaces", Deprecated: true},
+			{
+				Name:       "policy-namespaces",
+				Deprecated: true,
+			},
 		},
 	}
 )
@@ -83,7 +99,7 @@ func NewRegoFlagGroup() *RegoFlagGroup {
 	return &RegoFlagGroup{
 		IncludeDeprecatedChecks: IncludeDeprecatedChecksFlag.Clone(),
 		SkipCheckUpdate:         SkipCheckUpdateFlag.Clone(),
-		Trace:                   TraceFlag.Clone(),
+		Trace:                   TraceRegoFlag.Clone(),
 		CheckPaths:              ConfigCheckFlag.Clone(),
 		DataPaths:               ConfigDataFlag.Clone(),
 		CheckNamespaces:         CheckNamespaceFlag.Clone(),
diff --git a/pkg/report/writer.go b/pkg/report/writer.go
@@ -57,7 +57,7 @@ func Write(ctx context.Context, report types.Report, option flag.Options) (err e
 			Tree:                 option.DependencyTree,
 			ShowSuppressed:       option.ShowSuppressed,
 			IncludeNonFailures:   option.IncludeNonFailures,
-			Trace:                option.Trace,
+			Trace:                option.RegoOptions.Trace,
 			RenderCause:          option.RenderCause,
 			LicenseRiskThreshold: option.LicenseRiskThreshold,
 			IgnoredLicenses:      option.IgnoredLicenses,
diff --git a/pkg/x/http/recorder_test.go b/pkg/x/http/recorder_test.go
@@ -0,0 +1,73 @@
+package http_test
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+)
+
+// RequestRecorder is a test helper that records a single HTTP request sent through a RoundTripper
+type RequestRecorder struct {
+	request  *http.Request
+	response *http.Response
+	err      error
+}
+
+// RequestRecorderOption is a functional option for RequestRecorder
+type RequestRecorderOption func(*RequestRecorder)
+
+// WithResponse sets the response to return
+func WithResponse(resp *http.Response) RequestRecorderOption {
+	return func(rr *RequestRecorder) {
+		rr.response = resp
+	}
+}
+
+// WithError sets the error to return
+func WithError(err error) RequestRecorderOption {
+	return func(rr *RequestRecorder) {
+		rr.err = err
+	}
+}
+
+// NewRequestRecorder creates a new RequestRecorder with optional configuration
+func NewRequestRecorder(opts ...RequestRecorderOption) *RequestRecorder {
+	rr := &RequestRecorder{
+		response: &http.Response{
+			StatusCode: http.StatusOK,
+			Status:     "200 OK",
+			Proto:      "HTTP/1.1",
+			ProtoMajor: 1,
+			ProtoMinor: 1,
+			Header:     make(http.Header),
+			Body:       io.NopCloser(bytes.NewReader(nil)),
+		},
+	}
+
+	for _, opt := range opts {
+		opt(rr)
+	}
+
+	return rr
+}
+
+// RoundTrip implements http.RoundTripper and records the request
+func (rr *RequestRecorder) RoundTrip(req *http.Request) (*http.Response, error) {
+	// Record the request
+	rr.request = req
+
+	if rr.err != nil {
+		return nil, rr.err
+	}
+
+	if rr.response != nil {
+		rr.response.Request = req
+	}
+
+	return rr.response, nil
+}
+
+// Request returns the recorded request
+func (rr *RequestRecorder) Request() *http.Request {
+	return rr.request
+}
diff --git a/pkg/x/http/trace.go b/pkg/x/http/trace.go
diff --git a/pkg/x/http/trace_test.go b/pkg/x/http/trace_test.go
diff --git a/pkg/x/http/transport.go b/pkg/x/http/transport.go
diff --git a/pkg/x/http/useragent_test.go b/pkg/x/http/useragent_test.go
