Add reference attestation for multiple equivalent images (#2467)

Signed-off-by: robert-cronin <[email protected]>

Author: robert-cronin

internal/testing/testdata/models.go

@@ -608,3 +608,81 @@ var ITE6EOLPython = []byte(`{
         }
     }
 }`)
+
+// ITE6ReferenceSingle is a test document for the Reference ingestor with a single reference
+var ITE6ReferenceSingle = []byte(`{
+    "type": "https://in-toto.io/Statement/v1",
+    "subject": [
+        {
+            "uri": "pkg:npm/[email protected]"
+        }
+    ],
+    "predicateType": "https://in-toto.io/attestation/reference/v0.1",
+    "predicate": {
+        "attester": {
+            "id": "attester-123"
+        },
+        "references": [
+            {
+                "downloadLocation": "https://example.com/downloads/pkg.tar.gz",
+                "digest": {
+                    "sha256": "abcd1234..."
+                },
+                "mediaType": "application/x-tar"
+            }
+        ]
+    }
+}`)
+
+// ITE6ReferenceMultiple is a test document for the Reference ingestor with multiple references
+var ITE6ReferenceMultiple = []byte(`{
+    "type": "https://in-toto.io/Statement/v1",
+    "subject": [
+        {
+            "uri": "pkg:pypi/[email protected]"
+        }
+    ],
+    "predicateType": "https://in-toto.io/attestation/reference/v0.1",
+    "predicate": {
+        "attester": {
+            "id": "attester-xyz"
+        },
+        "references": [
+            {
+                "downloadLocation": "https://example.com/artifacts/python-ref1.tgz",
+                "digest": {
+                    "sha256": "aa1111111111111111111111111111111111111111111111111111111111111111"
+                },
+                "mediaType": "application/octet-stream"
+            },
+            {
+                "downloadLocation": "https://example.com/artifacts/python-ref2.whl",
+                "digest": {
+                    "sha256": "bb2222222222222222222222222222222222222222222222222222222222222222"
+                },
+                "mediaType": "application/zip"
+            }
+        ]
+    }
+}`)
+
+// ITE6ReferenceNoSubject is a test document for the Reference ingestor with no subject provided
+var ITE6ReferenceNoSubject = []byte(`{
+    "type": "https://in-toto.io/Statement/v1",
+    "subject": [],
+    "predicateType": "https://in-toto.io/attestation/reference/v0.1",
+    "predicate": {
+        "attester": {
+            "id": "attester-nobody"
+        },
+        "references": [
+            {
+                "downloadLocation": "https://example.com/artifacts/no-subject.tgz",
+                "digest": {
+                    "sha256": "no-subject-digest"
+                },
+                "mediaType": "application/octet-stream"
+            }
+        ]
+    }
+}`)

pkg/certifier/attestation/reference/attestation_reference.go

@@ -0,0 +1,54 @@
+//
+// Copyright 2025 The GUAC Authors.
+//
+// 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 attestation
+
+import (
+	attestationv1 "github.com/in-toto/attestation/go/v1"
+)
+
+const (
+	PredicateReference = "https://in-toto.io/attestation/reference/v0.1"
+)
+
+// ReferenceStatement defines the statement header and the Reference predicate
+type ReferenceStatement struct {
+	attestationv1.Statement
+	// Predicate contains type specific metadata.
+	Predicate ReferencePredicate `json:"predicate"`
+}
+
+// ReferencePredicate defines predicate definition of the Reference attestation
+type ReferencePredicate struct {
+	Attester   ReferenceAttester `json:"attester"`
+	References []ReferenceItem   `json:"references"`
+}
+
+// ReferenceAttester defines the attester information
+type ReferenceAttester struct {
+	ID string `json:"id"`
+}
+
+// ReferenceItem represents an individual reference in the predicate
+type ReferenceItem struct {
+	DownloadLocation string              `json:"downloadLocation"`
+	Digest           ReferenceDigestItem `json:"digest"`
+	MediaType        string              `json:"mediaType"`
+}
+
+// ReferenceDigestItem represents an individual digest in the predicate
+type ReferenceDigestItem struct {
+	SHA256 string `json:"sha256"`
+}

pkg/handler/processor/ite6/ite6.go

@@ -35,7 +35,8 @@ func (e *ITE6Processor) ValidateSchema(i *processor.Document) error {
 		i.Type != processor.DocumentITE6SLSA &&
 		i.Type != processor.DocumentITE6Vul &&
 		i.Type != processor.DocumentITE6ClearlyDefined &&
-		i.Type != processor.DocumentITE6EOL {
+		i.Type != processor.DocumentITE6EOL &&
+		i.Type != processor.DocumentITE6Reference {
 		return fmt.Errorf("expected ITE6 document type, actual document type: %v", i.Type)
 	}
 

pkg/handler/processor/process/process.go

@@ -60,6 +60,7 @@ func init() {
 	_ = RegisterDocumentProcessor(&ite6.ITE6Processor{}, processor.DocumentITE6Vul)
 	_ = RegisterDocumentProcessor(&ite6.ITE6Processor{}, processor.DocumentITE6ClearlyDefined)
 	_ = RegisterDocumentProcessor(&ite6.ITE6Processor{}, processor.DocumentITE6EOL)
+	_ = RegisterDocumentProcessor(&ite6.ITE6Processor{}, processor.DocumentITE6Reference)
 	_ = RegisterDocumentProcessor(&dsse.DSSEProcessor{}, processor.DocumentDSSE)
 	_ = RegisterDocumentProcessor(&spdx.SPDXProcessor{}, processor.DocumentSPDX)
 	_ = RegisterDocumentProcessor(&csaf.CSAFProcessor{}, processor.DocumentCsaf)

pkg/handler/processor/processor.go

@@ -56,10 +56,11 @@ type DocumentType string
 
 // Document* is the enumerables of DocumentType
 const (
-	DocumentITE6SLSA    DocumentType = "SLSA"
-	DocumentITE6Generic DocumentType = "ITE6"
-	DocumentITE6Vul     DocumentType = "ITE6VUL"
-	DocumentITE6EOL     DocumentType = "ITE6EOL"
+	DocumentITE6SLSA      DocumentType = "SLSA"
+	DocumentITE6Generic   DocumentType = "ITE6"
+	DocumentITE6Vul       DocumentType = "ITE6VUL"
+	DocumentITE6EOL       DocumentType = "ITE6EOL"
+	DocumentITE6Reference DocumentType = "ITE6REF"
 	// ClearlyDefined
 	DocumentITE6ClearlyDefined DocumentType = "ITE6CD"
 	DocumentDSSE               DocumentType = "DSSE"

pkg/ingestor/parser/parser.go

@@ -32,6 +32,7 @@ import (
 	"github.com/guacsec/guac/pkg/ingestor/parser/eol"
 	"github.com/guacsec/guac/pkg/ingestor/parser/opaque"
 	"github.com/guacsec/guac/pkg/ingestor/parser/open_vex"
+	"github.com/guacsec/guac/pkg/ingestor/parser/reference"
 	"github.com/guacsec/guac/pkg/ingestor/parser/scorecard"
 	"github.com/guacsec/guac/pkg/ingestor/parser/slsa"
 	"github.com/guacsec/guac/pkg/ingestor/parser/spdx"
@@ -50,6 +51,7 @@ func init() {
 	_ = RegisterDocumentParser(csaf.NewCsafParser, processor.DocumentCsaf)
 	_ = RegisterDocumentParser(open_vex.NewOpenVEXParser, processor.DocumentOpenVEX)
 	_ = RegisterDocumentParser(eol.NewEOLCertificationParser, processor.DocumentITE6EOL)
+	_ = RegisterDocumentParser(reference.NewReferenceParser, processor.DocumentITE6Reference)
 	_ = RegisterDocumentParser(opaque.NewOpaqueParser, processor.DocumentOpaque)
 }
 

pkg/ingestor/parser/reference/reference.go

@@ -0,0 +1,162 @@
+//
+// Copyright 2025 The GUAC Authors.
+//
+// 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 reference
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	jsoniter "github.com/json-iterator/go"
+
+	"github.com/guacsec/guac/pkg/assembler"
+	"github.com/guacsec/guac/pkg/assembler/clients/generated"
+	"github.com/guacsec/guac/pkg/assembler/helpers"
+	attestation "github.com/guacsec/guac/pkg/certifier/attestation/reference"
+	"github.com/guacsec/guac/pkg/handler/processor"
+	"github.com/guacsec/guac/pkg/ingestor/parser/common"
+	"github.com/guacsec/guac/pkg/logging"
+)
+
+var json = jsoniter.ConfigCompatibleWithStandardLibrary
+
+const (
+	justification = "Retrieved from reference predicate"
+)
+
+type parser struct {
+	doc                *processor.Document
+	pkg                *generated.PkgInputSpec
+	collectedReference []assembler.IsOccurrenceIngest
+	identifierStrings  *common.IdentifierStrings
+	timeScanned        time.Time
+}
+
+// newReferenceParser initializes the parser
+func NewReferenceParser() common.DocumentParser {
+	return &parser{
+		identifierStrings: &common.IdentifierStrings{},
+	}
+}
+
+// initializeReferenceParser clears out all values for the next iteration
+func (r *parser) initializeReferenceParser() {
+	r.doc = nil
+	r.pkg = nil
+	r.collectedReference = make([]assembler.IsOccurrenceIngest, 0)
+	r.identifierStrings = &common.IdentifierStrings{}
+	r.timeScanned = time.Now()
+}
+
+// Parse breaks out the document into the graph components
+func (r *parser) Parse(ctx context.Context, doc *processor.Document) error {
+	logger := logging.FromContext(ctx)
+	r.initializeReferenceParser()
+	r.doc = doc
+
+	statement, err := parseReferenceStatement(doc.Blob)
+	if err != nil {
+		return fmt.Errorf("failed to parse reference predicate: %w", err)
+	}
+
+	r.timeScanned = time.Now()
+
+	if err := r.parseSubject(statement); err != nil {
+		logger.Warnf("unable to parse subject of statement: %v", err)
+		return fmt.Errorf("unable to parse subject of statement: %w", err)
+	}
+
+	if err := r.parseReferences(ctx, statement); err != nil {
+		logger.Warnf("unable to parse reference statement: %v", err)
+		return fmt.Errorf("unable to parse reference statement: %w", err)
+	}
+
+	return nil
+}
+
+func parseReferenceStatement(p []byte) (*attestation.ReferenceStatement, error) {
+	statement := attestation.ReferenceStatement{}
+	if err := json.Unmarshal(p, &statement); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal reference predicate: %w", err)
+	}
+	return &statement, nil
+}
+
+func (r *parser) parseSubject(s *attestation.ReferenceStatement) error {
+	if len(s.Statement.Subject) == 0 {
+		return fmt.Errorf("no subject found in reference statement")
+	}
+
+	for _, sub := range s.Statement.Subject {
+		p, err := helpers.PurlToPkg(sub.Uri)
+		if err != nil {
+			return fmt.Errorf("failed to parse uri: %s to a package with error: %w", sub.Uri, err)
+		}
+		r.pkg = p
+		r.identifierStrings.PurlStrings = append(r.identifierStrings.PurlStrings, sub.Uri)
+	}
+	return nil
+}
+
+// parseReferences parses the attestation to collect the reference information
+func (r *parser) parseReferences(_ context.Context, s *attestation.ReferenceStatement) error {
+	if r.pkg == nil {
+		return fmt.Errorf("package not specified for reference information")
+	}
+
+	for _, ref := range s.Predicate.References {
+		refData := assembler.IsOccurrenceIngest{
+			Pkg: r.pkg,
+			Artifact: &generated.ArtifactInputSpec{
+				Algorithm: "sha256",
+				Digest:    ref.Digest.SHA256,
+			},
+			IsOccurrence: &generated.IsOccurrenceInputSpec{
+				Justification: justification,
+				Collector:     "GUAC",
+				Origin:        "GUAC Reference",
+				DocumentRef:   ref.DownloadLocation,
+			},
+		}
+
+		r.collectedReference = append(r.collectedReference, refData)
+	}
+
+	return nil
+}
+
+func (r *parser) GetPredicates(ctx context.Context) *assembler.IngestPredicates {
+	logger := logging.FromContext(ctx)
+	preds := &assembler.IngestPredicates{}
+
+	if r.pkg == nil {
+		logger.Error("error getting predicates: unable to find package element")
+		return preds
+	}
+
+	preds.IsOccurrence = r.collectedReference
+	return preds
+}
+
+// GetIdentities gets the identity node from the document if they exist
+func (r *parser) GetIdentities(ctx context.Context) []common.TrustInformation {
+	return nil
+}
+
+func (r *parser) GetIdentifiers(ctx context.Context) (*common.IdentifierStrings, error) {
+	common.RemoveDuplicateIdentifiers(r.identifierStrings)
+	return r.identifierStrings, nil
+}