feat(vsa): generate digest-based VSAs for index and arch images

Switch VSA generation from name-based to digest-based grouping. Image index
expansion now records relationships between image indexes and their child
manifests, storing this mapping in the report. VSAs for an index image
include validation results for the index and all child images, while
VSAs for a child image contain only its own results.

Author: joejstuart

cmd/validate/__snapshots__/image_test.snap

@@ -1,4 +1,3 @@
-
 [Test_ValidateImageCommandYAMLPolicyFile/spec - 1]
 {
  "components": [
@@ -36,7 +35,6 @@
  "success": true
 }
 ---
-
 [Test_ValidateImageCommandYAMLPolicyFile/ecp - 1]
 {
  "components": [

cmd/validate/image.go

@@ -70,14 +70,16 @@ func validateImageCmd(validate imageValidationFunc) *cobra.Command {
 		rekorURL                    string
 		snapshot                    string
 		spec                        *app.SnapshotSpec
-		strict                      bool
-		images                      string
-		noColor                     bool
-		forceColor                  bool
-		workers                     int
-		vsaEnabled                  bool
-		vsaSigningKey               string
-		vsaUpload                   []string
+		// Only used to pass the expansion info to the report. Not a cli flag.
+		expansion     *applicationsnapshot.ExpansionInfo
+		strict        bool
+		images        string
+		noColor       bool
+		forceColor    bool
+		workers       int
+		vsaEnabled    bool
+		vsaSigningKey string
+		vsaUpload     []string
 	}{
 		strict:  true,
 		workers: 5,
@@ -200,7 +202,7 @@ func validateImageCmd(validate imageValidationFunc) *cobra.Command {
 				cmd.SetContext(ctx)
 			}
 
-			if s, err := applicationsnapshot.DetermineInputSpec(ctx, applicationsnapshot.Input{
+			if s, exp, err := applicationsnapshot.DetermineInputSpec(ctx, applicationsnapshot.Input{
 				File:     data.filePath,
 				JSON:     data.input,
 				Image:    data.imageRef,
@@ -210,6 +212,7 @@ func validateImageCmd(validate imageValidationFunc) *cobra.Command {
 				allErrors = errors.Join(allErrors, err)
 			} else {
 				data.spec = s
+				data.expansion = exp
 			}
 
 			policyConfiguration, err := validate_utils.GetPolicyConfig(ctx, data.policyConfiguration)
@@ -450,7 +453,7 @@ func validateImageCmd(validate imageValidationFunc) *cobra.Command {
 				data.output = append(data.output, fmt.Sprintf("%s=%s", applicationsnapshot.JSON, data.outputFile))
 			}
 
-			report, err := applicationsnapshot.NewReport(data.snapshot, components, data.policy, manyPolicyInput, showSuccesses)
+			report, err := applicationsnapshot.NewReport(data.snapshot, components, data.policy, manyPolicyInput, showSuccesses, data.expansion)
 			if err != nil {
 				return err
 			}

cmd/validate/image_test.go

@@ -323,7 +323,7 @@ func Test_determineInputSpec(t *testing.T) {
 	ctx := oci.WithClient(context.Background(), &client)
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {
-			s, err := applicationsnapshot.DetermineInputSpec(ctx, applicationsnapshot.Input{
+			s, _, err := applicationsnapshot.DetermineInputSpec(ctx, applicationsnapshot.Input{
 				File:   c.arguments.filePath,
 				JSON:   c.arguments.input,
 				Image:  c.arguments.imageRef,

internal/applicationsnapshot/expansion_info.go

@@ -0,0 +1,37 @@
+// 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 applicationsnapshot
+
+// ExpansionInfo tracks the relationships between image indexes and their child manifests
+// that are created when expanding multi-arch images.
+type ExpansionInfo struct {
+	// ChildrenByIndex maps an image index digest to the list of child manifest digests
+	ChildrenByIndex map[string][]string `json:"childrenByIndex,omitempty"`
+	// ParentByChild maps a child manifest digest to its parent index digest
+	ParentByChild map[string]string `json:"parentByChild,omitempty"`
+	// IndexAliases maps image references to their pinned digest form
+	IndexAliases map[string]string `json:"indexAliases,omitempty"`
+}
+
+// NewExpansionInfo creates a new ExpansionInfo instance
+func NewExpansionInfo() *ExpansionInfo {
+	return &ExpansionInfo{
+		ChildrenByIndex: make(map[string][]string),
+		ParentByChild:   make(map[string]string),
+		IndexAliases:    make(map[string]string),
+	}
+}

internal/applicationsnapshot/input.go

@@ -54,6 +54,7 @@ type Input struct {
 
 type snapshot struct {
 	app.SnapshotSpec
+	Expansion *ExpansionInfo
 }
 
 func (s *snapshot) merge(snap app.SnapshotSpec) {
@@ -89,7 +90,7 @@ func (s *snapshot) merge(snap app.SnapshotSpec) {
 	}
 }
 
-func DetermineInputSpec(ctx context.Context, input Input) (*app.SnapshotSpec, error) {
+func DetermineInputSpec(ctx context.Context, input Input) (*app.SnapshotSpec, *ExpansionInfo, error) {
 	var snapshot snapshot
 	provided := false
 
@@ -106,7 +107,7 @@ func DetermineInputSpec(ctx context.Context, input Input) (*app.SnapshotSpec, er
 
 		file, err := readSnapshotSource(content)
 		if err != nil {
-			return nil, err
+			return nil, nil, err
 		}
 		snapshot.merge(file)
 		provided = true
@@ -117,11 +118,11 @@ func DetermineInputSpec(ctx context.Context, input Input) (*app.SnapshotSpec, er
 		fs := utils.FS(ctx)
 		content, err := afero.ReadFile(fs, input.File)
 		if err != nil {
-			return nil, err
+			return nil, nil, err
 		}
 		file, err := readSnapshotSource(content)
 		if err != nil {
-			return nil, err
+			return nil, nil, err
 		}
 		snapshot.merge(file)
 		provided = true
@@ -131,7 +132,7 @@ func DetermineInputSpec(ctx context.Context, input Input) (*app.SnapshotSpec, er
 	if input.JSON != "" {
 		json, err := readSnapshotSource([]byte(input.JSON))
 		if err != nil {
-			return nil, err
+			return nil, nil, err
 		}
 		snapshot.merge(json)
 		provided = true
@@ -156,25 +157,29 @@ func DetermineInputSpec(ctx context.Context, input Input) (*app.SnapshotSpec, er
 		client, err := kubernetes.NewClient(ctx)
 		if err != nil {
 			log.Debugf("Unable to initialize Kubernetes Client: %v", err)
-			return nil, err
+			return nil, nil, err
 		}
 
 		cluster, err := client.FetchSnapshot(ctx, input.Snapshot)
 		if err != nil {
 			log.Debugf("Unable to fetch snapshot %s from Kubernetes cluster: %v", input.Snapshot, err)
-			return nil, err
+			return nil, nil, err
 		}
 		snapshot.merge(cluster.Spec)
 		provided = true
 	}
 
 	if !provided {
 		log.Debug("No application snapshot available")
-		return nil, errors.New("neither Snapshot nor image reference provided to validate")
+		return nil, nil, errors.New("neither Snapshot nor image reference provided to validate")
 	}
-	expandImageIndex(ctx, &snapshot.SnapshotSpec)
+	exp := expandImageIndex(ctx, &snapshot.SnapshotSpec)
 
-	return &snapshot.SnapshotSpec, nil
+	// Store expansion info in the snapshot for later use
+	// This will be used when building the Report
+	snapshot.Expansion = exp
+
+	return &snapshot.SnapshotSpec, exp, nil
 }
 
 func readSnapshotSource(input []byte) (app.SnapshotSpec, error) {
@@ -192,7 +197,7 @@ func readSnapshotSource(input []byte) (app.SnapshotSpec, error) {
 // For an image index, remove the original component and replace it with an expanded component with all its image manifests
 // Do not raise an error if the image is inaccessible, it will be handled as a violation when evaluated against the policy
 // This is to retain the original behavior of the `ec validate` command.
-func imageIndexWorker(client oci.Client, component app.SnapshotComponent, componentChan chan<- []app.SnapshotComponent, errorsChan chan<- error) {
+func imageIndexWorker(client oci.Client, component app.SnapshotComponent, componentChan chan<- []app.SnapshotComponent, errorsChan chan<- error, exp *ExpansionInfo) {
 	var components []app.SnapshotComponent
 	components = append(components, component)
 	// to avoid adding to componentsChan before each return
@@ -228,6 +233,10 @@ func imageIndexWorker(client oci.Client, component app.SnapshotComponent, compon
 		return
 	}
 
+	// Track expansion metadata
+	idxPinned := fmt.Sprintf("%s@%s", ref.Context().Name(), desc.Digest)
+	exp.IndexAliases[ref.Name()] = idxPinned
+
 	// Add the platform-specific image references (Image Manifests) to the list of components so
 	// each is validated as well as the multi-platform image reference (Image Index).
 	for i, manifest := range indexManifest.Manifests {
@@ -241,15 +250,21 @@ func imageIndexWorker(client oci.Client, component app.SnapshotComponent, compon
 		archComponent.Name = fmt.Sprintf("%s-%s-%s", component.Name, manifest.Digest, arch)
 		archComponent.ContainerImage = fmt.Sprintf("%s@%s", ref.Context().Name(), manifest.Digest)
 		components = append(components, archComponent)
+
+		// Track parent-child relationships
+		childPinned := archComponent.ContainerImage
+		exp.ChildrenByIndex[idxPinned] = append(exp.ChildrenByIndex[idxPinned], childPinned)
+		exp.ParentByChild[childPinned] = idxPinned
 	}
 }
 
-func expandImageIndex(ctx context.Context, snap *app.SnapshotSpec) {
+func expandImageIndex(ctx context.Context, snap *app.SnapshotSpec) *ExpansionInfo {
 	if trace.IsEnabled() {
 		region := trace.StartRegion(ctx, "ec:expand-image-index")
 		defer region.End()
 	}
 
+	exp := NewExpansionInfo()
 	client := oci.NewClient(ctx)
 
 	componentChan := make(chan []app.SnapshotComponent, len(snap.Components))
@@ -259,7 +274,7 @@ func expandImageIndex(ctx context.Context, snap *app.SnapshotSpec) {
 	for _, component := range snap.Components {
 		// fetch manifests concurrently
 		g.Go(func() error {
-			imageIndexWorker(client, component, componentChan, errorsChan)
+			imageIndexWorker(client, component, componentChan, errorsChan, exp)
 			return nil
 		})
 	}
@@ -289,6 +304,8 @@ func expandImageIndex(ctx context.Context, snap *app.SnapshotSpec) {
 		log.Warnf("Encountered error while checking for Image Index: %v", allErrors)
 	}
 	log.Debugf("Snap component after expanding the image index is %v", snap.Components)
+
+	return exp
 }
 
 func imageWorkers() int {

internal/applicationsnapshot/input_test.go

@@ -177,7 +177,7 @@ func Test_DetermineInputSpec(t *testing.T) {
 					panic(err)
 				}
 			}
-			got, err := DetermineInputSpec(ctx, tc.input)
+			got, _, err := DetermineInputSpec(ctx, tc.input)
 			// expect an error so check for nil
 			if tc.want != nil {
 				assert.NoError(t, err)

internal/applicationsnapshot/report.go

@@ -61,6 +61,7 @@ type Report struct {
 	EffectiveTime time.Time                        `json:"effective-time"`
 	PolicyInput   [][]byte                         `json:"-"`
 	ShowSuccesses bool                             `json:"-"`
+	Expansion     *ExpansionInfo                   `json:"-"`
 }
 
 type summary struct {
@@ -126,7 +127,7 @@ var OutputFormats = []string{
 
 // WriteReport returns a new instance of Report representing the state of
 // components from the snapshot.
-func NewReport(snapshot string, components []Component, policy policy.Policy, policyInput [][]byte, showSuccesses bool) (Report, error) {
+func NewReport(snapshot string, components []Component, policy policy.Policy, policyInput [][]byte, showSuccesses bool, expansion *ExpansionInfo) (Report, error) {
 	success := true
 
 	// Set the report success, remains true if all components are successful
@@ -157,6 +158,7 @@ func NewReport(snapshot string, components []Component, policy policy.Policy, po
 		PolicyInput:   policyInput,
 		EffectiveTime: policy.EffectiveTime().UTC(),
 		ShowSuccesses: showSuccesses,
+		Expansion:     expansion,
 	}, nil
 }
 

internal/applicationsnapshot/report_test.go

@@ -52,7 +52,7 @@ func Test_ReportJson(t *testing.T) {
 
 	ctx := context.Background()
 	testPolicy := createTestPolicy(t, ctx)
-	report, err := NewReport("snappy", components, testPolicy, nil, true)
+	report, err := NewReport("snappy", components, testPolicy, nil, true, nil)
 	assert.NoError(t, err)
 
 	testEffectiveTime := testPolicy.EffectiveTime().UTC().Format(time.RFC3339Nano)
@@ -110,7 +110,7 @@ func Test_ReportYaml(t *testing.T) {
 
 	ctx := context.Background()
 	testPolicy := createTestPolicy(t, ctx)
-	report, err := NewReport("snappy", components, testPolicy, nil, true)
+	report, err := NewReport("snappy", components, testPolicy, nil, true, nil)
 	assert.NoError(t, err)
 
 	testEffectiveTime := testPolicy.EffectiveTime().UTC().Format(time.RFC3339Nano)
@@ -257,7 +257,7 @@ func Test_GenerateMarkdownSummary(t *testing.T) {
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {
 			ctx := context.Background()
-			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true)
+			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true, nil)
 			assert.NoError(t, err)
 			report.created = time.Unix(0, 0).UTC()
 
@@ -504,7 +504,7 @@ func Test_ReportSummary(t *testing.T) {
 	for _, tc := range tests {
 		t.Run(fmt.Sprintf("NewReport=%s", tc.name), func(t *testing.T) {
 			ctx := context.Background()
-			report, err := NewReport(tc.snapshot, []Component{tc.input}, createTestPolicy(t, ctx), nil, true)
+			report, err := NewReport(tc.snapshot, []Component{tc.input}, createTestPolicy(t, ctx), nil, true, nil)
 			assert.NoError(t, err)
 			assert.Equal(t, tc.want, report.toSummary())
 		})
@@ -641,7 +641,7 @@ func Test_ReportAppstudio(t *testing.T) {
 			assert.NoError(t, err)
 
 			ctx := context.Background()
-			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true)
+			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true, nil)
 			assert.NoError(t, err)
 			assert.False(t, report.created.IsZero())
 			assert.Equal(t, c.success, report.Success)
@@ -789,7 +789,7 @@ func Test_ReportHACBS(t *testing.T) {
 			assert.NoError(t, err)
 
 			ctx := context.Background()
-			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true)
+			report, err := NewReport(c.snapshot, c.components, createTestPolicy(t, ctx), nil, true, nil)
 			assert.NoError(t, err)
 			assert.False(t, report.created.IsZero())
 			assert.Equal(t, c.success, report.Success)
@@ -821,7 +821,7 @@ func Test_ReportPolicyInput(t *testing.T) {
 	}
 
 	ctx := context.Background()
-	report, err := NewReport("snapshot", nil, createTestPolicy(t, ctx), policyInput, true)
+	report, err := NewReport("snapshot", nil, createTestPolicy(t, ctx), policyInput, true, nil)
 	require.NoError(t, err)
 
 	p := format.NewTargetParser(JSON, format.Options{}, defaultWriter, fs)

internal/input/report_test.go

@@ -233,7 +233,7 @@ func Test_ReportSummary(t *testing.T) {
 		t.Run(fmt.Sprintf("NewReport=%s", tc.name), func(t *testing.T) {
 			ctx := context.Background()
 			report, err := NewReport(tc.input, createTestPolicy(t, ctx), nil)
-			// report, err := NewReport(tc.snapshot, []Component{tc.input}, createTestPolicy(t, ctx), nil)
+			// report, err := NewReport(tc.snapshot, []Component{tc.input}, createTestPolicy(t, ctx), nil, nil)
 			assert.NoError(t, err)
 			fmt.Println("\n\nExpected:\n", tc.want, "\n\nActual:\n", report.toSummary())
 			assert.Equal(t, tc.want, report.toSummary())