diff --git a/AGENTS.md b/AGENTS.md index 6bce812..ad95143 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -246,7 +246,11 @@ imports only `purlkit`, `spdxkit`, the standard library, and the two format libraries whose vocabularies it cites by constant (cyclonedx-go, spdx/tools-golang); `httpkit` is a leaf that `plugin` reaches for `HostContext`; `scan` imports `model`, `plugin` and `graphview`, and nothing -imports `scan`. Nothing imports upward. The +imports `scan`. Nothing imports upward. `sbom` is the only importer of +`spdx/tools-golang/spdx/v3`: the SPDX 3 reader panics on some untrusted +graphs and the converter and serializer are nondeterministic, and +`sbom/spdx3*.go` is where both are contained (`repo_guards_test.go` +enforces it). The module root holds `doc.go` (the map) and `repo_guards_test.go` (the import boundary and the single-guidance-file rule, both keyed on the root directory) and nothing else; do not add code there. diff --git a/README.md b/README.md index eab09ca..03aeb02 100644 --- a/README.md +++ b/README.md @@ -160,7 +160,7 @@ an SBOM cannot say. ## The SBOM codec -- `sbom` — the SBOM codec: projects a graph into SPDX 2.3 or CycloneDX JSON and reads such a document back into a graph, with the document model, the strict ingest preflight, and the assertions a document carries about itself. +- `sbom` — the SBOM codec: projects a graph into SPDX 2.3, SPDX 3.0 (JSON-LD) or CycloneDX JSON and reads such a document back into a graph, with the document model, the strict ingest preflight, and the assertions a document carries about itself. - `graphview` — what a document may say about a node: the package URL it publishes, which of its children a document can name, and which nodes count as top-level parents. Both come from the CLI's `internal/sbom` and `internal/graphview` diff --git a/go.mod b/go.mod index bacb702..5f0a8db 100644 --- a/go.mod +++ b/go.mod @@ -19,11 +19,14 @@ require ( github.com/aquasecurity/go-version v0.0.1 // indirect github.com/fatih/color v1.13.0 // indirect github.com/golang/protobuf v1.5.4 // indirect + github.com/google/uuid v1.6.0 // indirect github.com/hashicorp/go-hclog v1.6.3 // indirect github.com/hashicorp/yamux v0.1.2 // indirect github.com/mattn/go-colorable v0.1.12 // indirect github.com/mattn/go-isatty v0.0.17 // indirect github.com/oklog/run v1.1.0 // indirect + github.com/piprate/json-gold v0.7.0 // indirect + github.com/pquerna/cachecontrol v0.0.0-20180517163645-1555304b9b35 // indirect go.uber.org/multierr v1.10.0 // indirect golang.org/x/sys v0.49.0 // indirect golang.org/x/text v0.43.0 // indirect diff --git a/go.sum b/go.sum index 3a11633..7d83520 100644 --- a/go.sum +++ b/go.sum @@ -19,6 +19,8 @@ github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps= github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= +github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/hashicorp/go-hclog v1.6.3 h1:Qr2kF+eVWjTiYmU7Y31tYlP1h0q/X3Nl3tPGdaB11/k= github.com/hashicorp/go-hclog v1.6.3/go.mod h1:W4Qnvbt70Wk/zYJryRzDRU/4r0kIg0PVHBcfoyhpF5M= github.com/hashicorp/go-plugin v1.8.0 h1:ie8S6RRY8RvB2usYZv+AAZ/wBvx2AU5p5QeP5j/FORs= @@ -38,8 +40,12 @@ github.com/oklog/run v1.1.0 h1:GEenZ1cK0+q0+wsJew9qUg/DyD8k3JzYsZAi5gYi2mA= github.com/oklog/run v1.1.0/go.mod h1:sVPdnTZT1zYwAJeCMu2Th4T21pA3FPOQRfWjQlk7DVU= github.com/package-url/packageurl-go v0.1.7 h1:iFWg6tzAjLA6F/qX3M5nZaiMHJgc+p2zxVyr/fY+sZY= github.com/package-url/packageurl-go v0.1.7/go.mod h1:nKAWB8E6uk1MHqiS/lQb9pYBGH2+mdJ2PJc2s50dQY0= +github.com/piprate/json-gold v0.7.0 h1:bEMirgA5y8Z2loTQfxyIFfY+EflxH1CTP6r/KIlcJNw= +github.com/piprate/json-gold v0.7.0/go.mod h1:RVhE35veDX19r5gfUAR+IYHkAUuPwJO8Ie/qVeFaIzw= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/pquerna/cachecontrol v0.0.0-20180517163645-1555304b9b35 h1:J9b7z+QKAmPf4YLrFg6oQUotqHQeUNWwkvo7jZp1GLU= +github.com/pquerna/cachecontrol v0.0.0-20180517163645-1555304b9b35/go.mod h1:prYjPmNq4d1NPVmpShWobRqXY3q7Vp+80DqgxxUrUIA= github.com/spdx/tools-golang v0.6.0-rc4 h1:2GkvNr0DcnJHY9BDm3OYHo229jZS/h4qYDK+tHYXPOo= github.com/spdx/tools-golang v0.6.0-rc4/go.mod h1:ruCHu3shgy7bVbZ7gtEU4Gq4fI08n2SdXtgV5PoN/OM= github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= diff --git a/repo_guards_test.go b/repo_guards_test.go index fe39abe..7e49226 100644 --- a/repo_guards_test.go +++ b/repo_guards_test.go @@ -45,6 +45,18 @@ var boundedImports = []struct { kitDir: "spdxkit", allowed: map[string]string{}, }, + { + // The SPDX 3 model, its JSON-LD reader and its 2.3 converter. The + // reader panics on some untrusted graphs, the converter and the + // serializer are nondeterministic, and the library's shared license + // values are mutated by its serializer: sbom/spdx3*.go contains all + // of that, so no other package may reach the library directly. + // The 2.3 package stays importable from model, which cites its + // vocabulary by constant. + module: "github.com/spdx/tools-golang/spdx/v3", + kitDir: "sbom", + allowed: map[string]string{}, + }, { module: "encoding/json/v2", kitDir: "sbom", diff --git a/sbom/codec.go b/sbom/codec.go index 6b2dd99..89eebe9 100644 --- a/sbom/codec.go +++ b/sbom/codec.go @@ -60,6 +60,7 @@ type codec interface { var codecs = map[Target]codec{ TargetSPDX23JSON: spdx23Codec{}, + TargetSPDX30JSON: spdx30Codec{}, TargetCycloneDX14JSON: cycloneDXCodec{version: TargetCycloneDX14JSON}, TargetCycloneDX15JSON: cycloneDXCodec{version: TargetCycloneDX15JSON}, TargetCycloneDX16JSON: cycloneDXCodec{version: TargetCycloneDX16JSON}, @@ -200,6 +201,10 @@ func DetectJSONTarget(data []byte) (Target, error) { Schema struct { URL string `json:"url"` } `json:"schema"` + // Raw, so a document whose @context or @graph has an unexpected + // shape is an unsupported format rather than malformed JSON. + Context json.RawMessage `json:"@context"` + Graph json.RawMessage `json:"@graph"` } if err := json.Unmarshal(trimmed, &sniff); err != nil { return "", ErrMalformedJSON @@ -212,6 +217,8 @@ func DetectJSONTarget(data []byte) (Target, error) { switch { case sniff.SPDXVersion == "SPDX-2.3": return TargetSPDX23JSON, nil + case spdx3ContextNamed(sniff.Context) && nonEmptyJSONArray(sniff.Graph): + return TargetSPDX30JSON, nil case sniff.BOMFormat == "CycloneDX": switch sniff.SpecVersion { case "1.4": @@ -229,6 +236,43 @@ func DetectJSONTarget(data []byte) (Target, error) { return "", ErrUnsupportedFormat } +// spdx3ContextMarker is what makes a JSON-LD document an SPDX 3.0 one: the +// specification publishes its JSON-LD context under +// https://spdx.org/rdf/3.0./spdx-context.jsonld (3.0.1 today), and a +// document names it in @context, as a string or as one entry of a list. SPDX +// 3 has no other discriminator -- no version member like 2.3's spdxVersion -- +// so the context is the format's own declaration of what it is. Which patch +// release is readable is the library's decision: its reader resolves the +// context offline and refuses one it does not carry. +const spdx3ContextMarker = "spdx.org/rdf/3.0." + +// spdx3ContextNamed reports whether a JSON-LD @context names an SPDX 3.0 +// context. +func spdx3ContextNamed(raw json.RawMessage) bool { + if len(raw) == 0 { + return false + } + var single string + if json.Unmarshal(raw, &single) == nil { + return strings.Contains(single, spdx3ContextMarker) + } + var list []json.RawMessage + if json.Unmarshal(raw, &list) != nil { + return false + } + for _, entry := range list { + if json.Unmarshal(entry, &single) == nil && strings.Contains(single, spdx3ContextMarker) { + return true + } + } + return false +} + +func nonEmptyJSONArray(raw json.RawMessage) bool { + var list []json.RawMessage + return json.Unmarshal(raw, &list) == nil && len(list) > 0 +} + // UnmarshalAutoJSON parses a supported SBOM JSON payload without requiring the caller to preselect a target. func UnmarshalAutoJSON(data []byte) (*Document, Target, error) { // Before sniffing, not after. The format is read out of the document, so diff --git a/sbom/codec_fuzz_test.go b/sbom/codec_fuzz_test.go index a0c72ba..3ef95d4 100644 --- a/sbom/codec_fuzz_test.go +++ b/sbom/codec_fuzz_test.go @@ -26,6 +26,17 @@ func FuzzUnmarshalAutoJSON(f *testing.F) { `{"spdxVersion":"SPDX-2.3","SPDXID":"SPDXRef-DOCUMENT","name":"demo","documentNamespace":"https://example.com/spdx/demo","externalDocumentRefs":[{"externalDocumentId":"DocumentRef-a","spdxDocument":"../../etc/passwd","checksum":{"algorithm":"NOPE","checksumValue":""}}],"packages":[]}`, `{"bomFormat":"CycloneDX","specVersion":"1.6","version":1,"serialNumber":"urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79","externalReferences":[{"type":"bom","url":"urn:cdx:3e671687-395b-41f5-a30f-a58921a69b79/2","hashes":[{"alg":"SHA-256","content":"0000000000000000000000000000000000000000000000000000000000000000"}]}],"components":[]}`, `{"bomFormat":"CycloneDX","specVersion":"1.6","version":1,"externalReferences":[{"type":"bom","url":"file:///etc/passwd"}],"components":[{"bom-ref":"a","name":"a","version":"1","purl":"pkg:npm/a@1","scope":"optional","properties":[{"name":"bomly:scopes","value":"runtime,future"}]}]}`, + // SPDX 3.0 JSON-LD: a minimal document, one naming a listed license + // by its License List IRI (which ingest defines before the library + // reads it), one whose context is a list, one with no SpdxDocument, + // and the vocabulary-as-element shape that panicked the library's + // reader. + `{"@context":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld","@graph":[{"type":"CreationInfo","@id":"_:c","specVersion":"3.0.1","created":"2026-01-01T00:00:00Z","createdBy":["https://example.com/a"]},{"type":"Organization","spdxId":"https://example.com/a","name":"a","creationInfo":"_:c"},{"type":"SpdxDocument","spdxId":"https://example.com/d","creationInfo":"_:c","rootElement":["https://example.com/p"]},{"type":"software_Package","spdxId":"https://example.com/p","name":"p","software_packageVersion":"1","software_packageUrl":"pkg:npm/p@1","creationInfo":"_:c"}]}`, + `{"@context":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld","@graph":[{"type":"CreationInfo","@id":"_:c","specVersion":"3.0.1","created":"2026-01-01T00:00:00Z","createdBy":[]},{"type":"SpdxDocument","spdxId":"https://example.com/d","creationInfo":"_:c"},{"type":"software_Package","spdxId":"https://example.com/p","name":"p","creationInfo":"_:c"},{"type":"Relationship","spdxId":"https://example.com/r","from":"https://example.com/p","to":["https://spdx.org/licenses/MIT"],"relationshipType":"hasDeclaredLicense","creationInfo":"_:c"}]}`, + `{"@context":["https://spdx.org/rdf/3.0.1/spdx-context.jsonld"],"@graph":[{"type":"SpdxDocument","spdxId":"https://example.com/d"}]}`, + `{"@context":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld","@graph":[{"type":"software_Package","spdxId":"https://example.com/p","name":"p"}]}`, + `{"@context":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld","@graph":[{"type":"SpdxDocument","spdxId":"https://example.com/d"},{"type":"software_Package","spdxId":"https://example.com/p","verifiedUsing":[{"type":"Hash","algorithm":"https://example.com/h","hashValue":"00"}]},{"type":"HashAlgorithm","spdxId":"https://example.com/h"}]}`, + `{"@context":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld","@graph":[{"type":"SpdxDocument","spdxId":"https://exa`, // Malformed inputs: rejection paths must be deterministic, never panic. ``, `{}`, diff --git a/sbom/doc.go b/sbom/doc.go index 64f0991..41f5862 100644 --- a/sbom/doc.go +++ b/sbom/doc.go @@ -1,8 +1,9 @@ // Package sbom is the SBOM codec: it projects a dependency graph into an -// SPDX 2.3 or CycloneDX document and reads such a document back into a graph. +// SPDX 2.3, SPDX 3.0 or CycloneDX document and reads such a document back +// into a graph. // // It owns the document model (Document, Component, Dependency and the -// assertions they carry), the two format codecs, the strict preflight that +// assertions they carry), the format codecs, the strict preflight that // refuses a document without one unambiguous reading (bomly-cli ADR-0026), // and the projection in both directions: FromDepGraph and FromGraphEntries // build a Document from a graph, ToGraph builds a graph from a Document, and diff --git a/sbom/document_assertions_test.go b/sbom/document_assertions_test.go index 74de390..b3eb82b 100644 --- a/sbom/document_assertions_test.go +++ b/sbom/document_assertions_test.go @@ -137,7 +137,7 @@ func TestDocumentClaimsSurviveTheGraphHop(t *testing.T) { // byte difference. Pinning them would have made this test pass over exactly // the defects it exists to catch. func TestSingleSourceExportIsAFixedPoint(t *testing.T) { - for _, target := range []Target{TargetSPDX23JSON, TargetCycloneDX16JSON} { + for _, target := range []Target{TargetSPDX23JSON, TargetSPDX30JSON, TargetCycloneDX16JSON} { t.Run(string(target), func(t *testing.T) { opts := BuildOptions{ToolVersion: "0.0.0-test", RestatesSource: true} diff --git a/sbom/document_sources_test.go b/sbom/document_sources_test.go index a33d4ba..87aefe5 100644 --- a/sbom/document_sources_test.go +++ b/sbom/document_sources_test.go @@ -176,7 +176,7 @@ func TestSourceLinkChecksumCoversTheSourceBytes(t *testing.T) { // be built from nothing (bomly-dev/bomly-sdk#61). Provenance now survives more // than one hop, which is the SDK's declared merge class for the source set. func TestMergedSourceLinksSurviveASecondConversion(t *testing.T) { - for _, target := range []Target{TargetSPDX23JSON, TargetCycloneDX16JSON} { + for _, target := range []Target{TargetSPDX23JSON, TargetSPDX30JSON, TargetCycloneDX16JSON} { t.Run(string(target), func(t *testing.T) { first, _ := mergedExport(t, target, documentRichSPDX, serialCycloneDX) @@ -196,6 +196,10 @@ func TestMergedSourceLinksSurviveASecondConversion(t *testing.T) { for _, ref := range spdxExternalDocumentRefs(t, second) { named = append(named, ref.URI) } + case TargetSPDX30JSON: + for _, imported := range spdx3DocumentImports(t, second) { + named = append(named, imported.LocationHint) + } default: for _, ref := range cycloneDXSourceRefs(t, second) { named = append(named, ref.URL) @@ -245,7 +249,7 @@ func TestCycloneDXSourceLinksCarryTheirChecksum(t *testing.T) { // A native scan names no sources: there were none. func TestNativeExportNamesNoSources(t *testing.T) { g := scopedGraph(t, model.ScopeRuntime) - for _, target := range []Target{TargetSPDX23JSON, TargetCycloneDX16JSON} { + for _, target := range []Target{TargetSPDX23JSON, TargetSPDX30JSON, TargetCycloneDX16JSON} { t.Run(string(target), func(t *testing.T) { raw, err := MarshalDepGraphJSON(g, target, BuildOptions{Created: fixedExportTime()}, EncodeOptions{Pretty: true}) if err != nil { @@ -256,6 +260,10 @@ func TestNativeExportNamesNoSources(t *testing.T) { if refs := spdxExternalDocumentRefs(t, raw); len(refs) != 0 { t.Errorf("externalDocumentRefs = %+v, want none", refs) } + case TargetSPDX30JSON: + if imports := spdx3DocumentImports(t, raw); len(imports) != 0 { + t.Errorf("imports = %+v, want none", imports) + } default: if refs := cycloneDXSourceRefs(t, raw); len(refs) != 0 { t.Errorf("bom references = %+v, want none", refs) diff --git a/sbom/eol_round_trip_test.go b/sbom/eol_round_trip_test.go index 6fa9ea2..7d83230 100644 --- a/sbom/eol_round_trip_test.go +++ b/sbom/eol_round_trip_test.go @@ -10,7 +10,7 @@ import ( // defect 4). Each format keeps exactly what it can write: SPDX has no cycle // field in its package comment, CycloneDX does. func TestEOLSurvivesADocumentRoundTrip(t *testing.T) { - for _, target := range []Target{TargetSPDX23JSON, TargetCycloneDX16JSON} { + for _, target := range []Target{TargetSPDX23JSON, TargetSPDX30JSON, TargetCycloneDX16JSON} { t.Run(string(target), func(t *testing.T) { doc := &Document{ Name: "eol", diff --git a/sbom/model.go b/sbom/model.go index 9756fd3..bf6ed16 100644 --- a/sbom/model.go +++ b/sbom/model.go @@ -12,6 +12,7 @@ type Target string const ( TargetSPDX23JSON Target = "spdx-2.3+json" + TargetSPDX30JSON Target = "spdx-3.0+json" TargetCycloneDX14JSON Target = "cyclonedx-1.4+json" TargetCycloneDX15JSON Target = "cyclonedx-1.5+json" TargetCycloneDX16JSON Target = "cyclonedx-1.6+json" diff --git a/sbom/origin_test.go b/sbom/origin_test.go index b6d72e1..970e741 100644 --- a/sbom/origin_test.go +++ b/sbom/origin_test.go @@ -572,7 +572,7 @@ func TestExportKeepsEveryFoldedOrigin(t *testing.T) { t.Fatalf("graph holds %d dependency nodes; want the fixture's two", got) } - for _, target := range []Target{TargetCycloneDX16JSON, TargetSPDX23JSON} { + for _, target := range []Target{TargetCycloneDX16JSON, TargetSPDX23JSON, TargetSPDX30JSON} { out, err := MarshalDepGraphJSON(g, target, BuildOptions{}, EncodeOptions{}) if err != nil { t.Fatalf("marshal %v: %v", target, err) diff --git a/sbom/scope_round_trip_test.go b/sbom/scope_round_trip_test.go index b1f2138..fb7c3f0 100644 --- a/sbom/scope_round_trip_test.go +++ b/sbom/scope_round_trip_test.go @@ -36,7 +36,7 @@ func componentScopes(t *testing.T, doc *Document, name string) []model.Scope { // formats. Before this, export wrote the single merged precedence value and // the union PR #406 established stopped at the SBOM boundary. func TestScopeSetSurvivesTheExportBoundary(t *testing.T) { - for _, target := range []Target{TargetSPDX23JSON, TargetCycloneDX16JSON} { + for _, target := range []Target{TargetSPDX23JSON, TargetSPDX30JSON, TargetCycloneDX16JSON} { t.Run(string(target), func(t *testing.T) { g := scopedGraph(t, model.ScopeRuntime, model.ScopeDevelopment) raw, err := MarshalDepGraphJSON(g, target, BuildOptions{}, EncodeOptions{Pretty: true}) @@ -441,7 +441,7 @@ func TestUnknownScopeTokenKeepsTheKnownScopes(t *testing.T) { // A document Bomly wrote names no unknown tokens, so the warning stays quiet // on the ordinary path. func TestAKnownCarrierReportsNoUnknownTokens(t *testing.T) { - for _, target := range []Target{TargetSPDX23JSON, TargetCycloneDX16JSON} { + for _, target := range []Target{TargetSPDX23JSON, TargetSPDX30JSON, TargetCycloneDX16JSON} { t.Run(string(target), func(t *testing.T) { g := scopedGraph(t, model.ScopeRuntime, model.ScopeDevelopment) raw, err := MarshalDepGraphJSON(g, target, BuildOptions{}, EncodeOptions{Pretty: true}) diff --git a/sbom/spdx23.go b/sbom/spdx23.go index 5018111..ad9eb0d 100644 --- a/sbom/spdx23.go +++ b/sbom/spdx23.go @@ -18,6 +18,14 @@ import ( type spdx23Codec struct{} func (spdx23Codec) encodeJSON(doc *Document, opts EncodeOptions) ([]byte, error) { + return marshalJSON(buildSPDX23Document(doc), opts.Pretty) +} + +// buildSPDX23Document projects the intermediate document onto SPDX 2.3's +// model. It is shared with the SPDX 3 encoder, which converts this document +// with the specification library rather than projecting a second time, so +// the two SPDX encodings of one scan cannot disagree about what they say. +func buildSPDX23Document(doc *Document) *v23.Document { idByComponent := make(map[string]common.ElementID, len(doc.Components)) ids := newSPDXIDAllocator(len(doc.Components)) packages := make([]*v23.Package, 0, len(doc.Components)) @@ -133,8 +141,7 @@ func (spdx23Codec) encodeJSON(doc *Document, opts EncodeOptions) ([]byte, error) Relationships: relationships, OtherLicenses: spdxOtherLicenses(extractedLicenses), } - - return marshalJSON(spdxDoc, opts.Pretty) + return spdxDoc } func (spdx23Codec) decodeJSON(data []byte) (*Document, error) { @@ -142,7 +149,13 @@ func (spdx23Codec) decodeJSON(data []byte) (*Document, error) { if err := json.Unmarshal(data, &spdxDoc); err != nil { return nil, err } + return documentFromSPDX23(&spdxDoc), nil +} +// documentFromSPDX23 reads an SPDX 2.3 model into the intermediate document. +// It is shared with the SPDX 3 decoder, which lowers its document to this +// model first, so both SPDX versions are read by one set of rules. +func documentFromSPDX23(spdxDoc *v23.Document) *Document { extractedByRef := spdxExtractedTexts(spdxDoc.OtherLicenses) components := make([]Component, 0, len(spdxDoc.Packages)) @@ -225,7 +238,7 @@ func (spdx23Codec) decodeJSON(data []byte) (*Document, error) { return &Document{ Name: spdxDoc.DocumentName, Namespace: spdxDoc.DocumentNamespace, - Assertions: spdxDocumentAssertions(&spdxDoc), + Assertions: spdxDocumentAssertions(spdxDoc), Tool: extractSPDXToolName(spdxDoc.CreationInfo), Tools: extractSPDXToolNames(spdxDoc.CreationInfo), Created: parseSPDXCreated(spdxDoc.CreationInfo), @@ -236,7 +249,7 @@ func (spdx23Codec) decodeJSON(data []byte) (*Document, error) { Roots: roots, Described: roots, UnknownScopeTokens: unknownScopes, - }, nil + } } func sanitizeSPDXID(raw string) string { diff --git a/sbom/spdx3.go b/sbom/spdx3.go new file mode 100644 index 0000000..e88102b --- /dev/null +++ b/sbom/spdx3.go @@ -0,0 +1,659 @@ +package sbom + +import ( + "bytes" + "encoding/json" + "fmt" + "reflect" + "sort" + "strings" + + "github.com/spdx/tools-golang/spdx/v2/common" + v23 "github.com/spdx/tools-golang/spdx/v2/v2_3" + v30 "github.com/spdx/tools-golang/spdx/v3/v3_0" +) + +// spdx30Codec reads and writes SPDX 3.0.1 in its JSON-LD serialization. +// +// Delegation. The SPDX 3 vocabulary, object model, JSON-LD serialization and +// validation are spdx/tools-golang's (package spdx/v3/v3_0), which this module +// already pins for SPDX 2.3 and which Syft's own SPDX 3 encoder uses. Nothing +// here spells an SPDX 3 term: every relationship type, hash algorithm, +// reference type and purpose is one of the library's generated values, or is +// read back through one. +// +// Encoding projects the document onto SPDX 2.3 with the same builder the 2.3 +// codec uses, then converts it with the library's v3_0.From_v2_3. One +// projection, so the two SPDX encodings of one scan cannot disagree. +// +// Decoding has no library to delegate to: tools-golang converts 2.3 to 3.0 +// and not back, and no maintained Go library reads SPDX 3 into anything +// else. lowerSPDX3 is the inverse step, written here against the library's +// typed model, and it lowers to the SPDX 2.3 model so that one set of rules +// (documentFromSPDX23) reads both versions. Where the inverse needs a +// vocabulary mapping it derives it from the library's own forward converter +// (spdx3_vocabulary.go) rather than transcribing one. +// +// The pinned library is a release candidate, v0.6.0-rc4; there is no final +// v0.6.0 yet. It has four defects this codec works around, each pinned by a +// test that fails once the library changes, so recheck all four when v0.6.0 +// final ships: +// +// - From_v2_3 keys SHA3 and BLAKE2b checksums with underscores (SHA3_256) +// where SPDX 2.3 spells them with hyphens (SHA3-256), so those digests +// convert with an empty, required algorithm (prepareSPDX23ForConversion; +// TestSPDX3PublishesEveryDigestTheSDKPublishes). +// - From_v2_3 keeps only the reference types in its own small maps and +// drops every other external reference (carrySPDX3References). +// - From_v2_3 leaves createdBy empty when every 2.3 creator is a tool, +// which the library's own validation rejects (completeSPDX3CreatedBy). +// - Both the converter and the serializer build element lists from map +// iteration, so the output order and every minted identifier change from +// run to run (nameSPDX3Elements, canonicalSPDX3JSON; +// TestSPDX3EncodingIsDeterministic). +// +// The library's reader also panics on some malformed graphs, which is why +// both directions contain a panic at this boundary: license strings and +// whole documents here come from untrusted input. +type spdx30Codec struct{} + +func (spdx30Codec) encodeJSON(doc *Document, opts EncodeOptions) (out []byte, err error) { + defer func() { + if recovered := recover(); recovered != nil { + out, err = nil, fmt.Errorf("encode spdx 3: %v", recovered) + } + }() + + spdx23 := buildSPDX23Document(doc) + prepareSPDX23ForConversion(spdx23) + + var converted v30.Document + v30.From_v2_3(*spdx23, &converted) + if err := completeSPDX3Conversion(&converted, spdx23); err != nil { + return nil, err + } + // Validated before writing, because ToJSON writes an invalid document + // without complaint. preProcess runs the same fill-ins ToJSON performs. + if err := converted.Validate(true); err != nil { + return nil, fmt.Errorf("spdx 3 document failed validation: %w", err) + } + + var buf bytes.Buffer + if err := converted.ToJSON(&buf); err != nil { + return nil, fmt.Errorf("serialize spdx 3: %w", err) + } + return canonicalSPDX3JSON(buf.Bytes(), opts.Pretty) +} + +// prepareSPDX23ForConversion corrects the 2.3 projection where From_v2_3 +// would otherwise misread it. +// +// Checksum algorithms: the converter's lookup keys write SPDX 2.3's +// hyphenated names with underscores, so "SHA3-256" finds nothing and the hash +// is written with no algorithm. Rewriting the hyphen is the whole difference +// between the two spellings, so no table is involved, and an algorithm without +// a hyphen is untouched. +// +// Download location and home page: SPDX 2.3 requires downloadLocation and +// fills an unknown one with NOASSERTION. SPDX 3 makes both optional anyURI +// properties with no such sentinel -- an unknown location is an absent one -- +// so the sentinel is removed rather than published as a relative URI. +func prepareSPDX23ForConversion(doc *v23.Document) { + for _, pkg := range doc.Packages { + if pkg == nil { + continue + } + for i := range pkg.PackageChecksums { + pkg.PackageChecksums[i].Algorithm = spdx3ConverterChecksumKey(pkg.PackageChecksums[i].Algorithm) + } + if isSPDXSentinel(pkg.PackageDownloadLocation) { + pkg.PackageDownloadLocation = "" + } + if isSPDXSentinel(pkg.PackageHomePage) { + pkg.PackageHomePage = "" + } + } + for i := range doc.ExternalDocumentReferences { + ref := &doc.ExternalDocumentReferences[i] + ref.Checksum.Algorithm = spdx3ConverterChecksumKey(ref.Checksum.Algorithm) + } +} + +// spdx3ConverterChecksumKey spells a 2.3 checksum algorithm the way +// From_v2_3's lookup expects it. See prepareSPDX23ForConversion. +func spdx3ConverterChecksumKey(algorithm common.ChecksumAlgorithm) common.ChecksumAlgorithm { + return common.ChecksumAlgorithm(strings.ReplaceAll(string(algorithm), "-", "_")) +} + +func isSPDXSentinel(value string) bool { + value = strings.TrimSpace(value) + return strings.EqualFold(value, "NOASSERTION") || strings.EqualFold(value, "NONE") +} + +// completeSPDX3Conversion finishes what From_v2_3 leaves undone. +func completeSPDX3Conversion(d *v30.Document, spdx23 *v23.Document) error { + sbom := spdx3ConvertedSBOM(d) + if sbom == nil { + return fmt.Errorf("spdx 3 conversion produced no sbom element") + } + packages := make(map[string]*v30.Package, len(spdx23.Packages)) + for _, element := range sbom.Elements { + if pkg, ok := element.(*v30.Package); ok { + packages[pkg.ID] = pkg + } + } + for _, pkg := range spdx23.Packages { + if pkg == nil { + continue + } + if converted := packages[string(pkg.PackageSPDXIdentifier)]; converted != nil { + carrySPDX3References(converted, pkg.PackageExternalReferences) + // The converter leaves an empty list where it converted nothing, which + // serializes as an empty array; absent says the same thing. + if len(converted.ExternalIdentifiers) == 0 { + converted.ExternalIdentifiers = nil + } + } + } + completeSPDX3CreatedBy(d) + nameSPDX3Elements(d, sbom, spdx23) + return nil +} + +// spdx3ConvertedSBOM returns the software SBOM element From_v2_3 roots the +// document at. +func spdx3ConvertedSBOM(d *v30.Document) *v30.SBOM { + for _, root := range d.RootElements { + if sbom, ok := root.(*v30.SBOM); ok { + return sbom + } + } + return nil +} + +// carrySPDX3References writes the external references From_v2_3 dropped. +// +// The converter keeps a reference only when its type is in one of two small +// lookup tables (purl, CPE, swid, four package managers, three security +// types); everything else -- a source document's website or issue tracker, an +// origin beyond the first -- is discarded with no trace in the output. SPDX 3 +// has a home for each: +// +// - An origin beyond the primary is an alternative download location, the +// specification's own term for it. +// - Any other reference is an ExternalRef of type "other", the value SPDX 3 +// defines for a type outside its vocabulary. SPDX 3 has no free-text type +// field, so the 2.3 category and type it had ride in the comment, in the +// same "bomly:" carrier the package comment uses, ahead of any comment +// the reference had of its own. +// +// What the converter did carry is detected by locator rather than by +// re-deriving its tables, so a reference the library learns to convert stops +// being carried here without a change. +func carrySPDX3References(pkg *v30.Package, refs []*v23.PackageExternalReference) { + for _, ref := range refs { + if ref == nil { + continue + } + locator := strings.TrimSpace(ref.Locator) + if locator == "" || spdx3PackageCarriesLocator(pkg, locator) { + continue + } + if strings.EqualFold(strings.TrimSpace(ref.RefType), spdxOriginRefType) { + pkg.ExternalRefs = append(pkg.ExternalRefs, &v30.ExternalRef{ + Type: v30.ExternalRefType_AltDownloadLocation, + Locators: []string{locator}, + }) + continue + } + pkg.ExternalRefs = append(pkg.ExternalRefs, &v30.ExternalRef{ + Type: v30.ExternalRefType_Other, + Locators: []string{locator}, + Comment: spdx3ReferenceCarrier(ref.Category, ref.RefType, ref.ExternalRefComment), + }) + } +} + +func spdx3PackageCarriesLocator(pkg *v30.Package, locator string) bool { + if string(pkg.PackageURL) == locator { + return true + } + for _, identifier := range pkg.ExternalIdentifiers { + if identifier != nil && identifier.GetIdentifier() == locator { + return true + } + } + for _, ref := range pkg.ExternalRefs { + if ref == nil { + continue + } + for _, l := range ref.GetLocators() { + if l == locator { + return true + } + } + } + return false +} + +// spdx3ReferenceCarrierPrefix opens the comment of an "other" ExternalRef +// that carries an SPDX 2.3 category and type. The first line is the carrier; +// anything after it is the reference's own comment. +const spdx3ReferenceCarrierPrefix = "bomly:" + +func spdx3ReferenceCarrier(category, refType, comment string) string { + carrier := spdx3ReferenceCarrierPrefix + "category=" + strings.TrimSpace(category) + ";type=" + strings.TrimSpace(refType) + if comment = strings.TrimSpace(comment); comment != "" { + carrier += "\n" + comment + } + return carrier +} + +// parseSPDX3ReferenceCarrier reads a carrier written by spdx3ReferenceCarrier. +// ok is false for a comment that carries none, which is every comment a +// document Bomly did not write has. +func parseSPDX3ReferenceCarrier(comment string) (category, refType, rest string, ok bool) { + first, rest, _ := strings.Cut(comment, "\n") + if !strings.HasPrefix(strings.TrimSpace(first), spdx3ReferenceCarrierPrefix) { + return "", "", comment, false + } + category = parseSPDXCommentField(first, "category") + refType = parseSPDXCommentField(first, "type") + if category == "" || refType == "" { + return "", "", comment, false + } + return category, refType, strings.TrimSpace(rest), true +} + +// completeSPDX3CreatedBy names an agent when the conversion found none. +// +// SPDX 3 requires at least one createdBy agent, and From_v2_3 reads agents +// only from Person and Organization creators: a 2.3 document credited to a +// tool alone -- every Bomly scan without a configured manufacturer -- converts +// to a document the library's own validation rejects. The tool that produced +// the document is the agent that created it, and SPDX 3 has the class for +// that: SoftwareAgent. +// +// Only the producer. The 2.3 creators list the producing tool first +// (documentTools guarantees it) followed by the tools the source documents +// credited, and those contributed to this document without creating it; +// createdUsing keeps naming every one of them. +func completeSPDX3CreatedBy(d *v30.Document) { + info, ok := d.CreationInfo.(*v30.CreationInfo) + if !ok || info == nil || len(info.CreatedBy) > 0 { + return + } + for _, tool := range info.CreatedUsing { + if isNilElement(tool) || strings.TrimSpace(tool.GetName()) == "" { + continue + } + info.CreatedBy = append(info.CreatedBy, &v30.SoftwareAgent{ + Name: tool.GetName(), + CreationInfo: info, + }) + return + } +} + +// nameSPDX3Elements gives every element an identifier derived from what it +// is, and folds duplicate agents and listed licenses into one element each. +// +// From_v2_3 leaves most elements without an identifier and the serializer +// mints one per element in traversal order, which follows map iteration: +// the same scan written twice came out with different identifiers for the +// same relationships and licenses, so neither a diff nor a golden could +// compare two exports. The converter also builds a fresh agent per package +// for a shared supplier and a fresh license per occurrence of an identifier, +// so a dependency tree under one MIT-licensed vendor published that vendor and +// that license once per package. +// +// Names come from content -- a relationship from its subject and type, a +// listed license from its identifier -- and are allocated in the order of the +// 2.3 projection, which is deterministic, so the same document always names +// its elements the same way. Identifiers the conversion already set (packages, +// LicenseRef licenses, the specification's individual license values) are +// kept. +func nameSPDX3Elements(d *v30.Document, sbom *v30.SBOM, spdx23 *v23.Document) { + n := &spdx3Namer{ + ids: newSPDXIDAllocator(len(sbom.Elements)), + seen: make(map[any]struct{}, len(sbom.Elements)), + agents: make(map[string]v30.AnyAgent), + licenses: make(map[string]v30.AnyLicenseInfo), + } + // Identifiers the conversion set are reserved first, so a minted name can + // never collide with one. + for _, element := range sbom.Elements { + if element != nil && element.GetID() != "" && !strings.Contains(element.GetID(), ":") { + n.ids.assigned[element.GetID()] = struct{}{} + } + } + + n.name(sbom, "SBOM") + if info, ok := d.CreationInfo.(*v30.CreationInfo); ok && info != nil { + for i, agent := range info.CreatedBy { + info.CreatedBy[i] = n.agent(agent) + } + for _, tool := range info.CreatedUsing { + n.name(tool, "Tool-"+tool.GetName()) + } + } + d.DataLicense = n.license(d.DataLicense, "DataLicense") + + relationships := make(map[v30.AnyElement][]v30.AnyRelationship) + for _, element := range sbom.Elements { + if rel, ok := element.(v30.AnyRelationship); ok && rel != nil { + relationships[rel.GetFrom()] = append(relationships[rel.GetFrom()], rel) + } + } + byID := make(map[string]*v30.Package, len(sbom.Elements)) + for _, element := range sbom.Elements { + if pkg, ok := element.(*v30.Package); ok { + byID[pkg.ID] = pkg + } + } + for _, pkg23 := range spdx23.Packages { + if pkg23 == nil { + continue + } + pkg := byID[string(pkg23.PackageSPDXIdentifier)] + if pkg == nil { + continue + } + if !isNilElement(pkg.SuppliedBy) { + pkg.SuppliedBy = n.agent(pkg.SuppliedBy) + } + for i, agent := range pkg.OriginatedBy { + pkg.OriginatedBy[i] = n.agent(agent) + } + n.relationships(pkg.ID, relationships[pkg]) + delete(relationships, pkg) + } + // Anything left -- a relationship whose subject is not a package, which + // Bomly does not write today -- is named in a stable order too. + var rest []v30.AnyRelationship + for _, rels := range relationships { + rest = append(rest, rels...) + } + n.relationships("Element", rest) + + // The converter also lists every element it built in the SBOM's and the + // document's element lists, the library's shared license values among + // them, and ToJSON walks those lists too. Each list gets the + // per-document values license() handed out, so nothing reachable from + // this document is shared with another. + sbom.Elements = n.ownElements(sbom.Elements) + d.Elements = n.ownElements(d.Elements) +} + +func (n *spdx3Namer) ownElements(elements v30.ElementList) v30.ElementList { + for i, element := range elements { + if shared, ok := element.(*v30.IndividualLicensingInfo); ok && shared != nil { + if own, ok := n.license(shared, "").(v30.AnyElement); ok { + elements[i] = own + } + } + } + return elements +} + +type spdx3Namer struct { + ids *spdxIDAllocator + seen map[any]struct{} + agents map[string]v30.AnyAgent + licenses map[string]v30.AnyLicenseInfo +} + +// name sets an element's identifier once. An identifier already present is +// kept. +func (n *spdx3Namer) name(element interface { + GetID() string + SetID(string) +}, raw string) { + if isNilElement(element) { + return + } + if _, done := n.seen[element]; done { + return + } + n.seen[element] = struct{}{} + if element.GetID() != "" { + return + } + element.SetID(n.ids.allocate(raw)) +} + +// agent returns the one element standing for this agent, naming it. +func (n *spdx3Namer) agent(agent v30.AnyAgent) v30.AnyAgent { + if isNilElement(agent) { + return agent + } + kind := spdx3TypeName(agent) + key := kind + "\x00" + agent.GetName() + "\x00" + spdx3IdentifierKey(agent.GetExternalIdentifiers()) + if existing, ok := n.agents[key]; ok { + return existing + } + n.agents[key] = agent + n.name(agent, kind+"-"+agent.GetName()) + return agent +} + +func spdx3IdentifierKey(identifiers v30.ExternalIdentifierList) string { + parts := make([]string, 0, len(identifiers)) + for _, identifier := range identifiers { + if identifier == nil { + continue + } + typ := identifier.GetType() + parts = append(parts, typ.GetID()+"="+identifier.GetIdentifier()) + } + sort.Strings(parts) + return strings.Join(parts, ",") +} + +// relationships names a subject's relationships and the license trees they +// point at, ordered by type so the allocation order does not depend on the +// converter's map iteration. +func (n *spdx3Namer) relationships(subject string, rels []v30.AnyRelationship) { + type keyed struct { + key string + rel v30.AnyRelationship + } + ordered := make([]keyed, 0, len(rels)) + for _, rel := range rels { + ordered = append(ordered, keyed{key: spdx3RelationshipKey(rel), rel: rel}) + } + sort.SliceStable(ordered, func(i, j int) bool { return ordered[i].key < ordered[j].key }) + for _, entry := range ordered { + rel := entry.rel + typ := rel.GetType() + raw := "Relationship-" + subject + "-" + spdx3Tail(typ.GetID()) + if scoped, ok := rel.(v30.AnyLifecycleScopedRelationship); ok { + scope := scoped.GetScope() + raw += "-" + spdx3Tail(scope.GetID()) + } + n.name(rel, raw) + to := rel.GetTo() + for i, target := range to { + if license, ok := target.(v30.AnyLicenseInfo); ok { + to[i] = n.license(license, rel.GetID()+"-license") + } + } + } +} + +// spdx3RelationshipKey orders a subject's relationships by what they say, +// with the targets as the tie-break. +func spdx3RelationshipKey(rel v30.AnyRelationship) string { + typ := rel.GetType() + key := typ.GetID() + if scoped, ok := rel.(v30.AnyLifecycleScopedRelationship); ok { + scope := scoped.GetScope() + key += "\x00" + scope.GetID() + } + for _, target := range rel.GetTo() { + if license, ok := target.(v30.AnyLicenseInfo); ok { + if expression, rendered := renderSPDX3License(license); rendered { + key += "\x00" + expression + continue + } + } + if !isNilElement(target) { + key += "\x00" + target.GetID() + } + } + return key +} + +// license returns the one element standing for this license tree, naming +// every node in it. Listed licenses and listed exceptions are folded by +// identifier; compound nodes are named by their position under raw. +func (n *spdx3Namer) license(license v30.AnyLicenseInfo, raw string) v30.AnyLicenseInfo { + if isNilElement(license) { + return license + } + switch l := license.(type) { + case *v30.ListedLicense: + key := "ListedLicense-" + l.Name + if existing, ok := n.licenses[key]; ok { + return existing + } + n.licenses[key] = l + n.name(l, key) + case *v30.ConjunctiveLicenseSet: + n.name(l, raw) + for i, member := range l.Members { + l.Members[i] = n.license(member, fmt.Sprintf("%s-%d", l.ID, i)) + } + case *v30.DisjunctiveLicenseSet: + n.name(l, raw) + for i, member := range l.Members { + l.Members[i] = n.license(member, fmt.Sprintf("%s-%d", l.ID, i)) + } + case *v30.OrLaterOperator: + n.name(l, raw) + if subject, ok := n.license(l.SubjectLicense, l.ID+"-subject").(v30.AnyLicense); ok { + l.SubjectLicense = subject + } + case *v30.WithAdditionOperator: + n.name(l, raw) + if subject, ok := n.license(l.SubjectExtendableLicense, l.ID+"-subject").(v30.AnyExtendableLicense); ok { + l.SubjectExtendableLicense = subject + } + l.SubjectAddition = n.addition(l.SubjectAddition, l.ID+"-addition") + case *v30.IndividualLicensingInfo: + // NoAssertionLicense and NoneLicense are package variables in the + // library, and ToJSON writes this document's creationInfo into any + // element that has none. Publishing the shared value would mutate a + // global: the next document would carry this one's creation info, + // and two concurrent encodes would race. A per-document value with + // the same IRI says the same thing. + key := "IndividualLicensingInfo-" + l.ID + if existing, ok := n.licenses[key]; ok { + return existing + } + own := &v30.IndividualLicensingInfo{ID: l.ID, Name: l.Name} + n.licenses[key] = own + n.seen[own] = struct{}{} + return own + default: + n.name(license, raw) + } + return license +} + +func (n *spdx3Namer) addition(addition v30.AnyLicenseAddition, raw string) v30.AnyLicenseAddition { + if isNilElement(addition) { + return addition + } + if listed, ok := addition.(*v30.ListedLicenseException); ok { + key := "ListedLicenseException-" + listed.AdditionText + if existing, ok := n.licenses[key]; ok { + if folded, ok := existing.(v30.AnyLicenseAddition); ok { + return folded + } + } + if info, ok := addition.(v30.AnyLicenseInfo); ok { + n.licenses[key] = info + } + n.name(listed, key) + return listed + } + n.name(addition, raw) + return addition +} + +// canonicalSPDX3JSON orders the serialized graph. +// +// The serializer walks an object graph whose collections were filled from +// map iteration, so the @graph array and every collection's element list come +// out in a different order on each run. With every identifier fixed by +// nameSPDX3Elements, sorting the graph by identifier and each element list +// lexically is the whole of the remaining nondeterminism; every other list +// (rootElement, a relationship's targets, createdBy) already follows the 2.3 +// projection's order and is left as it is. Object keys are written sorted by +// encoding/json, as the 2.3 encoder writes them. +func canonicalSPDX3JSON(raw []byte, pretty bool) ([]byte, error) { + decoder := json.NewDecoder(bytes.NewReader(raw)) + decoder.UseNumber() + var document map[string]any + if err := decoder.Decode(&document); err != nil { + return nil, fmt.Errorf("canonicalize spdx 3: %w", err) + } + graph, _ := document["@graph"].([]any) + for _, node := range graph { + object, ok := node.(map[string]any) + if !ok { + continue + } + if elements, ok := object["element"].([]any); ok { + sort.SliceStable(elements, func(i, j int) bool { + return fmt.Sprint(elements[i]) < fmt.Sprint(elements[j]) + }) + } + } + sort.SliceStable(graph, func(i, j int) bool { + return spdx3NodeKey(graph[i]) < spdx3NodeKey(graph[j]) + }) + return marshalJSON(document, pretty) +} + +func spdx3NodeKey(node any) string { + object, ok := node.(map[string]any) + if !ok { + return "" + } + for _, key := range []string{"spdxId", "@id"} { + if id, ok := object[key].(string); ok { + return id + } + } + return "" +} + +// spdx3Tail is the local name of an SPDX 3 vocabulary IRI: the generated +// values' identifiers are "https://spdx.org/rdf/3.0.1/terms///". +func spdx3Tail(iri string) string { + if i := strings.LastIndexAny(iri, "/#"); i >= 0 { + return iri[i+1:] + } + return iri +} + +// spdx3TypeName names an element's class, for identifiers. +func spdx3TypeName(element any) string { + name := fmt.Sprintf("%T", element) + if i := strings.LastIndex(name, "."); i >= 0 { + name = name[i+1:] + } + return name +} + +// isNilElement reports a nil interface or a typed nil pointer inside one; the +// converter hands back both. +func isNilElement(value any) bool { + if value == nil { + return true + } + v := reflect.ValueOf(value) + return v.Kind() == reflect.Pointer && v.IsNil() +} diff --git a/sbom/spdx3_decode.go b/sbom/spdx3_decode.go new file mode 100644 index 0000000..1636e65 --- /dev/null +++ b/sbom/spdx3_decode.go @@ -0,0 +1,645 @@ +package sbom + +import ( + "bytes" + "encoding/json" + "fmt" + "sort" + "strings" + "time" + + "github.com/spdx/tools-golang/spdx/v2/common" + v23 "github.com/spdx/tools-golang/spdx/v2/v2_3" + v30 "github.com/spdx/tools-golang/spdx/v3/v3_0" +) + +func (spdx30Codec) decodeJSON(data []byte) (doc *Document, err error) { + // The library's JSON-LD reader panics on some malformed graphs (a + // vocabulary value given as an element, for one), and this is untrusted + // input: the panic is contained here and reported as malformed input. + defer func() { + if recovered := recover(); recovered != nil { + doc, err = nil, fmt.Errorf("%w: spdx 3: %v", ErrMalformedJSON, recovered) + } + }() + defined, err := defineSPDX3ListedReferences(data) + if err != nil { + return nil, fmt.Errorf("%w: spdx 3: %v", ErrMalformedJSON, err) + } + var parsed v30.Document + if err := parsed.FromJSON(bytes.NewReader(defined)); err != nil { + return nil, fmt.Errorf("%w: spdx 3: %v", ErrMalformedJSON, err) + } + return documentFromSPDX23(lowerSPDX3(&parsed)), nil +} + +// spdx3ListedReferenceProperties are the license properties of the SPDX +// 3.0.1 JSON-LD context whose value names a license or exception element, +// with whether the element named is an exception. +var spdx3ListedReferenceProperties = map[string]bool{ + "to": false, + "dataLicense": false, + "expandedlicensing_member": false, + "expandedlicensing_subjectLicense": false, + "expandedlicensing_subjectExtendableLicense": false, + "expandedlicensing_subjectAddition": true, +} + +// defineSPDX3ListedReferences adds a definition for every SPDX License List +// license or exception the document names by IRI without defining. +// +// A producer may name a listed license by its License List IRI +// (https://spdx.org/licenses/MIT) instead of defining an element for it. The +// pinned library's reader cannot resolve an identifier the graph does not +// define -- its only placeholder type for one satisfies no element interface +// -- so it rejected such a document outright, over a license reference. The +// IRI says everything a definition would: which list entry it is. So a +// minimal definition is added before reading, typed as the position it was +// named in requires (an exception after WITH, a license elsewhere), and the +// renderer reads the identifier back from the IRI. Only license properties +// are considered and only the License List namespace, so no other +// reference is altered. When the library can resolve external identifiers, +// this becomes a no-op: nothing is added for a document that defines what it +// names. +func defineSPDX3ListedReferences(data []byte) ([]byte, error) { + decoder := json.NewDecoder(bytes.NewReader(data)) + decoder.UseNumber() + var document map[string]any + if err := decoder.Decode(&document); err != nil { + return nil, err + } + graph, _ := document["@graph"].([]any) + defined := make(map[string]struct{}, len(graph)) + var creationInfo any + for _, node := range graph { + object, ok := node.(map[string]any) + if !ok { + continue + } + if id := spdx3NodeKey(object); id != "" { + defined[id] = struct{}{} + } + if creationInfo == nil { + creationInfo = object["creationInfo"] + } + } + + named := make(map[string]bool) // IRI -> is an exception + var order []string + for _, node := range graph { + object, ok := node.(map[string]any) + if !ok { + continue + } + for property, exception := range spdx3ListedReferenceProperties { + for _, iri := range spdx3ReferenceValues(object[property]) { + if !strings.HasPrefix(iri, spdxListedLicenseNamespace) || len(iri) == len(spdxListedLicenseNamespace) { + continue + } + if _, ok := defined[iri]; ok { + continue + } + if _, seen := named[iri]; !seen { + order = append(order, iri) + } + named[iri] = named[iri] || exception + } + } + } + if len(order) == 0 { + return data, nil + } + sort.Strings(order) + for _, iri := range order { + identifier := strings.TrimPrefix(iri, spdxListedLicenseNamespace) + definition := map[string]any{ + "spdxId": iri, + "name": identifier, + "creationInfo": creationInfo, + } + if named[iri] { + definition["type"] = "expandedlicensing_ListedLicenseException" + definition["expandedlicensing_additionText"] = identifier + } else { + definition["type"] = "expandedlicensing_ListedLicense" + } + if creationInfo == nil { + delete(definition, "creationInfo") + } + graph = append(graph, definition) + } + document["@graph"] = graph + return json.Marshal(document) +} + +// spdx3ReferenceValues reads a property that names one element or a list of +// them. +func spdx3ReferenceValues(value any) []string { + switch v := value.(type) { + case string: + return []string{v} + case []any: + out := make([]string, 0, len(v)) + for _, entry := range v { + if s, ok := entry.(string); ok { + out = append(out, s) + } + } + return out + } + return nil +} + +// lowerSPDX3 rewrites an SPDX 3 document as the SPDX 2.3 document it would +// have been converted from, so the 2.3 reader -- which owns every rule about +// what an SPDX package, license, reference or creator means to Bomly -- reads +// both versions. It is the inverse of v3_0.From_v2_3, which tools-golang does +// not provide; see spdx30Codec. +// +// What 2.3 cannot hold is not invented: a relationship that is not a +// dependency, a description or a license is dropped, as the 2.3 reader drops +// one, and an element that is not a package is read only where a package +// points at it. +func lowerSPDX3(d *v30.Document) *v23.Document { + l := newSPDX3Lowering(d) + + out := &v23.Document{ + SPDXVersion: v23.Version, + DataLicense: v23.DataLicense, + SPDXIdentifier: common.ElementID("DOCUMENT"), + DocumentName: d.Name, + DocumentNamespace: spdx3DocumentNamespace(d.ID), + DocumentComment: d.Comment, + CreationInfo: lowerSPDX3CreationInfo(d.CreationInfo), + } + if license, ok := renderSPDX3License(d.DataLicense); ok { + out.DataLicense = license + } + for _, imported := range d.Imports { + if ref, ok := lowerSPDX3Import(imported); ok { + out.ExternalDocumentReferences = append(out.ExternalDocumentReferences, ref) + } + } + + // Packages first, in document order, so identifiers are allocated the + // same way every time the same document is read. + for _, element := range d.Elements { + if pkg, ok := element.(v30.AnyPackage); ok && !isNilElement(pkg) { + out.Packages = append(out.Packages, l.lowerPackage(pkg)) + } + } + for _, element := range d.Elements { + if custom, ok := element.(*v30.CustomLicense); ok && custom != nil { + if other := lowerSPDX3CustomLicense(custom); other != nil { + out.OtherLicenses = append(out.OtherLicenses, other) + } + } + } + out.Relationships = append(out.Relationships, l.describes(d)...) + for _, element := range d.Elements { + rel, ok := element.(v30.AnyRelationship) + if !ok || isNilElement(rel) { + continue + } + out.Relationships = append(out.Relationships, l.lowerRelationship(rel)...) + } + l.applyLicenses(d.Elements) + return out +} + +// spdx3DocumentNamespace recovers the 2.3 namespace From_v2_3 turned into the +// document's identifier by appending "#" for its elements to hang off. +func spdx3DocumentNamespace(id string) string { + return strings.TrimSuffix(strings.TrimSpace(id), "#") +} + +type spdx3Lowering struct { + ids *spdxIDAllocator + idOf map[v30.AnyElement]common.ElementID + packages map[v30.AnyElement]*v23.Package + expand func(string) string + document string +} + +func newSPDX3Lowering(d *v30.Document) *spdx3Lowering { + prefixes := make(map[string]string, len(d.NamespaceMaps)) + for _, entry := range d.NamespaceMaps { + if entry == nil { + continue + } + prefixes[entry.GetPrefix()] = string(entry.GetNamespace()) + } + return &spdx3Lowering{ + ids: newSPDXIDAllocator(len(d.Elements)), + idOf: make(map[v30.AnyElement]common.ElementID, len(d.Elements)), + packages: make(map[v30.AnyElement]*v23.Package, len(d.Elements)), + document: strings.TrimSpace(d.ID), + // A compact identifier ("SPDXRef:pkg-x") is expanded through the + // document's namespace map, which is what the prefix means; the + // reader keeps identifiers exactly as written. + expand: func(id string) string { + prefix, rest, ok := strings.Cut(id, ":") + if !ok { + return id + } + if namespace, known := prefixes[prefix]; known { + return namespace + rest + } + return id + }, + } +} + +// elementID names an element in the lowered document. +// +// An element under the document's own namespace keeps its local part, which +// for a document Bomly wrote is the 2.3 identifier it was converted from. Any +// other identifier -- a full IRI from another producer -- is made a valid 2.3 +// idstring. Either way the allocator keeps the result unique. +func (l *spdx3Lowering) elementID(element v30.AnyElement) common.ElementID { + if id, ok := l.idOf[element]; ok { + return id + } + raw := l.expand(strings.TrimSpace(element.GetID())) + if l.document != "" && strings.HasPrefix(raw, l.document) { + raw = strings.TrimLeft(strings.TrimPrefix(raw, l.document), "#/") + } + if raw == "" { + raw = spdx3TypeName(element) + } + id := common.ElementID(l.ids.allocate(raw)) + l.idOf[element] = id + return id +} + +func (l *spdx3Lowering) lowerPackage(pkg v30.AnyPackage) *v23.Package { + out := &v23.Package{ + PackageName: pkg.GetName(), + PackageSPDXIdentifier: l.elementID(pkg), + PackageVersion: pkg.GetVersion(), + PackageSummary: pkg.GetSummary(), + PackageDescription: pkg.GetDescription(), + PackageComment: pkg.GetComment(), + PackageHomePage: string(pkg.GetHomePage()), + PackageSourceInfo: pkg.GetSourceInfo(), + PackageCopyrightText: pkg.GetCopyrightText(), + PrimaryPackagePurpose: spdx3PurposeName(pkg.GetPrimaryPurpose()), + PackageSupplier: lowerSPDX3Supplier(pkg.GetSuppliedBy()), + PackageChecksums: lowerSPDX3Checksums(pkg.GetVerifiedUsing()), + // The 2.3 meaning of an absent download location. + PackageDownloadLocation: "NOASSERTION", + } + if location := strings.TrimSpace(string(pkg.GetDownloadLocation())); location != "" { + out.PackageDownloadLocation = location + } + if originators := pkg.GetOriginatedBy(); len(originators) > 0 { + out.PackageOriginator = lowerSPDX3Originator(originators[0]) + } + if purl := strings.TrimSpace(string(pkg.GetPackageURL())); purl != "" { + out.PackageExternalReferences = append(out.PackageExternalReferences, &v23.PackageExternalReference{ + Category: common.CategoryPackageManager, + RefType: common.TypePackageManagerPURL, + Locator: purl, + }) + } + for _, identifier := range pkg.GetExternalIdentifiers() { + if identifier == nil || strings.TrimSpace(identifier.GetIdentifier()) == "" { + continue + } + typ := identifier.GetType() + term := spdx3ReferenceTermFor(typ.GetID()) + out.PackageExternalReferences = append(out.PackageExternalReferences, &v23.PackageExternalReference{ + Category: term.category, + RefType: term.refType, + Locator: strings.TrimSpace(identifier.GetIdentifier()), + ExternalRefComment: identifier.GetComment(), + }) + } + for _, ref := range pkg.GetExternalRefs() { + if ref == nil { + continue + } + typ := ref.GetType() + term := spdx3ReferenceTermFor(typ.GetID()) + comment := ref.GetComment() + if typ == v30.ExternalRefType_Other { + if category, refType, rest, ok := parseSPDX3ReferenceCarrier(comment); ok { + term = spdx3ReferenceTerm{category: category, refType: refType} + comment = rest + } + } + for _, locator := range ref.GetLocators() { + if locator = strings.TrimSpace(locator); locator == "" { + continue + } + out.PackageExternalReferences = append(out.PackageExternalReferences, &v23.PackageExternalReference{ + Category: term.category, + RefType: term.refType, + Locator: locator, + ExternalRefComment: comment, + }) + } + } + l.packages[pkg] = out + return out +} + +// describes lowers the document's subject to 2.3 DESCRIBES relationships. +// +// SPDX 3 names a document's subject as its root elements -- directly, or +// through an SBOM (or other collection) that is itself a root -- and also +// allows a describes relationship from the document or a collection; 2.3 has +// only the relationship. All three forms are read. +func (l *spdx3Lowering) describes(d *v30.Document) []*v23.Relationship { + var described []v30.AnyElement + seen := make(map[v30.AnyElement]struct{}) + add := func(element v30.AnyElement) { + if _, ok := l.packages[element]; !ok { + return + } + if _, dup := seen[element]; dup { + return + } + seen[element] = struct{}{} + described = append(described, element) + } + for _, root := range d.RootElements { + if collection, ok := root.(v30.AnyElementCollection); ok && !isNilElement(collection) { + for _, inner := range collection.GetRootElements() { + add(inner) + } + continue + } + add(root) + } + for _, element := range d.Elements { + rel, ok := element.(v30.AnyRelationship) + if !ok || isNilElement(rel) || rel.GetType() != v30.RelationshipType_Describes { + continue + } + from := rel.GetFrom() + if _, isCollection := from.(v30.AnyElementCollection); !isCollection { + continue + } + for _, to := range rel.GetTo() { + add(to) + } + } + out := make([]*v23.Relationship, 0, len(described)) + for _, element := range described { + out = append(out, &v23.Relationship{ + RefA: common.DocElementID{ElementRefID: common.ElementID("DOCUMENT")}, + RefB: common.DocElementID{ElementRefID: l.elementID(element)}, + Relationship: common.TypeRelationshipDescribe, + }) + } + return out +} + +// lowerRelationship lowers a dependency between packages to DEPENDS_ON. +// +// SPDX 3 states a dependency as dependsOn, hasOptionalDependency or +// hasProvidedDependency, optionally scoped to a lifecycle phase; From_v2_3 +// produces exactly those from the 2.3 dependency family. The 2.3 reader +// treats every member of that family as the same edge and takes scope from +// Bomly's own carrier instead (ADR-0043 gives SPDX no scope default), so the +// distinction is not needed to read the edge and DEPENDS_ON states it. +func (l *spdx3Lowering) lowerRelationship(rel v30.AnyRelationship) []*v23.Relationship { + switch rel.GetType() { + case v30.RelationshipType_DependsOn, + v30.RelationshipType_HasOptionalDependency, + v30.RelationshipType_HasProvidedDependency: + default: + return nil + } + from := rel.GetFrom() + if _, ok := l.packages[from]; !ok { + return nil + } + var out []*v23.Relationship + for _, to := range rel.GetTo() { + if _, ok := l.packages[to]; !ok { + continue + } + out = append(out, &v23.Relationship{ + RefA: common.DocElementID{ElementRefID: l.elementID(from)}, + RefB: common.DocElementID{ElementRefID: l.elementID(to)}, + Relationship: common.TypeRelationshipDependsOn, + }) + } + return out +} + +// applyLicenses writes each package's declared and concluded licenses. +// +// SPDX 3 states them as hasDeclaredLicense and hasConcludedLicense +// relationships to license elements; 2.3 as two expression fields. A +// package with more than one relationship of a kind holds all of them, which +// is their conjunction -- the composition From_v2_3 splits apart when one +// 2.3 field is converted to several relationships. +func (l *spdx3Lowering) applyLicenses(elements v30.ElementList) { + declared := make(map[*v23.Package][]string) + concluded := make(map[*v23.Package][]string) + for _, element := range elements { + rel, ok := element.(v30.AnyRelationship) + if !ok || isNilElement(rel) { + continue + } + var target map[*v23.Package][]string + switch rel.GetType() { + case v30.RelationshipType_HasDeclaredLicense: + target = declared + case v30.RelationshipType_HasConcludedLicense: + target = concluded + default: + continue + } + pkg, ok := l.packages[rel.GetFrom()] + if !ok { + continue + } + for _, to := range rel.GetTo() { + license, ok := to.(v30.AnyLicenseInfo) + if !ok { + continue + } + if expression, ok := renderSPDX3License(license); ok { + target[pkg] = append(target[pkg], expression) + } + } + } + for pkg, expressions := range declared { + pkg.PackageLicenseDeclared = conjoinSPDXExpressions(expressions) + } + for pkg, expressions := range concluded { + pkg.PackageLicenseConcluded = conjoinSPDXExpressions(expressions) + } +} + +// conjoinSPDXExpressions joins expressions with AND, parenthesizing each so +// precedence is preserved; NOASSERTION beside a real license says nothing and +// is left out. +func conjoinSPDXExpressions(expressions []string) string { + kept := make([]string, 0, len(expressions)) + for _, expression := range expressions { + if len(expressions) > 1 && isSPDXSentinel(expression) { + continue + } + kept = append(kept, expression) + } + switch len(kept) { + case 0: + return "" + case 1: + return kept[0] + } + for i, expression := range kept { + kept[i] = "(" + expression + ")" + } + return strings.Join(kept, " AND ") +} + +// lowerSPDX3CustomLicense keeps a custom license's text, which 2.3 holds in +// the extracted-licensing section under the same reference. The library +// fills a missing text with NOASSERTION, which is not a text. +func lowerSPDX3CustomLicense(custom *v30.CustomLicense) *v23.OtherLicense { + ref, ok := spdx3CustomIdentifier(custom.ID, "LicenseRef-") + if !ok || !strings.HasPrefix(ref, "LicenseRef-") { + return nil + } + text := strings.TrimSpace(custom.Text) + if text == "" || isSPDXSentinel(text) { + return nil + } + return &v23.OtherLicense{ + LicenseIdentifier: ref, + ExtractedText: custom.Text, + LicenseName: custom.Name, + LicenseComment: custom.Comment, + } +} + +func lowerSPDX3Checksums(methods v30.IntegrityMethodList) []common.Checksum { + var out []common.Checksum + for _, method := range methods { + hash, ok := method.(*v30.Hash) + if !ok || hash == nil || strings.TrimSpace(hash.Value) == "" { + continue + } + algorithm, ok := spdx3ChecksumAlgorithm(hash.Algorithm) + if !ok { + continue + } + out = append(out, common.Checksum{Algorithm: algorithm, Value: strings.TrimSpace(hash.Value)}) + } + return out +} + +// lowerSPDX3Agent renders an agent as the 2.3 "Type: Name (email)" parts. A +// software agent is a 2.3 Tool; an agent of no more specific class has no 2.3 +// type and is dropped, as 2.3 itself would not accept it. +func lowerSPDX3Agent(agent v30.AnyAgent) (kind, value string, ok bool) { + if isNilElement(agent) { + return "", "", false + } + switch agent.(type) { + case *v30.Person: + kind = "Person" + case *v30.Organization: + kind = "Organization" + case *v30.SoftwareAgent: + kind = spdxToolCreatorType + default: + return "", "", false + } + value = strings.TrimSpace(agent.GetName()) + if value == "" { + return "", "", false + } + for _, identifier := range agent.GetExternalIdentifiers() { + if identifier == nil { + continue + } + if identifier.GetType() == v30.ExternalIdentifierType_Email && strings.TrimSpace(identifier.GetIdentifier()) != "" { + value += " (" + strings.TrimSpace(identifier.GetIdentifier()) + ")" + break + } + } + return kind, value, true +} + +func lowerSPDX3Supplier(agent v30.AnyAgent) *common.Supplier { + kind, value, ok := lowerSPDX3Agent(agent) + if !ok || kind == spdxToolCreatorType { + return nil + } + return &common.Supplier{SupplierType: kind, Supplier: value} +} + +func lowerSPDX3Originator(agent v30.AnyAgent) *common.Originator { + kind, value, ok := lowerSPDX3Agent(agent) + if !ok || kind == spdxToolCreatorType { + return nil + } + return &common.Originator{OriginatorType: kind, Originator: value} +} + +// lowerSPDX3CreationInfo lowers who and what created the document to 2.3 +// creator lines. A tool appears both as a createdBy software agent and as a +// createdUsing tool in a document Bomly wrote; it is one creator. +func lowerSPDX3CreationInfo(info v30.AnyCreationInfo) *v23.CreationInfo { + if isNilElement(info) { + return nil + } + out := &v23.CreationInfo{CreatorComment: info.GetComment()} + if created := info.GetCreated(); !created.IsZero() { + out.Created = created.UTC().Format(time.RFC3339) + } + seen := make(map[string]struct{}) + add := func(kind, value string) { + line := kind + ": " + value + if _, dup := seen[line]; dup { + return + } + seen[line] = struct{}{} + out.Creators = append(out.Creators, common.Creator{CreatorType: kind, Creator: value}) + } + for _, tool := range info.GetCreatedUsing() { + if isNilElement(tool) { + continue + } + if name := strings.TrimSpace(tool.GetName()); name != "" { + add(spdxToolCreatorType, name) + } + } + for _, agent := range info.GetCreatedBy() { + if kind, value, ok := lowerSPDX3Agent(agent); ok { + add(kind, value) + } + } + return out +} + +// lowerSPDX3Import lowers an imported document to a 2.3 external document +// reference, the form ADR-0042's source links take: the location is the +// source document's identity and the hash its checksum. +func lowerSPDX3Import(imported v30.AnyExternalMap) (v23.ExternalDocumentRef, bool) { + if isNilElement(imported) { + return v23.ExternalDocumentRef{}, false + } + uri := strings.TrimSpace(string(imported.GetLocationHint())) + if uri == "" { + uri = strings.TrimSpace(string(imported.GetExternalSpdxID())) + } + if uri == "" { + return v23.ExternalDocumentRef{}, false + } + ref := v23.ExternalDocumentRef{ + DocumentRefID: common.DocumentID(strings.TrimPrefix(spdx3LocalName(string(imported.GetExternalSpdxID())), "DocumentRef-")), + URI: uri, + } + if checksums := lowerSPDX3Checksums(imported.GetVerifiedUsing()); len(checksums) > 0 { + ref.Checksum = checksums[0] + } + return ref, true +} diff --git a/sbom/spdx3_licenses.go b/sbom/spdx3_licenses.go new file mode 100644 index 0000000..c10fda8 --- /dev/null +++ b/sbom/spdx3_licenses.go @@ -0,0 +1,188 @@ +package sbom + +import ( + "strings" + + v30 "github.com/spdx/tools-golang/spdx/v3/v3_0" +) + +// spdxListedLicenseNamespace is where the SPDX License List publishes its +// identifiers; an SPDX 3 listed license or exception may be named by its IRI +// there rather than carrying the identifier as its name. +const spdxListedLicenseNamespace = "https://spdx.org/licenses/" + +// Operator binding strength in an SPDX license expression, weakest first: in +// the license expression grammar (SPDX 2.3 Annex D, which SPDX 3 keeps) WITH +// binds tighter than AND, which binds tighter than OR. A sub-expression is +// parenthesized only +// where it binds more weakly than the operator it appears under, so a tree +// renders as the expression a person would have written for it. +const ( + spdxPrecedenceOr = iota + 1 + spdxPrecedenceAnd + spdxPrecedenceWith + spdxPrecedenceAtom +) + +// renderSPDX3License writes an SPDX 3 license element back as an SPDX license +// expression, the form the rest of this package reads. +// +// SPDX 3 carries a license as an object graph (the ExpandedLicensing +// profile): listed and custom licenses, an or-later operator, a WITH +// operator, and conjunctive and disjunctive sets. tools-golang parses an +// expression into that graph (v3_0.ParseLicenseExpression) but has no way +// back, and no other Go library reads it. This is that way back, and nothing +// more: each node renders as the one expression operator it stands for, and +// the string it produces is handed to spdxkit -- which owns the expression +// grammar, its validation and its canonical form -- exactly as a license +// string read from an SPDX 2.3 document is. So no grammar is owned here, and +// a malformed tree yields a string spdxkit rejects rather than a guess. +// TestSPDX3LicenseRenderingInvertsTheLibraryParser pins the round trip. +// +// ok is false when any node cannot be rendered, in which case the license is +// dropped, as an unreadable 2.3 license string is. +func renderSPDX3License(license v30.AnyLicenseInfo) (string, bool) { + expression, _, ok := renderSPDX3LicenseNode(license) + return expression, ok +} + +func renderSPDX3LicenseNode(license v30.AnyLicenseInfo) (expression string, precedence int, ok bool) { + if isNilElement(license) { + return "", 0, false + } + switch l := license.(type) { + case *v30.ListedLicense: + id, ok := spdx3ListedIdentifier(l.ID, l.Name) + return id, spdxPrecedenceAtom, ok + case *v30.CustomLicense: + id, ok := spdx3CustomIdentifier(l.ID, "LicenseRef-") + return id, spdxPrecedenceAtom, ok + case *v30.LicenseExpression: + // A whole expression in one element; its own operators are unknown + // here, so it is treated as the weakest-binding form and + // parenthesized wherever it is nested. + expression := strings.TrimSpace(l.LicenseExpression) + return expression, spdxPrecedenceOr, expression != "" + case *v30.IndividualLicensingInfo: + switch l.ID { + case v30.IndividualLicensingInfo_NoAssertionLicense.GetID(): + return "NOASSERTION", spdxPrecedenceAtom, true + case v30.IndividualLicensingInfo_NoneLicense.GetID(): + return "NONE", spdxPrecedenceAtom, true + } + return "", 0, false + case *v30.OrLaterOperator: + subject, precedence, ok := renderSPDX3LicenseNode(l.SubjectLicense) + if !ok || precedence != spdxPrecedenceAtom { + return "", 0, false + } + return subject + "+", spdxPrecedenceAtom, true + case *v30.WithAdditionOperator: + subject, precedence, ok := renderSPDX3LicenseNode(l.SubjectExtendableLicense) + if !ok || precedence != spdxPrecedenceAtom { + return "", 0, false + } + addition, ok := renderSPDX3Addition(l.SubjectAddition) + if !ok { + return "", 0, false + } + return subject + " WITH " + addition, spdxPrecedenceWith, true + case *v30.ConjunctiveLicenseSet: + return renderSPDX3LicenseSet(l.Members, " AND ", spdxPrecedenceAnd) + case *v30.DisjunctiveLicenseSet: + return renderSPDX3LicenseSet(l.Members, " OR ", spdxPrecedenceOr) + } + return "", 0, false +} + +func renderSPDX3LicenseSet(members v30.LicenseInfoList, operator string, precedence int) (string, int, bool) { + parts := make([]string, 0, len(members)) + precedences := make([]int, 0, len(members)) + for _, member := range members { + part, memberPrecedence, ok := renderSPDX3LicenseNode(member) + if !ok { + return "", 0, false + } + parts = append(parts, part) + precedences = append(precedences, memberPrecedence) + } + switch len(parts) { + case 0: + return "", 0, false + case 1: + // A set of one is its member; there is no operator to bind. + return parts[0], precedences[0], true + } + for i := range parts { + if precedences[i] < precedence { + parts[i] = "(" + parts[i] + ")" + } + } + return strings.Join(parts, operator), precedence, true +} + +func renderSPDX3Addition(addition v30.AnyLicenseAddition) (string, bool) { + if isNilElement(addition) { + return "", false + } + switch a := addition.(type) { + case *v30.ListedLicenseException: + // The library's parser keeps an exception's identifier in its + // additionText; a document naming it by IRI or by name is read too. + if id, ok := spdx3ListedIdentifier(a.ID, ""); ok { + return id, true + } + if text := strings.TrimSpace(a.AdditionText); text != "" && !strings.ContainsAny(text, " \t\r\n()") { + return text, true + } + return spdx3ListedIdentifier("", a.Name) + case *v30.CustomLicenseAddition: + return spdx3CustomIdentifier(a.ID, "AdditionRef-") + } + return "", false +} + +// spdx3ListedIdentifier is a listed license's identifier: the tail of its +// License List IRI when it has one, otherwise its name, which is where the +// library's parser puts the identifier. +func spdx3ListedIdentifier(id, name string) (string, bool) { + if tail, ok := strings.CutPrefix(id, spdxListedLicenseNamespace); ok && tail != "" && !strings.ContainsAny(tail, " \t\r\n()/") { + return tail, true + } + name = strings.TrimSpace(name) + if name == "" || strings.ContainsAny(name, " \t\r\n()") { + return "", false + } + return name, true +} + +// spdx3CustomIdentifier is a custom license's or addition's reference: the +// local part of its element identifier, which the 2.3 conversion and any +// conforming producer make the LicenseRef- (or AdditionRef-) reference. +func spdx3CustomIdentifier(id, prefix string) (string, bool) { + local := spdx3LocalName(id) + if local == "" { + return "", false + } + for _, accepted := range []string{"LicenseRef-", "AdditionRef-", "DocumentRef-"} { + if strings.HasPrefix(local, accepted) { + return local, true + } + } + // A custom element whose identifier is not a reference -- a full IRI + // with some other local part -- still needs one to appear in an + // expression; the local part, made a valid idstring, is the closest the + // document gives. + return prefix + sanitizeSPDXID(local), true +} + +// spdx3LocalName is the part of an element identifier after its namespace: +// after "#" or "/" in a full IRI, after the prefix of a compact one +// ("SPDXRef:LicenseRef-x"). +func spdx3LocalName(id string) string { + id = strings.TrimSpace(id) + if i := strings.LastIndexAny(id, "#/:"); i >= 0 { + return id[i+1:] + } + return id +} diff --git a/sbom/spdx3_licenses_test.go b/sbom/spdx3_licenses_test.go new file mode 100644 index 0000000..7f79ede --- /dev/null +++ b/sbom/spdx3_licenses_test.go @@ -0,0 +1,96 @@ +package sbom + +import ( + "testing" + + v30 "github.com/spdx/tools-golang/spdx/v3/v3_0" + + "github.com/bomly-dev/bomly-sdk/spdxkit" + testkit "github.com/bomly-dev/bomly-sdk/testkit" +) + +// spdx3LicenseSeeds cover every node the library's parser builds: listed and +// custom licenses, or-later, WITH with a listed exception, both sets nested +// both ways, and the two individual values. +var spdx3LicenseSeeds = []string{ + "MIT", + "MIT OR Apache-2.0", + "MIT AND Apache-2.0", + "MIT OR Apache-2.0 AND BSD-3-Clause", + "(MIT OR Apache-2.0) AND BSD-3-Clause", + "GPL-2.0-only WITH Classpath-exception-2.0", + "Apache-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0", + "GPL-2.0+", + "LicenseRef-custom", + "LicenseRef-custom AND (MIT OR ISC)", + "NOASSERTION", + "NONE", +} + +// Rendering inverts the library's parser up to the canonical form spdxkit +// owns: an expression, parsed into the SPDX 3 object graph and rendered back, +// means what it meant. This is the differential test the hand-written +// renderer is held to. +func TestSPDX3LicenseRenderingInvertsTheLibraryParser(t *testing.T) { + for _, expression := range spdx3LicenseSeeds { + t.Run(expression, func(t *testing.T) { + parsed, err := v30.ParseLicenseExpression(expression) + if err != nil { + t.Fatalf("the library cannot parse %q: %v", expression, err) + } + rendered, ok := renderSPDX3License(parsed) + if !ok { + t.Fatalf("%q did not render", expression) + } + if got, want := spdxkit.CanonicalExpression(rendered), spdxkit.CanonicalExpression(expression); got != want { + t.Errorf("rendered %q (canonical %q), want canonical %q", rendered, got, want) + } + }) + } +} + +// FuzzRenderSPDX3License drives the renderer with every tree the library's +// parser can build. The renderer reads untrusted documents, so it must never +// panic, must be deterministic, and must not turn a valid expression into an +// invalid one. +func FuzzRenderSPDX3License(f *testing.F) { + for _, seed := range spdx3LicenseSeeds { + f.Add(seed) + } + for _, seed := range []string{"", "(", "MIT OR", "MIT WITH", "A AND (B OR (C WITH D))", "LicenseRef-", "+", "MIT++"} { + f.Add(seed) + } + f.Fuzz(func(t *testing.T, expression string) { + if len(expression) > testkit.MaxFuzzInputSize { + return + } + parsed, ok := parseSPDX3LicenseForFuzz(expression) + if !ok { + return + } + first, firstOK := renderSPDX3License(parsed) + second, secondOK := renderSPDX3License(parsed) + if first != second || firstOK != secondOK { + t.Fatalf("non-deterministic render of %q: %q/%v then %q/%v", expression, first, firstOK, second, secondOK) + } + if firstOK && spdxkit.Valid(expression) && !spdxkit.Valid(first) { + t.Fatalf("valid %q rendered as invalid %q", expression, first) + } + }) +} + +// parseSPDX3LicenseForFuzz runs the library's parser, which is not under +// test here: a panic or an error inside it is skipped, so the fuzzer spends +// its time on the renderer. +func parseSPDX3LicenseForFuzz(expression string) (parsed v30.AnyLicenseInfo, ok bool) { + defer func() { + if recover() != nil { + parsed, ok = nil, false + } + }() + parsed, err := v30.ParseLicenseExpression(expression) + if err != nil || isNilElement(parsed) { + return nil, false + } + return parsed, true +} diff --git a/sbom/spdx3_test.go b/sbom/spdx3_test.go new file mode 100644 index 0000000..df8ea8a --- /dev/null +++ b/sbom/spdx3_test.go @@ -0,0 +1,573 @@ +package sbom + +import ( + "bytes" + "encoding/json" + "errors" + "os" + "reflect" + "slices" + "strings" + "testing" + "time" + + v30 "github.com/spdx/tools-golang/spdx/v3/v3_0" + + "github.com/bomly-dev/bomly-sdk/model" +) + +// richSPDX3Document exercises everything the SPDX 3 codec carries: scopes in +// both directions, a declared and a concluded license with a WITH clause, a +// custom license with text, digests including a SHA3 one, a CPE, a supplier +// shared by two packages, a second origin, an asserted reference outside the +// converter's vocabulary, an advisory, and the document-level lifecycle. +func richSPDX3Document() *Document { + return &Document{ + Name: "rich", + Namespace: "https://bomly.dev/spdx/1b4e28ba-2fa1-11d2-883f-0016d3cca427", + Tool: "bomly-cli", + ToolVersion: "0.31.0", + Created: time.Date(2026, 11, 11, 0, 0, 0, 0, time.UTC), + Lifecycle: "build", + Components: []Component{ + {ID: "DocumentRoot-app", Name: "app", Version: "1.0.0", Type: "application"}, + { + ID: "pkg:npm/%40scope/left-pad@1.3.0", Name: "left-pad", Org: "@scope", Version: "1.3.0", + PURL: "pkg:npm/%40scope/left-pad@1.3.0", + Scopes: model.ScopesOf("runtime", "development"), + Licenses: []License{ + {Value: "MIT", SPDXExpression: "MIT"}, + {Value: "Apache-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0", SPDXExpression: "Apache-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0", Type: "concluded"}, + }, + Digests: []Digest{ + {Algorithm: "sha256", Value: strings.Repeat("ab", 32)}, + {Algorithm: "sha3-256", Value: strings.Repeat("cd", 32)}, + }, + CPEs: []string{"cpe:2.3:a:left-pad:left-pad:1.3.0:*:*:*:*:*:*:*"}, + Supplier: &model.Contact{Kind: model.ContactKindOrganization, Name: "Acme"}, + Description: "pads strings", + Homepage: "https://left-pad.example/home", + ArtifactURL: "https://registry.npmjs.org/left-pad/-/left-pad-1.3.0.tgz", + Origins: []ComponentOrigin{ + {ArtifactURL: "https://registry.npmjs.org/left-pad/-/left-pad-1.3.0.tgz"}, + {ArtifactURL: "https://mirror.example/left-pad-1.3.0.tgz"}, + }, + ExternalReferences: []model.ExternalReference{ + {Category: model.ExternalReferenceCategoryOther, Type: "website", Locator: "https://left-pad.example", Comment: "project site"}, + }, + Vulnerabilities: []Vulnerability{{ID: "GHSA-aaaa-bbbb-cccc", Advisories: []string{"https://github.com/advisories/GHSA-aaaa-bbbb-cccc"}}}, + EOL: &EOL{EOL: true, EOLDate: "2025-01-31"}, + }, + { + ID: "pkg:npm/custom@2.0.0", Name: "custom", Version: "2.0.0", PURL: "pkg:npm/custom@2.0.0", + Supplier: &model.Contact{Kind: model.ContactKindOrganization, Name: "Acme"}, + Licenses: []License{ + {Value: "Some custom license text"}, + {Value: "MIT", SPDXExpression: "MIT", Type: "concluded"}, + }, + }, + }, + Dependencies: []Dependency{ + {Ref: "DocumentRoot-app", DependsOn: []string{"pkg:npm/%40scope/left-pad@1.3.0", "pkg:npm/custom@2.0.0"}}, + {Ref: "pkg:npm/%40scope/left-pad@1.3.0", DependsOn: []string{"pkg:npm/custom@2.0.0"}}, + }, + Roots: []string{"DocumentRoot-app"}, + } +} + +// spdx3DocumentImports reads the documents an SPDX 3 document imports -- the +// form ADR-0042's source links take in SPDX 3. +func spdx3DocumentImports(t *testing.T, raw []byte) []struct { + ExternalSpdxID string `json:"externalSpdxId"` + LocationHint string `json:"locationHint"` +} { + t.Helper() + var doc struct { + Graph []json.RawMessage `json:"@graph"` + } + if err := json.Unmarshal(raw, &doc); err != nil { + t.Fatalf("decode spdx 3 document: %v\n%s", err, raw) + } + for _, node := range doc.Graph { + var element struct { + Type string `json:"type"` + Imports []struct { + ExternalSpdxID string `json:"externalSpdxId"` + LocationHint string `json:"locationHint"` + } `json:"import"` + } + if err := json.Unmarshal(node, &element); err != nil { + t.Fatalf("decode spdx 3 element: %v", err) + } + if element.Type == "SpdxDocument" { + out := make([]struct { + ExternalSpdxID string `json:"externalSpdxId"` + LocationHint string `json:"locationHint"` + }, len(element.Imports)) + copy(out, element.Imports) + return out + } + } + t.Fatalf("no SpdxDocument element in\n%s", raw) + return nil +} + +// spdx3GraphNodes returns the @graph nodes of an SPDX 3 document. +func spdx3GraphNodes(t *testing.T, raw []byte) []map[string]any { + t.Helper() + var doc struct { + Graph []map[string]any `json:"@graph"` + } + if err := json.Unmarshal(raw, &doc); err != nil { + t.Fatalf("decode spdx 3 document: %v\n%s", err, raw) + } + return doc.Graph +} + +func spdx3NodesOfType(t *testing.T, raw []byte, typ string) []map[string]any { + t.Helper() + var out []map[string]any + for _, node := range spdx3GraphNodes(t, raw) { + if node["type"] == typ { + out = append(out, node) + } + } + return out +} + +// The library's own validation accepts what the encoder writes, read back +// with the library's own reader. +func TestSPDX3OutputPassesTheLibraryValidation(t *testing.T) { + raw, err := MarshalJSON(richSPDX3Document(), TargetSPDX30JSON, EncodeOptions{Pretty: true}) + if err != nil { + t.Fatalf("export: %v", err) + } + var reread v30.Document + if err := reread.FromJSON(bytes.NewReader(raw)); err != nil { + t.Fatalf("the library cannot read the export: %v\n%s", err, raw) + } + // preProcess, because the reader resolves the specification's + // individual license values to the library's shared instances, which + // carry no creation info of their own; preProcess applies the library's + // fill-ins, the same ones the encoder ran before writing. + if err := reread.Validate(true); err != nil { + t.Fatalf("the library rejects the export: %v\n%s", err, raw) + } +} + +// One document, written twice, is the same bytes. The library's converter and +// serializer both iterate maps; before nameSPDX3Elements and +// canonicalSPDX3JSON, every run produced a different element order and +// different minted identifiers for the same relationships and licenses. +func TestSPDX3EncodingIsDeterministic(t *testing.T) { + first, err := MarshalJSON(richSPDX3Document(), TargetSPDX30JSON, EncodeOptions{Pretty: true}) + if err != nil { + t.Fatalf("export: %v", err) + } + for run := 0; run < 20; run++ { + again, err := MarshalJSON(richSPDX3Document(), TargetSPDX30JSON, EncodeOptions{Pretty: true}) + if err != nil { + t.Fatalf("export %d: %v", run, err) + } + if !bytes.Equal(first, again) { + t.Fatalf("export %d differs from the first:\nfirst:\n%s\nagain:\n%s", run, first, again) + } + } +} + +// Encoding does not mutate the library's shared license values. ToJSON writes +// the document's creation info into any element without one, and +// NoAssertionLicense is a package variable: publishing it directly leaked one +// document's creation info into every later document in the process. +func TestSPDX3EncodingLeavesTheLibrarySingletonsAlone(t *testing.T) { + singletons := []v30.AnyIndividualLicensingInfo{ + v30.IndividualLicensingInfo_NoAssertionLicense, + v30.IndividualLicensingInfo_NoneLicense, + } + // Cleared for the duration, because ToJSON fills only a nil creation + // info: once anything in this process -- another test running the + // library's own fill-ins -- has set one, a regression here would leave + // no trace. + for _, singleton := range singletons { + previous := singleton.GetCreationInfo() + singleton.SetCreationInfo(nil) + t.Cleanup(func() { singleton.SetCreationInfo(previous) }) + } + for _, created := range []time.Time{ + time.Date(2001, 1, 1, 0, 0, 0, 0, time.UTC), + time.Date(2002, 2, 2, 0, 0, 0, 0, time.UTC), + } { + doc := richSPDX3Document() + doc.Created = created + raw, err := MarshalJSON(doc, TargetSPDX30JSON, EncodeOptions{}) + if err != nil { + t.Fatalf("export: %v", err) + } + if infos := spdx3NodesOfType(t, raw, "CreationInfo"); len(infos) != 1 { + t.Fatalf("creation info nodes = %d, want one\n%s", len(infos), raw) + } + } + for _, singleton := range singletons { + if singleton.GetCreationInfo() != nil { + t.Errorf("%s was given a creation info by an encode", singleton.GetID()) + } + } +} + +// A decoded SPDX 3 export says what a decoded SPDX 2.3 export of the same +// document says. Both are read by documentFromSPDX23, so any difference is +// something the 3.0 conversion or its inverse lost. +func TestSPDX3RoundTripMatchesSPDX23(t *testing.T) { + decode := func(target Target) *Document { + t.Helper() + raw, err := MarshalJSON(richSPDX3Document(), target, EncodeOptions{}) + if err != nil { + t.Fatalf("export %s: %v", target, err) + } + doc, err := UnmarshalJSON(raw, target) + if err != nil { + t.Fatalf("ingest %s: %v\n%s", target, err, raw) + } + // Each document's own bytes and format differ by definition. + doc.Assertions.Checksum = nil + doc.Assertions.Format = "" + return doc + } + want := decode(TargetSPDX23JSON) + got := decode(TargetSPDX30JSON) + + if !reflect.DeepEqual(got.Components, want.Components) { + for i := range want.Components { + if i < len(got.Components) && !reflect.DeepEqual(got.Components[i], want.Components[i]) { + t.Errorf("component %d:\n spdx 3: %+v\n spdx 2.3: %+v", i, got.Components[i], want.Components[i]) + } + } + if len(got.Components) != len(want.Components) { + t.Errorf("components = %d, want %d", len(got.Components), len(want.Components)) + } + } + for _, field := range []struct { + name string + got, want any + }{ + {"dependencies", got.Dependencies, want.Dependencies}, + {"roots", got.Roots, want.Roots}, + {"described", got.Described, want.Described}, + {"name", got.Name, want.Name}, + {"namespace", got.Namespace, want.Namespace}, + {"tools", got.Tools, want.Tools}, + {"created", got.Created, want.Created}, + {"lifecycle", got.Lifecycle, want.Lifecycle}, + {"serial version", got.SerialVersion, want.SerialVersion}, + {"assertions", got.Assertions, want.Assertions}, + } { + if !reflect.DeepEqual(field.got, field.want) { + t.Errorf("%s:\n spdx 3: %+v\n spdx 2.3: %+v", field.name, field.got, field.want) + } + } +} + +// Every digest the SDK publishes in SPDX 2.3 is published in SPDX 3 and read +// back. The pinned library's converter misspells the SHA3 and BLAKE2b +// algorithms and wrote those hashes with an empty, required algorithm; +// prepareSPDX23ForConversion corrects it. This runs over the SDK's whole +// registry, so a new algorithm, or a library release that changes the +// spelling, fails here by name. +func TestSPDX3PublishesEveryDigestTheSDKPublishes(t *testing.T) { + for _, algorithm := range model.DigestAlgorithms() { + if algorithm.SPDXName() == "" { + continue + } + t.Run(string(algorithm), func(t *testing.T) { + value, ok := publishableDigestValue(algorithm) + if !ok { + t.Skipf("the SDK publishes no value for %s at any common length", algorithm) + } + doc := &Document{ + Name: "digest", + Components: []Component{{ + ID: "pkg:npm/widget@1.0.0", Name: "widget", Version: "1.0.0", PURL: "pkg:npm/widget@1.0.0", + Digests: []Digest{{Algorithm: string(algorithm), Value: value}}, + }}, + } + want := roundTripDigests(t, doc, TargetSPDX23JSON) + if len(want) == 0 { + t.Skipf("the SDK does not publish %s in SPDX 2.3 either", algorithm) + } + if got := roundTripDigests(t, doc, TargetSPDX30JSON); !reflect.DeepEqual(got, want) { + t.Errorf("spdx 3 digests = %+v, want %+v as spdx 2.3 reads them", got, want) + } + }) + } +} + +func publishableDigestValue(algorithm model.DigestAlgorithm) (string, bool) { + for _, length := range []int{8, 32, 40, 56, 64, 96, 128} { + value := strings.Repeat("a", length) + if _, ok := (model.Digest{Algorithm: algorithm, Value: value}).Normalized(); ok { + return value, true + } + } + return "", false +} + +func roundTripDigests(t *testing.T, doc *Document, target Target) []Digest { + t.Helper() + raw, err := MarshalJSON(doc, target, EncodeOptions{}) + if err != nil { + t.Fatalf("export %s: %v", target, err) + } + back, err := UnmarshalJSON(raw, target) + if err != nil { + t.Fatalf("ingest %s: %v\n%s", target, err, raw) + } + return componentNamed(t, back, "widget").Digests +} + +// The inverse vocabulary is derived from the library's forward converter, not +// written here. This pins what the derivation finds against the SDK registry +// and tools-golang's 2.3 constants, so a library release that maps more (or +// less) shows up as a named failure. +func TestSPDX3VocabularyIsDerivedFromTheLibrary(t *testing.T) { + vocabulary := deriveSPDX3Vocabulary() + + var spdxNamed []string + for _, algorithm := range model.DigestAlgorithms() { + if name := algorithm.SPDXName(); name != "" { + spdxNamed = append(spdxNamed, name) + } + } + var derived []string + for _, spelling := range vocabulary.checksums { + derived = append(derived, string(spelling)) + } + slices.Sort(spdxNamed) + slices.Sort(derived) + if !slices.Equal(derived, spdxNamed) { + t.Errorf("hash algorithms derived = %v, want every SDK algorithm with an SPDX name: %v", derived, spdxNamed) + } + + // The Annex F types the pinned converter does not map for a package. + // When the library learns one, this list shrinks. + unmapped := map[string]bool{"swh": true, "gitoid": true} + found := map[string]bool{} + for _, term := range vocabulary.references { + found[term.refType] = true + } + for _, term := range spdx3AnnexFReferenceTypes { + switch { + case unmapped[term.refType] && found[term.refType]: + t.Errorf("the library now converts %s; remove it from the unmapped list", term.refType) + case !unmapped[term.refType] && !found[term.refType]: + t.Errorf("no SPDX 3 type was derived for %s %s", term.category, term.refType) + } + } +} + +// What From_v2_3 drops is carried: an origin beyond the first as an +// alternative download location, and an asserted reference outside the +// converter's vocabulary as an "other" reference that reads back with its 2.3 +// category, type and comment. +func TestSPDX3CarriesReferencesTheConverterDrops(t *testing.T) { + raw, err := MarshalJSON(richSPDX3Document(), TargetSPDX30JSON, EncodeOptions{}) + if err != nil { + t.Fatalf("export: %v", err) + } + if !bytes.Contains(raw, []byte(`"altDownloadLocation"`)) || !bytes.Contains(raw, []byte("https://mirror.example/left-pad-1.3.0.tgz")) { + t.Errorf("the second origin was dropped:\n%s", raw) + } + back, err := UnmarshalJSON(raw, TargetSPDX30JSON) + if err != nil { + t.Fatalf("ingest: %v", err) + } + refs := componentNamed(t, back, "left-pad").ExternalReferences + var website *model.ExternalReference + for i := range refs { + if refs[i].Type == "website" { + website = &refs[i] + } + // The origin is published, and declined on the way back in, as the + // 2.3 and CycloneDX readers decline theirs. + if strings.Contains(refs[i].Locator, "mirror.example") { + t.Errorf("an origin came back as a source assertion: %+v", refs[i]) + } + } + if website == nil { + t.Fatalf("the website reference was dropped: %+v\n%s", refs, raw) + } + if website.Category != model.ExternalReferenceCategoryOther || website.Locator != "https://left-pad.example" || website.Comment != "project site" { + t.Errorf("website reference = %+v", *website) + } +} + +// SPDX 3 requires a createdBy agent. A scan credited to the tool alone gets +// its producing tool as a software agent rather than an invalid document; the +// tools its sources credited stay tools. +func TestSPDX3CreditsTheToolAsTheCreatingAgent(t *testing.T) { + doc := richSPDX3Document() + doc.Assertions.Tools = []model.DocumentTool{{Name: "upstream-generator-2.0"}} + raw, err := MarshalJSON(doc, TargetSPDX30JSON, EncodeOptions{}) + if err != nil { + t.Fatalf("export: %v", err) + } + agents := spdx3NodesOfType(t, raw, "SoftwareAgent") + if len(agents) != 1 || agents[0]["name"] != "bomly-cli-0.31.0" { + t.Errorf("software agents = %v, want the tool", agents) + } + back, err := UnmarshalJSON(raw, TargetSPDX30JSON) + if err != nil { + t.Fatalf("ingest: %v", err) + } + if got := len(spdx3NodesOfType(t, raw, "Tool")); got != 2 { + t.Errorf("tools = %d, want the producer and the source's generator", got) + } + if len(back.Assertions.Creators) != 0 || len(back.Assertions.Tools) != 2 { + t.Errorf("each tool should read back once, as a tool: creators %+v tools %+v", back.Assertions.Creators, back.Assertions.Tools) + } +} + +// A shared supplier and a shared license are published once each. +func TestSPDX3FoldsSharedAgentsAndLicenses(t *testing.T) { + raw, err := MarshalJSON(richSPDX3Document(), TargetSPDX30JSON, EncodeOptions{}) + if err != nil { + t.Fatalf("export: %v", err) + } + if got := len(spdx3NodesOfType(t, raw, "Organization")); got != 1 { + t.Errorf("organizations = %d, want Acme once", got) + } + mit := 0 + for _, license := range spdx3NodesOfType(t, raw, "expandedlicensing_ListedLicense") { + if license["name"] == "MIT" { + mit++ + } + } + if mit != 1 { + t.Errorf("MIT published %d times, want once\n%s", mit, raw) + } +} + +// Detection reads the format's own declaration, its JSON-LD context, in +// either of the forms JSON-LD allows. +func TestSPDX3DetectionReadsTheContext(t *testing.T) { + for _, tc := range []struct { + name string + raw string + want Target + }{ + {"string context", `{"@context":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld","@graph":[{}]}`, TargetSPDX30JSON}, + {"list context", `{"@context":["https://spdx.org/rdf/3.0.1/spdx-context.jsonld",{"x":"y"}],"@graph":[{}]}`, TargetSPDX30JSON}, + {"no graph", `{"@context":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld"}`, ""}, + {"empty graph", `{"@context":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld","@graph":[]}`, ""}, + {"graph not a list", `{"@context":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld","@graph":{}}`, ""}, + {"another context", `{"@context":"https://schema.org","@graph":[{}]}`, ""}, + {"context not a string", `{"@context":7,"@graph":[{}]}`, ""}, + } { + t.Run(tc.name, func(t *testing.T) { + got, err := DetectJSONTarget([]byte(tc.raw)) + if tc.want == "" { + if !errors.Is(err, ErrUnsupportedFormat) { + t.Errorf("DetectJSONTarget = %q, %v; want ErrUnsupportedFormat", got, err) + } + return + } + if err != nil || got != tc.want { + t.Errorf("DetectJSONTarget = %q, %v; want %q", got, err, tc.want) + } + }) + } +} + +// A document another producer wrote -- full IRIs, a License List IRI, a +// lifecycle-scoped dependency, a purl given only as an identifier, a simple +// licensing expression -- reads into the same model a 2.3 document would. +func TestSPDX3ReadsADocumentBomlyDidNotWrite(t *testing.T) { + raw, err := os.ReadFile("testdata/spdx3/foreign.spdx3.json") + if err != nil { + t.Fatalf("read fixture: %v", err) + } + doc, target, err := UnmarshalAutoJSON(raw) + if err != nil { + t.Fatalf("ingest: %v", err) + } + if target != TargetSPDX30JSON { + t.Fatalf("target = %q, want spdx 3", target) + } + if doc.Name != "app-sbom" || doc.Namespace != "https://example.com/docs/app-1" || doc.Assertions.Comment != "produced by another tool" { + t.Errorf("document = name %q namespace %q comment %q", doc.Name, doc.Namespace, doc.Assertions.Comment) + } + if !doc.Created.Equal(time.Date(2025, 1, 2, 3, 4, 5, 0, time.UTC)) { + t.Errorf("created = %v", doc.Created) + } + if len(doc.Assertions.Tools) != 1 || doc.Assertions.Tools[0].Name != "examplegen-1.2.0" { + t.Errorf("tools = %+v", doc.Assertions.Tools) + } + if len(doc.Assertions.Creators) != 1 || doc.Assertions.Creators[0].Name != "Acme Corp" { + t.Errorf("creators = %+v", doc.Assertions.Creators) + } + + app := componentNamed(t, doc, "app") + if app.Type != "application" { + t.Errorf("app type = %q", app.Type) + } + if len(doc.Roots) != 1 || doc.Roots[0] != app.ID { + t.Errorf("roots = %v, want the SBOM's root element %q", doc.Roots, app.ID) + } + var appDeps []string + for _, dep := range doc.Dependencies { + if dep.Ref == app.ID { + appDeps = dep.DependsOn + } + } + lodash := componentNamed(t, doc, "lodash") + jest := componentNamed(t, doc, "jest") + if !slices.Contains(appDeps, lodash.ID) || !slices.Contains(appDeps, jest.ID) { + t.Errorf("app depends on %v, want lodash %q and jest %q (the latter lifecycle-scoped)", appDeps, lodash.ID, jest.ID) + } + + if lodash.PURL != "pkg:npm/lodash@4.17.21" { + t.Errorf("lodash purl = %q", lodash.PURL) + } + if lodash.Supplier == nil || lodash.Supplier.Name != "Acme Corp" { + t.Errorf("lodash supplier = %+v", lodash.Supplier) + } + if len(lodash.Digests) != 1 || !strings.EqualFold(lodash.Digests[0].Algorithm, "SHA512") { + t.Errorf("lodash digests = %+v", lodash.Digests) + } + if len(lodash.Licenses) != 1 || lodash.Licenses[0].SPDXExpression != "MIT" || lodash.Licenses[0].Type != string(model.LicenseTypeDeclared) { + t.Errorf("lodash licenses = %+v, want MIT declared through its License List IRI", lodash.Licenses) + } + var tracker bool + for _, ref := range lodash.ExternalReferences { + tracker = tracker || (ref.Type == "issueTracker" && ref.Locator == "https://github.com/lodash/lodash/issues") + } + if !tracker { + t.Errorf("lodash references = %+v, want the issue tracker under its SPDX 3 name", lodash.ExternalReferences) + } + + if jest.PURL != "pkg:npm/jest@29.0.0" { + t.Errorf("jest purl = %q, want the one given as an external identifier", jest.PURL) + } + if len(jest.Licenses) != 1 || jest.Licenses[0].SPDXExpression != "MIT OR Apache-2.0" || jest.Licenses[0].Type != string(model.LicenseTypeConcluded) { + t.Errorf("jest licenses = %+v", jest.Licenses) + } +} + +// The library's reader panics on some malformed graphs; ingest reports them +// as malformed input instead of crashing the scan. +func TestSPDX3DecodeContainsLibraryPanics(t *testing.T) { + // A vocabulary value written as an element of the graph, the shape that + // made the reader panic on the converter's own pre-fix output. + raw := `{"@context":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld","@graph":[` + + `{"type":"CreationInfo","@id":"_:c","specVersion":"3.0.1","created":"2025-01-01T00:00:00Z","createdBy":[]},` + + `{"type":"SpdxDocument","spdxId":"https://example.com/d","creationInfo":"_:c"},` + + `{"type":"software_Package","spdxId":"https://example.com/p","name":"p","creationInfo":"_:c",` + + `"verifiedUsing":[{"type":"Hash","algorithm":"https://example.com/h","hashValue":"00"}]},` + + `{"type":"HashAlgorithm","spdxId":"https://example.com/h"}]}` + _, err := UnmarshalJSON([]byte(raw), TargetSPDX30JSON) + if err == nil { + t.Skip("the library now reads this graph without failing; the recover is still the boundary") + } + if !errors.Is(err, ErrMalformedJSON) { + t.Errorf("err = %v, want ErrMalformedJSON", err) + } +} diff --git a/sbom/spdx3_vocabulary.go b/sbom/spdx3_vocabulary.go new file mode 100644 index 0000000..7152a19 --- /dev/null +++ b/sbom/spdx3_vocabulary.go @@ -0,0 +1,235 @@ +package sbom + +import ( + "strings" + "sync" + + "github.com/spdx/tools-golang/spdx/v2/common" + v23 "github.com/spdx/tools-golang/spdx/v2/v2_3" + v30 "github.com/spdx/tools-golang/spdx/v3/v3_0" + + "github.com/bomly-dev/bomly-sdk/model" +) + +// spdx3Vocabulary maps SPDX 3 vocabulary values back to the SPDX 2.3 terms +// the decoder lowers them to. +// +// None of it is written out by hand. tools-golang owns the 2.3 -> 3.0 mapping +// (v3_0.From_v2_3) and keeps it in unexported tables, and offers no inverse. +// Copying those tables here would be the transcription the delegation rule +// forbids: correct the day it was written and silently lossy the day the +// library or the specification grew. Instead each inverse is read off the +// library's own forward converter, once, by converting a probe document that +// carries one instance of every 2.3 term this package can name: +// +// - checksum algorithms: every member of the SDK's digest registry with an +// SPDX spelling (model.DigestAlgorithms), so the registry stays the one +// list of algorithms; +// - external reference types: every type tools-golang declares for SPDX 2.3 +// Annex F, by its constant. +// +// A 2.3 term the converter does not map simply produces no inverse entry, +// and the decoder treats the 3.0 value as foreign. TestSPDX3VocabularyIsDerived +// FromTheLibrary pins what the derivation finds, so a library change shows up +// as a named test failure rather than as a quiet change in decoded output. +type spdx3Vocabulary struct { + // checksums maps a HashAlgorithm IRI to its SPDX 2.3 checksum spelling. + checksums map[string]common.ChecksumAlgorithm + // references maps an ExternalIdentifierType or ExternalRefType IRI to + // the SPDX 2.3 category and type it was converted from. + references map[string]spdx3ReferenceTerm +} + +type spdx3ReferenceTerm struct { + category string + refType string +} + +// spdx3AnnexFReferenceTypes are the SPDX 2.3 Annex F reference types, each +// named by the constant tools-golang declares for it. The library has no +// slice of them, so they are listed; the values are the library's. +var spdx3AnnexFReferenceTypes = []spdx3ReferenceTerm{ + {common.CategorySecurity, common.TypeSecurityCPE23Type}, + {common.CategorySecurity, common.TypeSecurityCPE22Type}, + {common.CategorySecurity, common.TypeSecurityAdvisory}, + {common.CategorySecurity, common.TypeSecurityFix}, + {common.CategorySecurity, common.TypeSecurityUrl}, + {common.CategorySecurity, common.TypeSecuritySwid}, + {common.CategoryPackageManager, common.TypePackageManagerMavenCentral}, + {common.CategoryPackageManager, common.TypePackageManagerNpm}, + {common.CategoryPackageManager, common.TypePackageManagerNuGet}, + {common.CategoryPackageManager, common.TypePackageManagerBower}, + {common.CategoryPackageManager, common.TypePackageManagerPURL}, + {common.CategoryPersistentId, common.TypePersistentIdSwh}, + {common.CategoryPersistentId, common.TypePersistentIdGitoid}, +} + +var ( + spdx3VocabularyOnce sync.Once + spdx3VocabularyValue spdx3Vocabulary +) + +// spdx3VocabularyTerms returns the derived inverse vocabulary. +func spdx3VocabularyTerms() spdx3Vocabulary { + spdx3VocabularyOnce.Do(func() { + spdx3VocabularyValue = deriveSPDX3Vocabulary() + }) + return spdx3VocabularyValue +} + +func deriveSPDX3Vocabulary() (vocabulary spdx3Vocabulary) { + vocabulary = spdx3Vocabulary{ + checksums: make(map[string]common.ChecksumAlgorithm), + references: make(map[string]spdx3ReferenceTerm), + } + // The derivation runs library code; a panic in it must not take a scan + // down. A vocabulary that could not be derived decodes every value as + // foreign, which loses precision, not data. + defer func() { + if recover() != nil { + vocabulary = spdx3Vocabulary{ + checksums: map[string]common.ChecksumAlgorithm{}, + references: map[string]spdx3ReferenceTerm{}, + } + } + }() + + // One package per term, so each converted package says which term it + // came from by its identifier. + probe := v23.Document{ + SPDXVersion: v23.Version, + DataLicense: v23.DataLicense, + SPDXIdentifier: "DOCUMENT", + DocumentName: "vocabulary", + DocumentNamespace: "https://bomly.dev/spdx/vocabulary", + CreationInfo: &v23.CreationInfo{ + Creators: []common.Creator{{CreatorType: "Organization", Creator: "bomly"}}, + Created: "2000-01-01T00:00:00Z", + }, + } + checksumOf := map[string]common.ChecksumAlgorithm{} + for _, algorithm := range model.DigestAlgorithms() { + spelling := algorithm.SPDXName() + if spelling == "" { + continue + } + id := "checksum-" + sanitizeSPDXID(spelling) + checksumOf[id] = common.ChecksumAlgorithm(spelling) + probe.Packages = append(probe.Packages, &v23.Package{ + PackageName: id, + PackageSPDXIdentifier: common.ElementID(id), + PackageChecksums: []common.Checksum{{ + Algorithm: spdx3ConverterChecksumKey(common.ChecksumAlgorithm(spelling)), + Value: "00", + }}, + }) + } + referenceOf := map[string]spdx3ReferenceTerm{} + for _, term := range spdx3AnnexFReferenceTypes { + id := "reference-" + sanitizeSPDXID(term.refType) + referenceOf[id] = term + probe.Packages = append(probe.Packages, &v23.Package{ + PackageName: id, + PackageSPDXIdentifier: common.ElementID(id), + PackageExternalReferences: []*v23.PackageExternalReference{{ + Category: term.category, + RefType: term.refType, + // Not a valid URI, on purpose: the converter moves a purl that + // parses as one out of the identifier list into packageUrl, + // where its identifier type can no longer be read. Every + // other type takes the locator as it is. + Locator: "%zz", + }}, + }) + } + + var converted v30.Document + v30.From_v2_3(probe, &converted) + sbom := spdx3ConvertedSBOM(&converted) + if sbom == nil { + return vocabulary + } + for _, element := range sbom.Elements { + pkg, ok := element.(*v30.Package) + if !ok { + continue + } + if spelling, ok := checksumOf[pkg.ID]; ok { + for _, method := range pkg.VerifiedUsing { + if hash, ok := method.(*v30.Hash); ok && hash.Algorithm.GetID() != "" { + vocabulary.checksums[hash.Algorithm.GetID()] = spelling + } + } + continue + } + term, ok := referenceOf[pkg.ID] + if !ok { + continue + } + for _, identifier := range pkg.ExternalIdentifiers { + if identifier == nil { + continue + } + typ := identifier.GetType() + vocabulary.references[typ.GetID()] = term + } + for _, ref := range pkg.ExternalRefs { + if ref == nil { + continue + } + typ := ref.GetType() + vocabulary.references[typ.GetID()] = term + } + } + // The Bomly-defined origin type is published as an alternative download + // location (carrySPDX3References), so it reads back as that type -- and + // the 2.3 reader then declines it as origin-derived, the same rule the + // CycloneDX reader applies to vcs and distribution references. + vocabulary.references[v30.ExternalRefType_AltDownloadLocation.GetID()] = spdx3ReferenceTerm{ + category: common.CategoryOther, + refType: spdxOriginRefType, + } + return vocabulary +} + +// spdx3ChecksumAlgorithm returns the SPDX 2.3 spelling of an SPDX 3 hash +// algorithm, or false for one the SDK has no member for. +func spdx3ChecksumAlgorithm(algorithm v30.HashAlgorithm) (common.ChecksumAlgorithm, bool) { + spelling, ok := spdx3VocabularyTerms().checksums[algorithm.GetID()] + return spelling, ok +} + +// spdx3ReferenceTermFor returns the SPDX 2.3 category and type an SPDX 3 +// reference type lowers to. +// +// A type outside the derived vocabulary is foreign -- one SPDX 3 defines and +// 2.3 does not, such as vcs or issueTracker -- and keeps its SPDX 3 name as +// the type under category OTHER, the 2.3 category for exactly that. The +// model's reference vocabulary is open by design, so the name survives a +// round trip rather than being folded into a 2.3 type it is not. +func spdx3ReferenceTermFor(iri string) spdx3ReferenceTerm { + if term, ok := spdx3VocabularyTerms().references[iri]; ok { + return term + } + return spdx3ReferenceTerm{category: common.CategoryOther, refType: spdx3Tail(iri)} +} + +// spdx3PurposeName lowers an SPDX 3 software purpose to the 2.3 spelling: +// "operatingSystem" becomes "OPERATING-SYSTEM". Purposes are written in +// lowerCamelCase in SPDX 3 and in upper case with hyphens in 2.3; the change +// is spelling only, so it is a rule rather than a table, and a purpose 2.3 +// lacks keeps its name for the component-type reader to classify. +func spdx3PurposeName(purpose v30.SoftwarePurpose) string { + tail := spdx3Tail(purpose.GetID()) + if tail == "" { + return "" + } + var b strings.Builder + for i, r := range tail { + if r >= 'A' && r <= 'Z' && i > 0 { + b.WriteByte('-') + } + b.WriteRune(r) + } + return strings.ToUpper(b.String()) +} diff --git a/sbom/strict_test.go b/sbom/strict_test.go index 0c6b125..6a5ac98 100644 --- a/sbom/strict_test.go +++ b/sbom/strict_test.go @@ -153,7 +153,7 @@ func TestStrictIngestDoesNotRejectMerelyUnusualDocuments(t *testing.T) { // Bomly's own output always passes its own gate, in both formats. A gate that // rejected what the encoder writes would be a released defect, not a defense. func TestBomlyOutputPassesTheStrictGate(t *testing.T) { - for _, target := range []Target{TargetSPDX23JSON, TargetCycloneDX16JSON} { + for _, target := range []Target{TargetSPDX23JSON, TargetSPDX30JSON, TargetCycloneDX16JSON} { t.Run(string(target), func(t *testing.T) { raw, err := MarshalDepGraphJSON(scopedGraph(t, "runtime"), target, BuildOptions{}, EncodeOptions{Pretty: true}) if err != nil { diff --git a/sbom/testdata/spdx3/foreign.spdx3.json b/sbom/testdata/spdx3/foreign.spdx3.json new file mode 100644 index 0000000..830d15b --- /dev/null +++ b/sbom/testdata/spdx3/foreign.spdx3.json @@ -0,0 +1,121 @@ +{ + "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld", + "@graph": [ + { + "type": "CreationInfo", + "@id": "_:creationinfo", + "specVersion": "3.0.1", + "created": "2025-01-02T03:04:05Z", + "createdBy": ["https://example.com/agents/acme"], + "createdUsing": ["https://example.com/tools/examplegen"] + }, + { + "type": "Organization", + "spdxId": "https://example.com/agents/acme", + "name": "Acme Corp", + "creationInfo": "_:creationinfo", + "externalIdentifier": [ + {"type": "ExternalIdentifier", "externalIdentifierType": "email", "identifier": "sbom@acme.example"} + ] + }, + { + "type": "Tool", + "spdxId": "https://example.com/tools/examplegen", + "name": "examplegen-1.2.0", + "creationInfo": "_:creationinfo" + }, + { + "type": "SpdxDocument", + "spdxId": "https://example.com/docs/app-1", + "name": "app-sbom", + "comment": "produced by another tool", + "creationInfo": "_:creationinfo", + "profileConformance": ["core", "software", "simpleLicensing"], + "rootElement": ["https://example.com/sbom/1"] + }, + { + "type": "software_Sbom", + "spdxId": "https://example.com/sbom/1", + "creationInfo": "_:creationinfo", + "rootElement": ["https://example.com/pkg/app"], + "element": [ + "https://example.com/pkg/app", + "https://example.com/pkg/lodash", + "https://example.com/pkg/jest" + ] + }, + { + "type": "software_Package", + "spdxId": "https://example.com/pkg/app", + "name": "app", + "software_packageVersion": "2.0.0", + "software_primaryPurpose": "application", + "creationInfo": "_:creationinfo" + }, + { + "type": "software_Package", + "spdxId": "https://example.com/pkg/lodash", + "name": "lodash", + "software_packageVersion": "4.17.21", + "software_packageUrl": "pkg:npm/lodash@4.17.21", + "software_downloadLocation": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "suppliedBy": "https://example.com/agents/acme", + "verifiedUsing": [ + {"type": "Hash", "algorithm": "sha512", "hashValue": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"} + ], + "externalRef": [ + {"type": "ExternalRef", "externalRefType": "issueTracker", "locator": ["https://github.com/lodash/lodash/issues"]} + ], + "creationInfo": "_:creationinfo" + }, + { + "type": "software_Package", + "spdxId": "https://example.com/pkg/jest", + "name": "jest", + "software_packageVersion": "29.0.0", + "externalIdentifier": [ + {"type": "ExternalIdentifier", "externalIdentifierType": "packageUrl", "identifier": "pkg:npm/jest@29.0.0"} + ], + "creationInfo": "_:creationinfo" + }, + { + "type": "Relationship", + "spdxId": "https://example.com/relationships/app-lodash", + "from": "https://example.com/pkg/app", + "to": ["https://example.com/pkg/lodash"], + "relationshipType": "dependsOn", + "creationInfo": "_:creationinfo" + }, + { + "type": "LifecycleScopedRelationship", + "spdxId": "https://example.com/relationships/app-jest", + "from": "https://example.com/pkg/app", + "to": ["https://example.com/pkg/jest"], + "relationshipType": "dependsOn", + "scope": "development", + "creationInfo": "_:creationinfo" + }, + { + "type": "Relationship", + "spdxId": "https://example.com/relationships/lodash-license", + "from": "https://example.com/pkg/lodash", + "to": ["https://spdx.org/licenses/MIT"], + "relationshipType": "hasDeclaredLicense", + "creationInfo": "_:creationinfo" + }, + { + "type": "simplelicensing_LicenseExpression", + "spdxId": "https://example.com/licenses/jest", + "simplelicensing_licenseExpression": "MIT OR Apache-2.0", + "creationInfo": "_:creationinfo" + }, + { + "type": "Relationship", + "spdxId": "https://example.com/relationships/jest-license", + "from": "https://example.com/pkg/jest", + "to": ["https://example.com/licenses/jest"], + "relationshipType": "hasConcludedLicense", + "creationInfo": "_:creationinfo" + } + ] +}