Add debug tracing behind --debug / AWS_ECR_CLIENT_DEBUG flag

Add a debug mode that prints detailed diagnostic information at every
step of the push-and-scan flow to help diagnose the
InvalidParameterException on imageDigest that occurs in CI with
buildx/inline-cache builds but cannot be reproduced locally.

When enabled (--debug or AWS_ECR_CLIENT_DEBUG=true), traces include:
- Full raw Docker push stream (all JSON messages from daemon)
- Each Aux message: raw JSON, parsed digest/tag/size
- Push stream error messages
- ImageId after push and after fallback logic
- ToImageIdentifier inputs including raw hex bytes of digest
- DescribeImageScanFindings parameters (repo, digest, tag, timeout)
- Waiter attempt numbers, errors with types
- Fallback scan describe results (status, description)

All trace lines are prefixed with [DEBUG] for easy filtering.
No output is produced when debug mode is off (the default).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Andrey9kin

debug.go

@@ -0,0 +1,31 @@
+/*
+
+Copyright 2021 Andrey Devyatkin.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+*/
+
+package main
+
+import "fmt"
+
+// debugEnabled is set to true via the --debug flag or AWS_ECR_CLIENT_DEBUG=true env var.
+var debugEnabled bool
+
+// debugf prints a debug message when debug mode is enabled.
+func debugf(format string, args ...interface{}) {
+	if debugEnabled {
+		fmt.Printf("[DEBUG] "+format+"\n", args...)
+	}
+}

docker.go

@@ -43,6 +43,7 @@ type ImageId struct {
 // for empty fields to avoid sending empty strings that violate the ECR API
 // parameter constraints (imageDigest must match '[a-zA-Z0-9-_+.]{0,20}:[a-fA-F0-9]{1,128}').
 func (id ImageId) ToImageIdentifier() (*types.ImageIdentifier, error) {
+	debugf("ToImageIdentifier: digest=%q (len=%d, bytes=%x) tag=%q", id.digest, len(id.digest), []byte(id.digest), id.tag)
 	if id.digest == "" && id.tag == "" {
 		return nil, fmt.Errorf("image identifier must have at least a digest or a tag, but both are empty")
 	}
@@ -78,6 +79,8 @@ func imagePush(client *dockerClient.Client, authConfig dockerRegistry.AuthConfig
 		return ImageId{}, err
 	}
 
+	debugf("Full Docker push stream for %s (%d bytes):\n%s", imageRef, buf.Len(), buf.String())
+
 	return getImageIdFromDockerDaemonJsonMessages(*buf)
 }
 
@@ -97,16 +100,20 @@ func getImageIdFromDockerDaemonJsonMessages(message bytes.Buffer) (ImageId, erro
 			return result, err
 		}
 		if err := jsonMessage.Error; err != nil {
+			debugf("Push stream error message: %v", err)
 			return result, err
 		}
 		if jsonMessage.Aux != nil {
+			debugf("Push stream Aux raw JSON: %s", string(*jsonMessage.Aux))
 			var r dockerTypes.PushResult
 			if err := json.Unmarshal(*jsonMessage.Aux, &r); err != nil {
 				return result, err
 			}
+			debugf("Push stream Aux parsed: digest=%q tag=%q size=%d", r.Digest, r.Tag, r.Size)
 			result.tag = r.Tag
 			result.digest = r.Digest
 		}
 	}
+	debugf("Final ImageId from push stream: digest=%q (len=%d) tag=%q", result.digest, len(result.digest), result.tag)
 	return result, nil
 }

ecr.go

