Migrate SPDX-JSON relationships to SBOM model (#634)

* remove power-user document shape Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * add power-user specific fields to syft-json format Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * port remaining spdx-json relationships to sbom model Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * add coordinate set Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * add SBOM file path helper Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * use internal mimetype helper in go binary cataloger Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * add new package-of relationship Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * update json schema to v2 Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * replace power-user presenter with syft-json format Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * fix tests and linting Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * remove "package-of" relationship (in favor of "contains") Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * add tests for spdx22json format encoding enhancements Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * update TODO and log entries Signed-off-by: Alex Goodman <alex.goodman@anchore.com> * introduce sbom.Descriptor Signed-off-by: Alex Goodman <alex.goodman@anchore.com>
2026-11-03 16:06:36 +01:00 · 2021-11-23 14:54:17 -05:00
parent e3b34813d7
commit bd9007fc0e
41 changed files with 2238 additions and 718 deletions
@@ -3,17 +3,17 @@ package model
 type FileType string

 const (
-	DocumentationFileType FileType = "DOCUMENTATION"
-	ImageFileType         FileType = "IMAGE"
-	VideoFileType         FileType = "VIDEO"
-	ArchiveFileType       FileType = "ARCHIVE"
-	SpdxFileType          FileType = "SPDX"
-	ApplicationFileType   FileType = "APPLICATION"
-	SourceFileType        FileType = "SOURCE"
-	BinaryFileType        FileType = "BINARY"
-	TextFileType          FileType = "TEXT"
-	AudioFileType         FileType = "AUDIO"
-	OtherFileType         FileType = "OTHER"
+	DocumentationFileType FileType = "DOCUMENTATION" // if the file serves as documentation
+	ImageFileType         FileType = "IMAGE"         // if the file is associated with a picture image file (MIME type of image/*, e.g., .jpg, .gif)
+	VideoFileType         FileType = "VIDEO"         // if the file is associated with a video file type (MIME type of video/*)
+	ArchiveFileType       FileType = "ARCHIVE"       // if the file represents an archive (.tar, .jar, etc.)
+	SpdxFileType          FileType = "SPDX"          // if the file is an SPDX document
+	ApplicationFileType   FileType = "APPLICATION"   // if the file is associated with a specific application type (MIME type of application/*)
+	SourceFileType        FileType = "SOURCE"        // if the file is human readable source code (.c, .html, etc.)
+	BinaryFileType        FileType = "BINARY"        // if the file is a compiled object, target image or binary executable (.o, .a, etc.)
+	TextFileType          FileType = "TEXT"          // if the file is human readable text file (MIME type of text/*)
+	AudioFileType         FileType = "AUDIO"         // if the file is associated with an audio file (MIME type of audio/* , e.g. .mp3)
+	OtherFileType         FileType = "OTHER"         // if the file doesn't fit into the above categories (generated artifacts, data files, etc.)
 )

 type File struct {
@@ -36,6 +36,6 @@ type File struct {
 	// Indicates the project in which the SpdxElement originated. Tools must preserve doap:homepage and doap:name
 	// properties and the URI (if one is known) of doap:Project resources that are values of this property. All other
 	// properties of doap:Projects are not directly supported by SPDX and may be dropped when translating to or
-	// from some SPDX formats(deprecated).
+	// from some SPDX formats (deprecated).
 	ArtifactOf []string `json:"artifactOf,omitempty"`
 }
@@ -3,18 +3,18 @@
 "name": "/some/path",
 "spdxVersion": "SPDX-2.2",
 "creationInfo": {
-  "created": "2021-10-29T16:26:08.995826Z",
+  "created": "2021-11-17T19:35:54.834877Z",
  "creators": [
   "Organization: Anchore, Inc",
   "Tool: syft-[not provided]"
  ],
-  "licenseListVersion": "3.14"
+  "licenseListVersion": "3.15"
 },
 "dataLicense": "CC0-1.0",
- "documentNamespace": "https:/anchore.com/syft/dir/some/path-5362d380-914a-458f-b059-d8d27899574c",
+ "documentNamespace": "https:/anchore.com/syft/dir/some/path-65e2226e-a61e-4ed1-81bb-56022e1ff1eb",
 "packages": [
  {
-   "SPDXID": "SPDXRef-Package-python-package-1-1.0.1",
+   "SPDXID": "SPDXRef-2a115ac97d018a0e",
   "name": "package-1",
   "licenseConcluded": "MIT",
   "downloadLocation": "NOASSERTION",
@@ -31,15 +31,12 @@
    }
   ],
   "filesAnalyzed": false,
-   "hasFiles": [
-    "SPDXRef-File-package-1-efae7fecc76ca25da40f79d7ef5b8933510434914835832c7976f3e866aa756a"
-   ],
   "licenseDeclared": "MIT",
   "sourceInfo": "acquired package info from installed python package manifest file: /some/path/pkg1",
   "versionInfo": "1.0.1"
  },
  {
-   "SPDXID": "SPDXRef-Package-deb-package-2-2.0.1",
+   "SPDXID": "SPDXRef-5e920b2bece2c3ae",
   "name": "package-2",
   "licenseConcluded": "NONE",
   "downloadLocation": "NOASSERTION",
@@ -60,20 +57,5 @@
   "sourceInfo": "acquired package info from DPKG DB: /some/path/pkg1",
   "versionInfo": "2.0.1"
  }
- ],
- "files": [
-  {
-   "SPDXID": "SPDXRef-File-package-1-efae7fecc76ca25da40f79d7ef5b8933510434914835832c7976f3e866aa756a",
-   "name": "foo",
-   "licenseConcluded": "",
-   "fileName": "/some/path/pkg1/dependencies/foo"
-  }
- ],
- "relationships": [
-  {
-   "spdxElementId": "SPDXRef-Package-python-package-1-1.0.1",
-   "relationshipType": "CONTAINS",
-   "relatedSpdxElement": "SPDXRef-File-package-1-efae7fecc76ca25da40f79d7ef5b8933510434914835832c7976f3e866aa756a"
-  }
 ]
 }
