Skip to content

Commit

Permalink
Add SBOM Discovery with Rekor (#1157)
Browse files Browse the repository at this point in the history
This PR adds the ability to discover build-time SBOMs from binaries with the Rekor transparency log.
It does this by creating external document references for them in SPDX JSON.

Explained in more detail in syft issue #1159

Signed-off-by: Christopher Phillips <christopher.phillips@anchore.com>
  • Loading branch information
mdeicas authored and spiffcs committed Oct 25, 2022
1 parent 6826d76 commit 6d87b7f
Show file tree
Hide file tree
Showing 40 changed files with 41,019 additions and 15 deletions.
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,7 @@ registry:yourrepo/yourimage:tag pull image directly from a registry (no

#### Non Default:
- cargo-auditable-binary
- rekor

### Excluding file paths

Expand Down Expand Up @@ -644,3 +645,12 @@ The following checks were performed on each of these signatures:
```

Consumers of your image can now trust that the SBOM associated with your image is correct and from a trusted source.

## Discovery of SBOMs on Rekor (experimental)
Syft can search the Rekor transparency log for SBOM attestations of binaries it finds while scanning and incorporate the results into the SBOMs it produces. This allows the use of SBOMs produced at build time (such as by a trusted builder), to augment binary metadata in the resultant SBOM.

The rekor-cataloger searches Rekor by hash for binaries and performs verification to ensure that the SBOMs and attestations have not been tampered with. It verifies the log entry has been signed by Rekor's public key, the certificate associated with the log entry chains back to the Fulcio root certificate, the log entry timestamp lies in the period of validity of the certificate, and other verifications. In the SBOM that Syft produces, the information is represented as an external document reference containing the URI and hash of the SBOM.

This is an experimental feature. It uses external sources, a functionality that is new to Syft. The use of trusted builders to produce SBOMs has not yet been fully established, and more consideration of what external sources to trust is necessary. Currently, Syft accepts any SBOM attestation that has a valid certificate issued by Fulcio.

To enable the rekor-cataloger, use the flag ``` --catalogers rekor ```.
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ require (
github.com/anchore/go-logger v0.0.0-20220728155337-03b66a5207d8
github.com/anchore/stereoscope v0.0.0-20221006201143-d24c9d626b33
github.com/docker/docker v20.10.17+incompatible
github.com/go-openapi/runtime v0.24.2
github.com/google/go-containerregistry v0.11.0
github.com/in-toto/in-toto-golang v0.4.1-0.20221018183522-731d0640b65f
github.com/knqyf263/go-rpmdb v0.0.0-20220629110411-9a3bd2ebb923
Expand Down Expand Up @@ -152,7 +153,6 @@ require (
github.com/go-openapi/jsonpointer v0.19.5 // indirect
github.com/go-openapi/jsonreference v0.20.0 // indirect
github.com/go-openapi/loads v0.21.2 // indirect
github.com/go-openapi/runtime v0.24.2 // indirect
github.com/go-openapi/spec v0.20.7 // indirect
github.com/go-openapi/strfmt v0.21.3 // indirect
github.com/go-openapi/swag v0.22.3 // indirect
Expand Down
3 changes: 3 additions & 0 deletions syft/artifact/relationship.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,9 @@ const (

// DependencyOfRelationship is a proxy for the SPDX 2.2.1 DEPENDENCY_OF relationship.
DependencyOfRelationship RelationshipType = "dependency-of"

// DescribedByRelationship is a proxy for the SPDX 2.2.1 DESCRIBED_BY relationship.
DescribedByRelationship RelationshipType = "described-by"
)

type RelationshipType string
Expand Down
12 changes: 12 additions & 0 deletions syft/formats/spdx22json/model/doc_element_id.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
package model

import "github.com/anchore/syft/syft/formats/common/spdxhelpers"

// DocElementID represents the identifier string portion of an SPDX document
// identifier. It should be to used to reference any other SPDX document.
// DocElementIDs should NOT contain the 'DOCUMENTREF-' portion.
type DocElementID string

func (d DocElementID) String() string {
return "DocumentRef-" + spdxhelpers.SanitizeElementID(string(d))
}
2 changes: 1 addition & 1 deletion syft/formats/spdx22json/model/external_document_ref.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,6 @@ type ExternalDocumentRef struct {
// externalDocumentId is a string containing letters, numbers, ., - and/or + which uniquely identifies an external document within this document.
ExternalDocumentID string `json:"externalDocumentId"`
Checksum Checksum `json:"checksum"`
// SPDX ID for SpdxDocument. A propoerty containing an SPDX document.
// SPDX ID for SpdxDocument. A property containing an SPDX document.
SpdxDocument string `json:"spdxDocument"`
}
86 changes: 73 additions & 13 deletions syft/formats/spdx22json/to_format_model.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package spdx22json

import (
"errors"
"fmt"
"sort"
"strings"
Expand All @@ -15,6 +16,7 @@ import (
"github.com/anchore/syft/syft/formats/common/util"
"github.com/anchore/syft/syft/formats/spdx22json/model"
"github.com/anchore/syft/syft/pkg"
"github.com/anchore/syft/syft/rekor"
"github.com/anchore/syft/syft/sbom"
"github.com/anchore/syft/syft/source"
)
Expand All @@ -40,14 +42,55 @@ func toFormatModel(s sbom.SBOM) *model.Document {
},
LicenseListVersion: spdxlicense.Version,
},
DataLicense: "CC0-1.0",
DocumentNamespace: namespace,
Packages: toPackages(s.Artifacts.PackageCatalog, relationships),
Files: toFiles(s),
Relationships: toRelationships(relationships),
DataLicense: "CC0-1.0",
ExternalDocumentRefs: toExternalDocumentRefs(s.Relationships),
DocumentNamespace: namespace,
Packages: toPackages(s.Artifacts.PackageCatalog, relationships),
Files: toFiles(s),
Relationships: toRelationships(relationships),
}
}

// isValidExternalRelationshipDocument returns if rel contains an ExternalRef and if it to_format_model know how to handle it.
// An error is returned if rel contains an ExternalRef, but the rel cannot be handled
func isValidExternalRelationshipDocument(rel artifact.Relationship) (bool, error) {
if _, ok := rel.From.(rekor.ExternalRef); ok {
return false, errors.New("syft cannot handle an ExternalRef in the FROM field of a relationship")
}
if externalRef, ok := rel.To.(rekor.ExternalRef); ok {
relationshipType := artifact.DescribedByRelationship
if rel.Type == relationshipType && toChecksumAlgorithm(externalRef.SpdxRef.Alg) == "SHA1" {
return true, nil
}
return false, fmt.Errorf("syft cannot handle an ExternalRef with relationship type: %v", relationshipType)
}
return false, nil
}

func toExternalDocumentRefs(relationships []artifact.Relationship) []model.ExternalDocumentRef {
externalDocRefs := []model.ExternalDocumentRef{}
for _, rel := range relationships {
valid, err := isValidExternalRelationshipDocument(rel)
if err != nil {
log.Warnf("dropping relationship %v: %w", rel, err)
continue
}
if valid {
externalRef := rel.To.(rekor.ExternalRef)
externalDocRef := model.ExternalDocumentRef{
ExternalDocumentID: model.DocElementID(rel.To.ID()).String(),
Checksum: model.Checksum{
Algorithm: toChecksumAlgorithm(externalRef.SpdxRef.Alg),
ChecksumValue: externalRef.SpdxRef.Checksum,
},
SpdxDocument: externalRef.SpdxRef.URI,
}
externalDocRefs = append(externalDocRefs, externalDocRef)
}
}
return externalDocRefs
}

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

Expand Down Expand Up @@ -238,21 +281,34 @@ func toFileTypes(metadata *source.FileMetadata) (ty []string) {
return ty
}

func toRelationships(relationships []artifact.Relationship) (result []model.Relationship) {
func toRelationships(relationships []artifact.Relationship) []model.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: model.ElementID(r.From.ID()).String(),
RelationshipType: relationshipType,
RelatedSpdxElement: model.ElementID(r.To.ID()).String(),
Comment: comment,
})
rel := model.Relationship{
SpdxElementID: model.ElementID(r.From.ID()).String(),
RelationshipType: relationshipType,
Comment: comment,
}

// if this relationship contains an external document ref, we need to use DocElementID instead of ElementID
valid, err := isValidExternalRelationshipDocument(r)
if err != nil {
log.Warnf("dropping relationship %v: %w", rel, err)
continue
}
if valid {
rel.RelatedSpdxElement = model.DocElementID(r.To.ID()).String()
} else {
rel.RelatedSpdxElement = model.ElementID(r.To.ID()).String()
}

result = append(result, rel)
}
return result
}
Expand All @@ -263,6 +319,10 @@ func lookupRelationship(ty artifact.RelationshipType) (bool, spdxhelpers.Relatio
return true, spdxhelpers.ContainsRelationship, ""
case artifact.OwnershipByFileOverlapRelationship:
return true, spdxhelpers.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)
case artifact.DependencyOfRelationship:
return true, spdxhelpers.DependencyOfRelationship, ""
case artifact.DescribedByRelationship:
return true, spdxhelpers.DescribedByRelationship, ""
}
return false, "", ""
}
Loading

0 comments on commit 6d87b7f

Please sign in to comment.