From 55927dbecbf4f039796d2c8ca2a5dd5e4c1a8253 Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Wed, 11 Nov 2026 16:14:19 -0800 Subject: [PATCH] feat(sbom): read and write SPDX 3.0.1 JSON-LD Adds TargetSPDX30JSON ("spdx-3.0+json"), encoded and decoded through spdx/tools-golang's spdx/v3/v3_0 package, which the module already pins (v0.6.0-rc4, the same release Syft's SPDX 3 encoder uses). Encoding projects onto SPDX 2.3 with the existing builder and converts with the library's From_v2_3, so both SPDX encodings of one scan say the same thing. Decoding lowers the library's typed SPDX 3 graph back to the 2.3 model and runs the existing 2.3 reader, so one set of rules reads both. Detection reads the document's JSON-LD @context. The pinned release candidate has defects the codec works around, each pinned by a test proven to fail without its fix: - SHA3 and BLAKE2b checksums convert with an empty, required algorithm. - Every external reference outside two small tables is dropped. - createdBy is left empty for a tool-only document, failing validation. - The converter and serializer iterate maps, so output order and minted identifiers changed on every run; elements now get content-derived identifiers and the graph is sorted. - The serializer mutates the library's shared NoAssertionLicense value. - The reader panics on some graphs and refuses an undefined License List IRI; ingest contains the panic and defines listed licenses first. Vocabulary inverses (hash algorithms, reference types) are derived at first use from the library's own forward converter, not transcribed. The license tree renderer is the one hand-written grammar piece; its output goes through spdxkit, with a differential test and a fuzz target. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 6 +- README.md | 2 +- go.mod | 3 + go.sum | 6 + repo_guards_test.go | 12 + sbom/codec.go | 44 ++ sbom/codec_fuzz_test.go | 11 + sbom/doc.go | 5 +- sbom/document_assertions_test.go | 2 +- sbom/document_sources_test.go | 12 +- sbom/eol_round_trip_test.go | 2 +- sbom/model.go | 1 + sbom/origin_test.go | 2 +- sbom/scope_round_trip_test.go | 4 +- sbom/spdx23.go | 21 +- sbom/spdx3.go | 659 +++++++++++++++++++++++++ sbom/spdx3_decode.go | 645 ++++++++++++++++++++++++ sbom/spdx3_licenses.go | 188 +++++++ sbom/spdx3_licenses_test.go | 96 ++++ sbom/spdx3_test.go | 573 +++++++++++++++++++++ sbom/spdx3_vocabulary.go | 235 +++++++++ sbom/strict_test.go | 2 +- sbom/testdata/spdx3/foreign.spdx3.json | 121 +++++ 23 files changed, 2636 insertions(+), 16 deletions(-) create mode 100644 sbom/spdx3.go create mode 100644 sbom/spdx3_decode.go create mode 100644 sbom/spdx3_licenses.go create mode 100644 sbom/spdx3_licenses_test.go create mode 100644 sbom/spdx3_test.go create mode 100644 sbom/spdx3_vocabulary.go create mode 100644 sbom/testdata/spdx3/foreign.spdx3.json 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" + } + ] +}