@@ -3,18 +3,18 @@
 "name": "user-image-input",
 "spdxVersion": "SPDX-2.2",
 "creationInfo": {
-  "created": "2021-10-29T16:26:09.001799Z",
+  "created": "2021-11-17T19:35:57.761372Z",
  "creators": [
   "Organization: Anchore, Inc",
   "Tool: syft-[not provided]"
  ],
-  "licenseListVersion": "3.14"
+  "licenseListVersion": "3.15"
 },
 "dataLicense": "CC0-1.0",
- "documentNamespace": "https:/anchore.com/syft/image/user-image-input-3ad8571c-513f-4fce-944e-5125353c3186",
+ "documentNamespace": "https:/anchore.com/syft/image/user-image-input-5383918f-ec96-4aa9-b756-ad16e1ada31e",
 "packages": [
  {
-   "SPDXID": "SPDXRef-Package-python-package-1-1.0.1",
+   "SPDXID": "SPDXRef-888661d4f0362f02",
   "name": "package-1",
   "licenseConcluded": "MIT",
   "downloadLocation": "NOASSERTION",
@@ -36,7 +36,7 @@
   "versionInfo": "1.0.1"
  },
  {
-   "SPDXID": "SPDXRef-Package-deb-package-2-2.0.1",
+   "SPDXID": "SPDXRef-4068ff5e8926b305",
   "name": "package-2",
   "licenseConcluded": "NONE",
   "downloadLocation": "NOASSERTION",
@@ -3,17 +3,21 @@ package spdx22json
 import (
 	"fmt"
 	"path"
+	"path/filepath"
+	"sort"
 	"strings"
 	"time"

-	"github.com/anchore/syft/syft/sbom"
-
 	"github.com/anchore/syft/internal"
 	"github.com/anchore/syft/internal/formats/common/spdxhelpers"
 	"github.com/anchore/syft/internal/formats/spdx22json/model"
+	"github.com/anchore/syft/internal/log"
 	"github.com/anchore/syft/internal/spdxlicense"
 	"github.com/anchore/syft/internal/version"
+	"github.com/anchore/syft/syft/artifact"
+	"github.com/anchore/syft/syft/file"
 	"github.com/anchore/syft/syft/pkg"
+	"github.com/anchore/syft/syft/sbom"
 	"github.com/anchore/syft/syft/source"
 	"github.com/google/uuid"
 )
@@ -21,7 +25,6 @@ import (
 // toFormatModel creates and populates a new JSON document struct that follows the SPDX 2.2 spec from the given cataloging results.
 func toFormatModel(s sbom.SBOM) model.Document {
 	name := documentName(s.Source)
-	packages, files, relationships := extractFromCatalog(s.Artifacts.PackageCatalog)

 	return model.Document{
 		Element: model.Element{
@@ -40,9 +43,9 @@ func toFormatModel(s sbom.SBOM) model.Document {
 		},
 		DataLicense:       "CC0-1.0",
 		DocumentNamespace: documentNamespace(name, s.Source),
-		Packages:          packages,
-		Files:             files,
-		Relationships:     relationships,
+		Packages:          toPackages(s.Artifacts.PackageCatalog, s.Relationships),
+		Files:             toFiles(s),
+		Relationships:     toRelationships(s.Relationships),
 	}
 }

@@ -58,6 +61,17 @@ func documentName(srcMetadata source.Metadata) string {
 	return uuid.Must(uuid.NewRandom()).String()
 }

+func cleanSPDXName(name string) string {
+	// remove # according to specification
+	name = strings.ReplaceAll(name, "#", "-")
+
+	// remove : for url construction
+	name = strings.ReplaceAll(name, ":", "-")
+
+	// clean relative pathing
+	return path.Clean(name)
+}
+
 func documentNamespace(name string, srcMetadata source.Metadata) string {
 	input := "unknown-source-type"
 	switch srcMetadata.Scheme {
@@ -76,19 +90,12 @@ func documentNamespace(name string, srcMetadata source.Metadata) string {
 	return path.Join(anchoreNamespace, identifier)
 }

-func extractFromCatalog(catalog *pkg.Catalog) ([]model.Package, []model.File, []model.Relationship) {
+func toPackages(catalog *pkg.Catalog, relationships []artifact.Relationship) []model.Package {
 	packages := make([]model.Package, 0)
-	relationships := make([]model.Relationship, 0)
-	files := make([]model.File, 0)

 	for _, p := range catalog.Sorted() {
 		license := spdxhelpers.License(p)
-		packageSpdxID := model.ElementID(fmt.Sprintf("Package-%+v-%s-%s", p.Type, p.Name, p.Version)).String()
-
-		packageFiles, fileIDs, packageFileRelationships := spdxhelpers.Files(packageSpdxID, p)
-		files = append(files, packageFiles...)
-
-		relationships = append(relationships, packageFileRelationships...)
+		packageSpdxID := model.ElementID(p.ID()).String()

 		// note: the license concluded and declared should be the same since we are collecting license information
 		// from the project data itself (the installed package files).
@@ -97,14 +104,16 @@ func extractFromCatalog(catalog *pkg.Catalog) ([]model.Package, []model.File, []
 			DownloadLocation: spdxhelpers.DownloadLocation(p),
 			ExternalRefs:     spdxhelpers.ExternalRefs(p),
 			FilesAnalyzed:    false,
-			HasFiles:         fileIDs,
+			HasFiles:         fileIDsForPackage(packageSpdxID, relationships),
 			Homepage:         spdxhelpers.Homepage(p),
-			LicenseDeclared:  license, // The Declared License is what the authors of a project believe govern the package
-			Originator:       spdxhelpers.Originator(p),
-			SourceInfo:       spdxhelpers.SourceInfo(p),
-			VersionInfo:      p.Version,
+			// The Declared License is what the authors of a project believe govern the package
+			LicenseDeclared: license,
+			Originator:      spdxhelpers.Originator(p),
+			SourceInfo:      spdxhelpers.SourceInfo(p),
+			VersionInfo:     p.Version,
 			Item: model.Item{
-				LicenseConcluded: license, // The Concluded License field is the license the SPDX file creator believes governs the package
+				// The Concluded License field is the license the SPDX file creator believes governs the package
+				LicenseConcluded: license,
 				Element: model.Element{
 					SPDXID: packageSpdxID,
 					Name:   p.Name,
@@ -113,16 +122,145 @@ func extractFromCatalog(catalog *pkg.Catalog) ([]model.Package, []model.File, []
 		})
 	}

-	return packages, files, relationships
+	return packages
 }

-func cleanSPDXName(name string) string {
-	// remove # according to specification
-	name = strings.ReplaceAll(name, "#", "-")
+func fileIDsForPackage(packageSpdxID string, relationships []artifact.Relationship) (fileIDs []string) {
+	for _, relationship := range relationships {
+		if relationship.Type != artifact.ContainsRelationship {
+			continue
+		}

-	// remove : for url construction
-	name = strings.ReplaceAll(name, ":", "-")
+		if _, ok := relationship.From.(pkg.Package); !ok {
+			continue
+		}

-	// clean relative pathing
-	return path.Clean(name)
+		if _, ok := relationship.To.(source.Coordinates); !ok {
+			continue
+		}
+
+		if string(relationship.From.ID()) == packageSpdxID {
+			fileIDs = append(fileIDs, string(relationship.To.ID()))
+		}
+	}
+	return fileIDs
+}
+
+func toFiles(s sbom.SBOM) []model.File {
+	results := make([]model.File, 0)
+	artifacts := s.Artifacts
+
+	for _, coordinates := range sbom.AllCoordinates(s) {
+		var metadata *source.FileMetadata
+		if metadataForLocation, exists := artifacts.FileMetadata[coordinates]; exists {
+			metadata = &metadataForLocation
+		}
+
+		var digests []file.Digest
+		if digestsForLocation, exists := artifacts.FileDigests[coordinates]; exists {
+			digests = digestsForLocation
+		}
+
+		// TODO: add file classifications (?) and content as a snippet
+
+		var comment string
+		if coordinates.FileSystemID != "" {
+			comment = fmt.Sprintf("layerID: %s", coordinates.FileSystemID)
+		}
+
+		results = append(results, model.File{
+			Item: model.Item{
+				Element: model.Element{
+					SPDXID:  string(coordinates.ID()),
+					Name:    filepath.Base(coordinates.RealPath),
+					Comment: comment,
+				},
+				// required, no attempt made to determine license information
+				LicenseConcluded: "NOASSERTION",
+			},
+			Checksums: toFileChecksums(digests),
+			FileName:  coordinates.RealPath,
+			FileTypes: toFileTypes(metadata),
+		})
+	}
+
+	// sort by real path then virtual path to ensure the result is stable across multiple runs
+	sort.SliceStable(results, func(i, j int) bool {
+		return results[i].FileName < results[j].FileName
+	})
+	return results
+}
+
+func toFileChecksums(digests []file.Digest) (checksums []model.Checksum) {
+	for _, digest := range digests {
+		checksums = append(checksums, model.Checksum{
+			Algorithm:     digest.Algorithm,
+			ChecksumValue: digest.Value,
+		})
+	}
+	return checksums
+}
+
+func toFileTypes(metadata *source.FileMetadata) (ty []string) {
+	if metadata == nil {
+		return nil
+	}
+
+	mimeTypePrefix := strings.Split(metadata.MIMEType, "/")[0]
+	switch mimeTypePrefix {
+	case "image":
+		ty = append(ty, string(model.ImageFileType))
+	case "video":
+		ty = append(ty, string(model.VideoFileType))
+	case "application":
+		ty = append(ty, string(model.ApplicationFileType))
+	case "text":
+		ty = append(ty, string(model.TextFileType))
+	case "audio":
+		ty = append(ty, string(model.AudioFileType))
+	}
+
+	if internal.IsExecutable(metadata.MIMEType) {
+		ty = append(ty, string(model.BinaryFileType))
+	}
+
+	if internal.IsArchive(metadata.MIMEType) {
+		ty = append(ty, string(model.ArchiveFileType))
+	}
+
+	// TODO: add support for source, spdx, and documentation file types
+	if len(ty) == 0 {
+		ty = append(ty, string(model.OtherFileType))
+	}
+
+	return ty
+}
+
+func toRelationships(relationships []artifact.Relationship) (result []model.Relationship) {
+	for _, r := range relationships {
+		exists, relationshipType, comment := lookupRelationship(r.Type)
+
+		if !exists {
+			log.Warnf("unable to convert relationship from SPDX 2.2 JSON, dropping: %+v", r)
+			continue
+		}
+
+		result = append(result, model.Relationship{
+			SpdxElementID:      string(r.From.ID()),
+			RelationshipType:   relationshipType,
+			RelatedSpdxElement: string(r.To.ID()),
+			Comment:            comment,
+		})
+	}
+	return result
+}
+
+func lookupRelationship(ty artifact.RelationshipType) (bool, model.RelationshipType, string) {
+	switch ty {
+	case artifact.ContainsRelationship:
+		return true, model.ContainsRelationship, ""
+	case artifact.OwnershipByFileOverlapRelationship:
+		return true, model.OtherRelationship, fmt.Sprintf("%s: indicates that the parent package claims ownership of a child package since the parent metadata indicates overlap with a location that a cataloger found the child package by", ty)
+	}
+	return false, "", ""
 }
@@ -0,0 +1,256 @@
+package spdx22json
+
+import (
+	"testing"
+
+	"github.com/anchore/syft/syft/pkg"
+
+	"github.com/anchore/syft/syft/file"
+
+	"github.com/anchore/syft/syft/artifact"
+
+	"github.com/anchore/syft/internal/formats/spdx22json/model"
+	"github.com/anchore/syft/syft/source"
+	"github.com/stretchr/testify/assert"
+)
+
+func Test_toFileTypes(t *testing.T) {
+
+	tests := []struct {
+		name     string
+		metadata source.FileMetadata
+		expected []string
+	}{
+		{
+			name: "application",
+			metadata: source.FileMetadata{
+				MIMEType: "application/vnd.unknown",
+			},
+			expected: []string{
+				string(model.ApplicationFileType),
+			},
+		},
+		{
+			name: "archive",
+			metadata: source.FileMetadata{
+				MIMEType: "application/zip",
+			},
+			expected: []string{
+				string(model.ApplicationFileType),
+				string(model.ArchiveFileType),
+			},
+		},
+		{
+			name: "audio",
+			metadata: source.FileMetadata{
+				MIMEType: "audio/ogg",
+			},
+			expected: []string{
+				string(model.AudioFileType),
+			},
+		},
+		{
+			name: "video",
+			metadata: source.FileMetadata{
+				MIMEType: "video/3gpp",
+			},
+			expected: []string{
+				string(model.VideoFileType),
+			},
+		},
+		{
+			name: "text",
+			metadata: source.FileMetadata{
+				MIMEType: "text/html",
+			},
+			expected: []string{
+				string(model.TextFileType),
+			},
+		},
+		{
+			name: "image",
+			metadata: source.FileMetadata{
+				MIMEType: "image/png",
+			},
+			expected: []string{
+				string(model.ImageFileType),
+			},
+		},
+		{
+			name: "binary",
+			metadata: source.FileMetadata{
+				MIMEType: "application/x-sharedlib",
+			},
+			expected: []string{
+				string(model.ApplicationFileType),
+				string(model.BinaryFileType),
+			},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			assert.ElementsMatch(t, test.expected, toFileTypes(&test.metadata))
+		})
+	}
+}
+
+func Test_lookupRelationship(t *testing.T) {
+
+	tests := []struct {
+		input   artifact.RelationshipType
+		exists  bool
+		ty      model.RelationshipType
+		comment string
+	}{
+		{
+			input:  artifact.ContainsRelationship,
+			exists: true,
+			ty:     model.ContainsRelationship,
+		},
+		{
+			input:   artifact.OwnershipByFileOverlapRelationship,
+			exists:  true,
+			ty:      model.OtherRelationship,
+			comment: "ownership-by-file-overlap: indicates that the parent package claims ownership of a child package since the parent metadata indicates overlap with a location that a cataloger found the child package by",
+		},
+		{
+			input:  "made-up",
+			exists: false,
+		},
+	}
+	for _, test := range tests {
+		t.Run(string(test.input), func(t *testing.T) {
+			exists, ty, comment := lookupRelationship(test.input)
+			assert.Equal(t, exists, test.exists)
+			assert.Equal(t, ty, test.ty)
+			assert.Equal(t, comment, test.comment)
+		})
+	}
+}
+
+func Test_toFileChecksums(t *testing.T) {
+	tests := []struct {
+		name     string
+		digests  []file.Digest
+		expected []model.Checksum
+	}{
+		{
+			name: "empty",
+		},
+		{
+			name: "has digests",
+			digests: []file.Digest{
+				{
+					Algorithm: "sha256",
+					Value:     "deadbeefcafe",
+				},
+				{
+					Algorithm: "md5",
+					Value:     "meh",
+				},
+			},
+			expected: []model.Checksum{
+				{
+					Algorithm:     "sha256",
+					ChecksumValue: "deadbeefcafe",
+				},
+				{
+					Algorithm:     "md5",
+					ChecksumValue: "meh",
+				},
+			},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			assert.ElementsMatch(t, test.expected, toFileChecksums(test.digests))
+		})
+	}
+}
+
+func Test_fileIDsForPackage(t *testing.T) {
+
+	p := pkg.Package{
+		Name: "bogus",
+	}
+
+	c := source.Coordinates{
+		RealPath:     "/path",
+		FileSystemID: "nowhere",
+	}
+
+	tests := []struct {
+		name          string
+		id            string
+		relationships []artifact.Relationship
+		expected      []string
+	}{
+		{
+			name: "find file IDs for packages with package-file relationships",
+			id:   string(p.ID()),
+			relationships: []artifact.Relationship{
+				{
+					From: p,
+					To:   c,
+					Type: artifact.ContainsRelationship,
+				},
+			},
+			expected: []string{
+				string(c.ID()),
+			},
+		},
+		{
+			name: "ignore package-to-package",
+			id:   string(p.ID()),
+			relationships: []artifact.Relationship{
+				{
+					From: p,
+					To:   p,
+					Type: artifact.ContainsRelationship,
+				},
+			},
+			expected: []string{},
+		},
+		{
+			name: "ignore file-to-file",
+			id:   string(p.ID()),
+			relationships: []artifact.Relationship{
+				{
+					From: c,
+					To:   c,
+					Type: artifact.ContainsRelationship,
+				},
+			},
+			expected: []string{},
+		},
+		{
+			name: "ignore file-to-package",
+			id:   string(p.ID()),
+			relationships: []artifact.Relationship{
+				{
+					From: c,
+					To:   p,
+					Type: artifact.ContainsRelationship,
+				},
+			},
+			expected: []string{},
+		},
+		{
+			name: "filter by relationship type",
+			id:   string(p.ID()),
+			relationships: []artifact.Relationship{
+				{
+					From: p,
+					To:   c,
+					Type: artifact.OwnershipByFileOverlapRelationship,
+				},
+			},
+			expected: []string{},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			assert.ElementsMatch(t, test.expected, fileIDsForPackage(test.id, test.relationships))
+		})
+	}
+}