Merge pull request #3004 from joejstuart/image-fallback

Fallback to validate image

Author: joejstuart

cmd/validate/vsa.go

@@ -9,6 +9,9 @@ Validate VSA by comparing the embedded policy against a supplied policy configur
 By default, VSA signature verification is enabled and requires a public key.
 Use --ignore-signature-verification to disable signature verification.
 
+By default, fallback to image validation is enabled when VSA validation fails.
+Use --no-fallback to disable this behavior.
+
 Supports validation of:
 - Single VSA by identifier (image digest, file path)
 - Multiple VSAs from application snapshot
@@ -26,17 +29,18 @@ ec validate vsa <vsa-identifier> [flags]
 
 --color:: Enable color when using text output even when the current terminal does not support it (Default: false)
 --effective-time:: Effective time for comparison (Default: now)
+--fallback-public-key:: Public key to use for fallback image validation (different from VSA verification key)
 -h, --help:: help for vsa (Default: false)
 --ignore-signature-verification:: Ignore VSA signature verification (signature verification is enabled by default) (Default: false)
 --images:: Application snapshot file
 --no-color:: Disable color when using text output even when the current terminal supports it (Default: false)
---output:: Output formats (Default: [])
--o, --output-file:: Output file
+--no-fallback:: Disable fallback to image validation when VSA validation fails (fallback is enabled by default) (Default: false)
+--output:: Output formats (e.g., json, yaml, text) (Default: [])
 -p, --policy:: Policy configuration
---public-key:: Path to public key for signature verification (required by default)
 --strict:: Exit with non-zero code if validation fails (Default: true)
 -v, --vsa:: VSA identifier (image digest, file path)
 --vsa-expiration:: VSA expiration threshold (e.g., 24h, 7d, 1w, 1m) (Default: 168h)
+--vsa-public-key:: Path to public key for VSA signature verification (required by default)
 --vsa-retrieval:: VSA retrieval backends (rekor@, file@) (Default: [])
 --workers:: Number of worker threads for parallel processing (Default: 5)
 

cmd/validate/vsa_test.go

@@ -65,6 +65,7 @@ replace github.com/google/go-containerregistry => github.com/conforma/go-contain
 require (
 	github.com/go-openapi/runtime v0.28.0
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2
+	golang.org/x/text v0.28.0
 	gopkg.in/yaml.v3 v3.0.1
 	k8s.io/api v0.32.3
 )