@@ -173,6 +173,15 @@ func GetImageScanResults(client *ecr.Client, imageId ImageId, ecrRepoName string
 	if err != nil {
 		return nil, fmt.Errorf("cannot query scan results: %w", err)
 	}
+	digestStr := "<nil>"
+	if imageIdentifier.ImageDigest != nil {
+		digestStr = *imageIdentifier.ImageDigest
+	}
+	tagStr := "<nil>"
+	if imageIdentifier.ImageTag != nil {
+		tagStr = *imageIdentifier.ImageTag
+	}
+	debugf("GetImageScanResults: repo=%q imageDigest=%q imageTag=%q timeout=%s", ecrRepoName, digestStr, tagStr, timeout)
 	input := ecr.DescribeImageScanFindingsInput{
 		ImageId:        imageIdentifier,
 		RepositoryName: &ecrRepoName,
@@ -192,10 +201,13 @@ func GetImageScanResults(client *ecr.Client, imageId ImageId, ecrRepoName string
 
 	var waiterErr error
 	for attempt := 0; attempt <= maxScanInitRetries; attempt++ {
+		debugf("WaitForOutput attempt %d/%d", attempt+1, maxScanInitRetries+1)
 		output, waiterErr = w.WaitForOutput(context.TODO(), &input, timeout)
 		if waiterErr == nil {
+			debugf("WaitForOutput succeeded")
 			break
 		}
+		debugf("WaitForOutput error: %v (type: %T)", waiterErr, waiterErr)
 		// Check if the waiter failed because the scan doesn't exist yet
 		var scanNotFound *types.ScanNotFoundException
 		if errors.As(waiterErr, &scanNotFound) {
@@ -213,14 +225,18 @@ func GetImageScanResults(client *ecr.Client, imageId ImageId, ecrRepoName string
 	}
 
 	if waiterErr != nil {
+		debugf("Waiter failed, attempting fallback DescribeImageScanFindings")
 		// Handle unsupported images with Clair-based scanning: DescribeImageScanFindings
 		// returns ScanStatusFailed with "UnsupportedImageError" in the description instead
 		// of ScanStatusUnsupportedImage. That causes WaitForOutput to return the error.
 		// So here we have to check the status description for "UnsupportedImageError" separately.
 		failedOutput, describeErr := client.DescribeImageScanFindings(context.TODO(), &input)
 		if describeErr != nil {
+			debugf("Fallback DescribeImageScanFindings also failed: %v", describeErr)
 			return nil, fmt.Errorf("waiting for scan failed: %w, and describing findings also failed: %w", waiterErr, describeErr)
 		}
+		debugf("Fallback DescribeImageScanFindings status=%q description=%v",
+			failedOutput.ImageScanStatus.Status, failedOutput.ImageScanStatus.Description)
 		if failedOutput.ImageScanStatus.Status == types.ScanStatusFailed &&
 			failedOutput.ImageScanStatus.Description != nil &&
 			strings.Contains(*failedOutput.ImageScanStatus.Description, "UnsupportedImageError") {

main.go

@@ -106,6 +106,14 @@ func main() {
 				EnvVars:     []string{"AWS_ECR_CLIENT_SKIP_PUSH"},
 				Destination: &skipPush,
 			},
+			&cli.BoolFlag{
+				Name:        "debug",
+				Value:       false,
+				DefaultText: "false",
+				Usage:       "Enable debug output (prints raw Docker push stream, image identifiers, scan parameters, etc.).",
+				EnvVars:     []string{"AWS_ECR_CLIENT_DEBUG"},
+				Destination: &debugEnabled,
+			},
 		},
 	}
 
@@ -156,6 +164,8 @@ func main() {
 			return err
 		}
 
+		debugf("ImageId after push: digest=%q tag=%q", imageId.digest, imageId.tag)
+
 		// Ensure we have at least the tag we pushed with, in case the Docker
 		// daemon push stream did not include it in the Aux message.
 		if imageId.tag == "" {
@@ -165,6 +175,7 @@ func main() {
 		if imageId.digest == "" {
 			fmt.Printf("Warning: Docker push did not return a digest, will identify image by tag only\n")
 		}
+		debugf("ImageId used for scan query: digest=%q tag=%q", imageId.digest, imageId.tag)
 
 		fmt.Printf("Checking scan result for the image %s\n", stageImageRef.String())
 		client, err := GetECRClient()