Improve container-images validation error messages

- Add helpful error message for .tar files with paths suggesting file: prefix
- Add specific filenames to file existence error messages
- Detect when users input file paths without proper prefix format
- Prevent customer confusion about format requirements

Examples:
- 'empty/alpine.tar' → suggests 'file:empty/alpine.tar'
- 'file:missing.tar' → shows 'file missing.tar does not exist' (not just 'file does not exist')

This addresses customer usability issues and makes error messages more actionable.

Author: Checkmarx Automation

internal/commands/scan.go

@@ -3363,7 +3363,7 @@ func validatePrefixedContainerImage(containerImage, prefix string) error {
 			return errors.Errorf("--container-images flag error: %v", err)
 		}
 		if !exists {
-			return errors.Errorf("--container-images flag error: file does not exist")
+			return errors.Errorf("--container-images flag error: file '%s' does not exist", imageRef)
 		}
 		return nil
 	}
@@ -3401,7 +3401,7 @@ func validatePrefixedContainerImage(containerImage, prefix string) error {
 			return errors.Errorf("--container-images flag error: %v", err)
 		}
 		if !exists {
-			return errors.Errorf("--container-images flag error: file does not exist")
+			return errors.Errorf("--container-images flag error: file '%s' does not exist", imageRef)
 		}
 		return nil
 	}
@@ -3445,12 +3445,17 @@ func validatePrefixedContainerImage(containerImage, prefix string) error {
 func validateTraditionalContainerImage(containerImage string) error {
 	// Handle legacy .tar file format
 	if strings.HasSuffix(containerImage, ".tar") {
+		// Check if this looks like a file path that should use a prefix
+		if strings.Contains(containerImage, "/") || strings.Contains(containerImage, "\\") {
+			return errors.Errorf("Invalid value for --container-images flag. The value '%s' appears to be a file path. For file-based scanning, use the 'file:' prefix: 'file:%s'", containerImage, containerImage)
+		}
+		
 		exists, err := osinstaller.FileExists(containerImage)
 		if err != nil {
 			return errors.Errorf("--container-images flag error: %v", err)
 		}
 		if !exists {
-			return errors.Errorf("--container-images flag error: file does not exist")
+			return errors.Errorf("--container-images flag error: file '%s' does not exist", containerImage)
 		}
 		return nil
 	}

internal/commands/scan_test.go

@@ -2199,6 +2199,16 @@ func TestValidateContainerImageFormat(t *testing.T) {
 			expectedError:  nil,
 			setupFiles:     []string{"nginx.tar"},
 		},
+		{
+			name:           "Invalid tar file with path - suggests file prefix",
+			containerImage: "empty/alpine.tar",
+			expectedError:  errors.New("Invalid value for --container-images flag. The value 'empty/alpine.tar' appears to be a file path. For file-based scanning, use the 'file:' prefix: 'file:empty/alpine.tar'"),
+		},
+		{
+			name:           "Invalid tar file with absolute path - suggests file prefix",
+			containerImage: "/path/to/image.tar",
+			expectedError:  errors.New("Invalid value for --container-images flag. The value '/path/to/image.tar' appears to be a file path. For file-based scanning, use the 'file:' prefix: 'file:/path/to/image.tar'"),
+		},
 		{
 			name:           "Missing image name",
 			containerImage: ":latest",
@@ -2284,7 +2294,7 @@ func TestValidateContainerImageFormat(t *testing.T) {
 		{
 			name:           "Invalid docker archive format - non-existent file",
 			containerImage: "docker-archive:nonexistent.tar",
-			expectedError:  errors.New("--container-images flag error: file does not exist"),
+			expectedError:  errors.New("--container-images flag error: file 'nonexistent.tar' does not exist"),
 		},
 
 		// OCI archive prefix tests
@@ -2303,7 +2313,7 @@ func TestValidateContainerImageFormat(t *testing.T) {
 		{
 			name:           "Invalid oci archive format - non-existent file",
 			containerImage: "oci-archive:nonexistent.tar",
-			expectedError:  errors.New("--container-images flag error: file does not exist"),
+			expectedError:  errors.New("--container-images flag error: file 'nonexistent.tar' does not exist"),
 		},
 
 		// OCI directory prefix tests (matches Syft behavior)
@@ -2366,7 +2376,7 @@ func TestValidateContainerImageFormat(t *testing.T) {
 		{
 			name:           "Invalid file format - non-existent file",
 			containerImage: "file:nonexistent.file",
-			expectedError:  errors.New("--container-images flag error: file does not exist"),
+			expectedError:  errors.New("--container-images flag error: file 'nonexistent.file' does not exist"),
 		},
 
 		// Registry prefix tests (restricted to single images only)