@@ -372,7 +373,6 @@ require (
 	golang.org/x/oauth2 v0.30.0 // indirect
 	golang.org/x/sys v0.35.0 // indirect
 	golang.org/x/term v0.34.0 // indirect
-	golang.org/x/text v0.28.0 // indirect
 	golang.org/x/time v0.11.0 // indirect
 	golang.org/x/tools v0.35.0 // indirect
 	gomodules.xyz/jsonpatch/v2 v2.4.0 // indirect

docs/modules/ROOT/pages/ec_validate_vsa.adoc

@@ -0,0 +1,269 @@
+// Copyright The Conforma Contributors
+//
+// 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.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+package vsa
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"golang.org/x/text/cases"
+	"golang.org/x/text/language"
+)
+
+// ValidationError represents a structured validation error with causes
+type ValidationError struct {
+	Message string  `json:"message"`
+	Causes  []Cause `json:"causes"`
+}
+
+// Cause represents a specific cause of validation failure
+type Cause struct {
+	Type      string  `json:"type"` // "vsa", "fallback", "network", "policy", etc.
+	Message   string  `json:"message"`
+	Details   string  `json:"details,omitempty"`
+	SubCauses []Cause `json:"sub_causes,omitempty"`
+	Timestamp string  `json:"timestamp,omitempty"`
+	Severity  string  `json:"severity,omitempty"` // "error", "warning", "info"
+}
+
+// ErrorType constants
+const (
+	ErrorTypeVSA       = "vsa"
+	ErrorTypeFallback  = "fallback"
+	ErrorTypeNetwork   = "network"
+	ErrorTypePolicy    = "policy"
+	ErrorTypeSignature = "signature"
+	ErrorTypeTimeout   = "timeout"
+	ErrorTypeRetrieval = "retrieval"
+)
+
+// Severity constants
+const (
+	SeverityError   = "error"
+	SeverityWarning = "warning"
+	SeverityInfo    = "info"
+)
+
+// Error implements the error interface
+func (ve *ValidationError) Error() string {
+	if ve == nil {
+		return ""
+	}
+
+	var parts []string
+	parts = append(parts, ve.Message)
+
+	for _, cause := range ve.Causes {
+		parts = append(parts, fmt.Sprintf("- %s: %s", cause.Type, cause.Message))
+		if cause.Details != "" {
+			parts = append(parts, fmt.Sprintf("  Details: %s", cause.Details))
+		}
+	}
+
+	return strings.Join(parts, "\n")
+}
+
+// HumanReadable returns a formatted human-readable version of the error
+func (ve *ValidationError) HumanReadable() string {
+	if ve == nil {
+		return ""
+	}
+
+	var builder strings.Builder
+	builder.WriteString(fmt.Sprintf("❌ %s\n", ve.Message))
+
+	for _, cause := range ve.Causes {
+		builder.WriteString(fmt.Sprintf("\n%s Failure\n", cases.Title(language.English).String(cause.Type)))
+		builder.WriteString(fmt.Sprintf("  Message: %s\n", cause.Message))
+
+		if cause.Details != "" {
+			builder.WriteString(fmt.Sprintf("  Details: %s\n", cause.Details))
+		}
+
+		if cause.Timestamp != "" {
+			builder.WriteString(fmt.Sprintf("  Time: %s\n", cause.Timestamp))
+		}
+
+		if len(cause.SubCauses) > 0 {
+			// Determine label based on severity
+			label := "Violations"
+			if len(cause.SubCauses) > 0 && cause.SubCauses[0].Severity == SeverityWarning {
+				label = "Warnings"
+			}
+			builder.WriteString(fmt.Sprintf("  %s:\n", label))
+			for _, subCause := range cause.SubCauses {
+				builder.WriteString(fmt.Sprintf("    - %s\n", subCause.Message))
+			}
+		}
+	}
+
+	return builder.String()
+}
+
+// BuildValidationError creates a structured error from VSA and fallback results
+func BuildValidationError(vsaResult *ValidationResult, fallbackResult *ImageValidationResult, vsaErr, fallbackErr error) *ValidationError {
+	var causes []Cause
+
+	// Add VSA failure cause
+	if vsaErr != nil || (vsaResult != nil && !vsaResult.Passed) {
+		vsaCause := buildVSACause(vsaResult, vsaErr)
+		causes = append(causes, vsaCause)
+	}
+
+	// Add fallback failure cause
+	if fallbackErr != nil || (fallbackResult != nil && !fallbackResult.Passed) {
+		fallbackCause := buildFallbackCause(fallbackResult, fallbackErr)
+		causes = append(causes, fallbackCause)
+	}
+
+	if len(causes) == 0 {
+		return nil
+	}
+
+	message := "Validation failed"
+	if len(causes) > 1 {
+		message = "Both VSA and fallback validation failed"
+	} else if len(causes) == 1 {
+		message = fmt.Sprintf("%s validation failed", cases.Title(language.English).String(causes[0].Type))
+	}
+
+	return &ValidationError{
+		Message: message,
+		Causes:  causes,
+	}
+}
+
+// buildVSACause creates a cause for VSA validation failure
+func buildVSACause(vsaResult *ValidationResult, vsaErr error) Cause {
+	cause := Cause{
+		Type:      ErrorTypeVSA,
+		Message:   "VSA validation failed",
+		Timestamp: time.Now().Format(time.RFC3339),
+		Severity:  SeverityError,
+	}
+
+	if vsaErr != nil {
+		cause.Details = vsaErr.Error()
+		// Try to categorize the error
+		if strings.Contains(vsaErr.Error(), "signature") {
+			cause.SubCauses = append(cause.SubCauses, Cause{
+				Type:    ErrorTypeSignature,
+				Message: "Signature verification failed",
+				Details: vsaErr.Error(),
+			})
+		} else if strings.Contains(vsaErr.Error(), "timeout") {
+			cause.SubCauses = append(cause.SubCauses, Cause{
+				Type:    ErrorTypeTimeout,
+				Message: "VSA retrieval timeout",
+				Details: vsaErr.Error(),
+			})
+		} else if strings.Contains(vsaErr.Error(), "network") || strings.Contains(vsaErr.Error(), "connection") {
+			cause.SubCauses = append(cause.SubCauses, Cause{
+				Type:    ErrorTypeNetwork,
+				Message: "Network error during VSA retrieval",
+				Details: vsaErr.Error(),
+			})
+		}
+	} else if vsaResult != nil {
+		cause.Details = vsaResult.Message
+		if vsaResult.PredicateOutcome != "" && vsaResult.PredicateOutcome != "passed" {
+			cause.SubCauses = append(cause.SubCauses, Cause{
+				Type:    ErrorTypePolicy,
+				Message: fmt.Sprintf("Predicate status: %s", vsaResult.PredicateOutcome),
+				Details: vsaResult.Message,
+			})
+		}
+	}
+
+	return cause
+}
+
+// buildFallbackCause creates a cause for fallback validation failure
+func buildFallbackCause(fallbackResult *ImageValidationResult, fallbackErr error) Cause {
+	cause := Cause{
+		Type:      ErrorTypeFallback,
+		Message:   "Fallback validation failed",
+		Timestamp: time.Now().Format(time.RFC3339),
+		Severity:  SeverityError,
+	}
+
+	if fallbackErr != nil {
+		cause.Details = fallbackErr.Error()
+	} else if fallbackResult != nil {
+		// Extract details from violations
+		if len(fallbackResult.Violations) > 0 {
+			cause.Details = fmt.Sprintf("%d policy violations found", len(fallbackResult.Violations))
+
+			// Add sub-causes for each violation
+			for _, violation := range fallbackResult.Violations {
+				subCause := Cause{
+					Type:     ErrorTypePolicy,
+					Message:  violation.Message,
+					Details:  "Policy violation",
+					Severity: SeverityError,
+				}
+				cause.SubCauses = append(cause.SubCauses, subCause)
+			}
+		}
+
+		// Add warnings as sub-causes with lower severity
+		for _, warning := range fallbackResult.Warnings {
+			subCause := Cause{
+				Type:     ErrorTypePolicy,
+				Message:  warning.Message,
+				Details:  "Policy warning",
+				Severity: SeverityWarning,
+			}
+			cause.SubCauses = append(cause.SubCauses, subCause)
+		}
+	}
+
+	return cause
+}
+
+// BuildNetworkError creates a structured error for network-related failures
+func BuildNetworkError(operation string, err error) *ValidationError {
+	return &ValidationError{
+		Message: fmt.Sprintf("Network operation failed: %s", operation),
+		Causes: []Cause{
+			{
+				Type:      ErrorTypeNetwork,
+				Message:   fmt.Sprintf("Failed to %s", operation),
+				Details:   err.Error(),
+				Timestamp: time.Now().Format(time.RFC3339),
+				Severity:  SeverityError,
+			},
+		},
+	}
+}
+
+// BuildTimeoutError creates a structured error for timeout failures
+func BuildTimeoutError(operation string, timeout time.Duration) *ValidationError {
+	return &ValidationError{
+		Message: fmt.Sprintf("Operation timed out: %s", operation),
+		Causes: []Cause{
+			{
+				Type:      ErrorTypeTimeout,
+				Message:   fmt.Sprintf("Timeout after %v", timeout),
+				Details:   fmt.Sprintf("Operation '%s' exceeded timeout of %v", operation, timeout),
+				Timestamp: time.Now().Format(time.RFC3339),
+				Severity:  SeverityError,
+			},
+		},
+	}
+}