interlynk-io / sbomasm

SBOM Assembler - A tool to compose your various sboms into a single sbom.

sbomasm: Assembler for SBOMs

sbomasm is your primary tool to assemble SBOMs, for easy management and distribution.

go install github.com/interlynk-io/sbomasm@latest

other installation options.

SBOM Card

Usage

SPDX assemble multiple SBOMs

sbomasm assemble -n "mega spdx app" -v "1.0.0" -t "application" -o final-product.spdx.json sdk.spdx.json demo-app.spdx.json report.spdx.json

CDX assemble multiple SBOMs

sbomasm assemble -n "mega cdx app" -v "1.0.0" -t "application" -o final-product.cdx.json sbom1.json sbom2.json sbom3.json

sbomasm in an AirGapped Environment

INTERLYNK_DISABLE_VERSION_CHECK=true sbomasm assemble -n "mega cdx app" -v "1.0.0" -t "application" -o final-product.cdx.json sbom1.json sbom2.json sbom3.json

sbomasm via containers

docker run -v .:/app/sboms/ ghcr.io/interlynk-io/sbomasm:v0.1.3 assemble -n "assemble cdx app" -v "v2.0.0" -t "application" -o /app/sboms/final-prod.cdx.json /app/sboms/one.cdx.json /app/sboms/two.cdx.json

Features

• SBOM format agnostic
• Supports Hierarchial and Flat merging
• Configurable primary component/package
• Blazing fast 🚀

Why should we assemble SBOMs?

• Software Supply Chain Management: When managing the software supply chain, organizations often need to merge multiple SBOMs from different vendors or sources to create a complete and accurate picture of the software components used in their products or systems.
• Software Development: When developing software, teams often use multiple tools and technologies to create and manage different parts of the software stack. Merging the SBOMs from these tools can provide a holistic view of the entire software stack, making it easier to identify dependencies, vulnerabilities, and licensing issues.
• Regulatory Compliance: Some regulations, such as the European Union's General Data Protection Regulation (GDPR), require companies to have a clear understanding of the software components used in their systems. Merging SBOMs can provide a comprehensive view of the software stack, making it easier to comply with these regulations.
• Open Source Software Management: Many organizations use open source software in their products and systems. Merging SBOMs for open source components can help organizations track and manage the various dependencies, licenses, and vulnerabilities associated with these components.

How does assembling SBOMs work

An assembled SBOM encompasses all the components/packages, dependencies, files, licenses, selected metadata of its included sbom. A new primary component/package is generated based on configuration, which is then associated with the included SBOMs primary components.

+-----------------------+   +-----------------------+   +-----------------------+
|       Micro SBOM 1    |   |       Micro SBOM 2    |   |       Micro SBOM 3    |
|-----------------------|   |-----------------------|   |-----------------------|
|  Component 1          |   |  Component 3          |   |  Component 4          |
|  Component 2          |   |  Component 1          |   |  Component 5          |
|  File 1 (Comp1)       |   |  File 1 (Comp3)       |   |  File 1 (Comp5)       |
|  File 2 (Comp1)       |   |  File 2 (Comp3)       |   |                       |
|  Dependency 1 (Comp1) |   |  Dependency 1 (Comp2) |   |  Dependency 2 (Comp3) |
|  License: Apache 2.0  |   |  License: MIT         |   |  License: BSD         |
|  Metadata 1           |   |  Metadata 1           |   |  Metadata 1           |
|-----------------------|   |-----------------------|   |-----------------------|
|          ↓            |   |          ↓            |   |          ↓            |
+-----------------------+   +-----------------------+   +-----------------------+
                                      ↓
                      +------------------------------------+
                      |           Mega SBOM                |
                      |------------------------------------|
                      |  Component 1                       |
                      |  Component 2                       |
                      |  Component 3                       |
                      |  Component 1                       |
                      |  Component 4                       |
                      |  Component 5                       |
                      |                                    |
                      |  File 1 (Comp1)                    |
                      |  File 2 (Comp1)                    |
                      |  File 1 (Comp3)                    |
                      |  File 2 (Comp3)                    |
                      |  File 1 (Comp5)                    |
                      |                                    |
                      |  Dependency 1 (Comp1)              |
                      |  Dependency 1 (Comp2)              |
                      |  Dependency 2 (Comp3)              |
                      |                                    |
                      |  License: Apache 2.0               |
                      |  License: MIT                      |
                      |  License: BSD                      |
                      |                                    |
                      |  Micro Sbom 1 - Primary Comp       |
                      |  Micro Sbom 2 - Primary Comp       |
                      |  Micro Sbom 3 - Primary Comp       |
                      +------------------------------------+

The assembled SBOM spec format is guided by the input SBOMs e.g if the inputs are all SPDX, the output needs to be SPDX format. Below is the support matrix for input and output formats

Spec	Input SBOM Formats	Output SBOM formats	Output SBOM spec version
SPDX	json, yaml, rdf, tag-value	json, xml	2.3
CycloneDX	json, xml	json, xml	1.6

Merge Algorithm

The default merge algorithm is Hierarchical merge.

Algo	SBOM Spec	Notes
Hierarchical	CycloneDX	For each input SBOM, we associate the dependent components with its primary component. This primary component is then included as a dependent of the newly created primary component for the assembled SBOM.
Flat	CycloneDX	Provides a flat list of components, duplicates are not removed.
Assembly	CycloneDX	Similar to Hierarchical merge, but treats each sbom as not dependent, so no relationships are created with primary.
Hierarchical	SPDX	It maintains relationships among all the merged documents. Contains relationship is using to express dependencies. No duplicate components are removed.
Flat	SPDX	It creates a flat list of all packages and files. It removes all relationships except the describes relationship
Assembly	SPDX	Similar to Hierarchical, except the contains relationship is omitted

A complete example/use-case

Interlynk produces a variety of closed-source tools that it offers to its customers. One of its security-conscious customers recognizes the importance of being diligent about the tools running on its network and has asked Interlynk to provide SBOMs for each tool. Interlynk has complied with this request by providing individual SBOMs for each tool it ships to the customer. However, the customer soon realizes that keeping track of so many SBOMs, which they receive at regular intervals, is challenging. To address this issue, the customer automates the process by combining all the SBOMs provided by Interlynk into a single SBOM, which they can monitor more easily using their preferred tool.

The customer uses sbomasm to help assemble these SBOMs. The input SBOMs are the following

├── sbom-tool
│   ├── sbomex-spdx.json
│   ├── sbomgr-spdx.json
│   └── sbomqs-spdx.json

To track all of these SBOMs, as a single unit, the first step will be to generate a config file, to capture the merged sbom details.

sbomasm generate > interlynk-config.yml

The config file is a yaml document, which needs to be filled out. All the [REQUIRED] files are necessary, the [OPTIONAL] can be left blank.

app:
  name: 'Interlynk combined set'
  version: 'v0.0.1'
  description: 'set of binaries recv on May 04 2023'
  author:
  - name: 'customer name'
    email: '[email protected]'
  primary_purpose: 'application'
  purl: '[OPTIONAL]'
  cpe: '[OPTIONAL]'
  license:
    id: '[OPTIONAL]'
  supplier:
    name: 'Interlynk'
    email: '[email protected]'
  checksum:
  - algorithm: '[OPTIONAL]'
    value: '[OPTIONAL]'
  copyright: '[OPTIONAL]'
output:
  spec: spdx
  file_format: json
assemble:
  include_dependency_graph: true
  include_components: true
  flat_merge: false
  hierarchical_merge: true

After saving the file, they run the following command sbomasm assemble -c interlynk-config.yml -o interlynk.combined-sbom.spdx.json samples/spdx/sbom-tool/*

The output is an assembled SBOM for all of interlynks binaries interlynk.combined-sbom.spdx.json. If everything is successful, the cli command, just writes the file, and nothing is displayed to the screen.

To get more details in case of issues or just information, run the above command with a debug flag sbomasm assemble -d -c interlynk-config.yml -o interlynk.combined-sbom.spdx.json samples/spdx/sbom-tool/*

2023-05-03T04:49:33.333-0700    DEBUG   assemble/config.go:313  sha256 samples/spdx/sbom-tool/sbomex-spdx.json : a0f1787b5f5b42861ec28f263be1e30c61782b7b0da1290403dedf64fffedb22
2023-05-03T04:49:33.337-0700    DEBUG   assemble/config.go:313  sha256 samples/spdx/sbom-tool/sbomgr-spdx.json : d0a0e2243b3fcaa376d95a7844c015547b98aaa5582cf740939d3fd78991a1f9
2023-05-03T04:49:33.342-0700    DEBUG   assemble/config.go:313  sha256 samples/spdx/sbom-tool/sbomqs-spdx.json : edf6fe76bb3836990d288b2a5c56d1d65aeb29b35b3f358d68ff0bd7833ce9d3
2023-05-03T04:49:33.342-0700    DEBUG   assemble/config.go:289  config &{ctx:0xc0000f7110 App:{Name:Interlynk combined set Version:v0.0.1 Description:set of binaries recv on May 04 2023 Author:[{Name:customer name Email:[email protected] Phone:}] PrimaryPurpose:application Purl: CPE: License:{Id: Expression:} Supplier:{Name:Interlynk Email:[email protected]} Checksums:[{Algorithm: Value:}] Copyright:} Output:{Spec:spdx FileFormat:json file:interlynk.combined-sbom.spdx.json} input:{files:[samples/spdx/sbom-tool/sbomex-spdx.json samples/spdx/sbom-tool/sbomgr-spdx.json samples/spdx/sbom-tool/sbomqs-spdx.json]} Assemble:{IncludeDependencyGraph:true IncludeComponents:true includeDuplicateComponents:true FlatMerge:false HierarchicalMerge:true}}2023-05-03T04:49:33.367-0700    DEBUG   assemble/combiner.go:50 combining 3 SPDX sboms
2023-05-03T04:49:33.378-0700    DEBUG   spdx/utils.go:53        loading bom:samples/spdx/sbom-tool/sbomex-spdx.json spec:spdx format:json
2023-05-03T04:49:33.440-0700    DEBUG   spdx/utils.go:53        loading bom:samples/spdx/sbom-tool/sbomgr-spdx.json spec:spdx format:json
2023-05-03T04:49:33.478-0700    DEBUG   spdx/utils.go:53        loading bom:samples/spdx/sbom-tool/sbomqs-spdx.json spec:spdx format:json
2023-05-03T04:49:33.523-0700    DEBUG   spdx/merge.go:114       No of Licenses: 1:  Selected:3.19
2023-05-03T04:49:33.523-0700    DEBUG   spdx/merge.go:222       primary component id: RootPackage-a3e525d1-1eca-4291-99fe-3f38223dca9b
2023-05-03T04:49:33.523-0700    DEBUG   spdx/merge.go:235       processing sbom DOCUMENT-github.com/interlynk-io/sbomex 0.0.3 with packages:74, files:1923, deps:1998, Snips:0 OtherLics:0, Annotations:0, externaldocrefs:0
2023-05-03T04:49:33.524-0700    DEBUG   spdx/merge.go:235       processing sbom DOCUMENT-github.com/interlynk-io/sbomgr 0.0.4 with packages:59, files:1004, deps:1064, Snips:0 OtherLics:0, Annotations:0, externaldocrefs:0
2023-05-03T04:49:33.525-0700    DEBUG   spdx/merge.go:235       processing sbom DOCUMENT-github.com/interlynk-io/sbomqs 0.0.14 with packages:68, files:1469, deps:1538, Snips:0 OtherLics:0, Annotations:0, externaldocrefs:0
2023-05-03T04:49:33.570-0700    DEBUG   spdx/merge.go:339       wrote sbom 3825558 bytes to interlynk.combined-sbom.spdx.json with packages:202, files:4396, deps:4598, snips:0 otherLics:0, annotations:0, externaldocRefs:0

The assembled SBOM can now be monitored using any SBOM monitoring tool of your choice. If you don't have one, contact us, we are building an SBOM monitor product to help with this.

Installation

Using Prebuilt binaries

https://github.com/interlynk-io/sbomasm/releases

Using Homebrew

brew tap interlynk-io/interlynk
brew install sbomasm

Using Go install

go install github.com/interlynk-io/sbomasm@latest

Using repo

This approach involves cloning the repo and building it.

1. Clone the repo git clone [email protected]:interlynk-io/sbomasm.git
2. cd into sbomasm folder
3. make; make build
4. To test if the build was successful run the following command ./build/sbomasm version

Contributions

We look forward to your contributions, below are a few guidelines on how to submit them

• Fork the repo
• Create your feature/bug branch (git checkout -b feature/bug)
• Commit your changes (git commit -aSm "awesome new feature") - commits must be signed
• Push your changes (git push origin feature/new-feature)
• Create a new pull-request

Other SBOM Open Source tools

• SBOM Quality Score - Quality & Compliance tool
• SBOM Search Tool - Search Tool
• SBOM Explorer - Discovering and downloading SBOM from a public repository
• SBOM Benchmark is a repository of SBOM and quality score for most popular containers and repositories

Contact

We appreciate all feedback. The best ways to get in touch with us:

• ❓& 🅰️ Slack
• ☎️ Live Chat
• 📫 Email Us
• 🐛 Report a bug or enhancement
• ❌ Follow us on X

Stargazers

If you like this project, please support us by starring it.

sbomasm's Issues

Add conversion functionality as requested

We should be able to ingest in SPDX docs and output cyclonedx and vice versa. This will be a lossy conversion, we should clearly document data lost in translation.

sbomasm creates invalid SPDX

Get the 3 SPDX files from https://github.com/spdx/spdx-examples/tree/master/software/example6/spdx2.2

These 3 files are valid SPDX.

Do:

sbomasm assemble -n merge -v 1 -t application -o merge.spdx.json *.spdx

Result is invalid SPDX:

pyspdxtools -i merge.spdx.json 
ERROR:root:The document is invalid. The following issues have been found:
document_ref_id must only contain letters, numbers, ".", "-" and "+" and must begin with "DocumentRef-", but is: hello-go-src
document_ref_id must only contain letters, numbers, ".", "-" and "+" and must begin with "DocumentRef-", but is: go-lib
verification_code must be None if files_analyzed is False, but is: PackageVerificationCode(value='', excluded_files=[])
verification_code must be None if files_analyzed is False, but is: PackageVerificationCode(value='', excluded_files=[])
verification_code must be None if files_analyzed is False, but is: PackageVerificationCode(value='', excluded_files=[])
verification_code must be None if files_analyzed is False, but is: PackageVerificationCode(value='', excluded_files=[])
verification_code must be None if files_analyzed is False, but is: PackageVerificationCode(value='', excluded_files=[])
did not find the referenced spdx_id "SPDXRef-hello-go-binary" in the SPDX document
did not find the external document reference "DocumentRef-hello-go-src" in the SPDX document
did not find the referenced spdx_id "SPDXRef-hello-go-binary" in the SPDX document
did not find the external document reference "DocumentRef-hello-go-src" in the SPDX document
did not find the external document reference "DocumentRef-go-lib" in the SPDX document
did not find the external document reference "DocumentRef-go-lib" in the SPDX document
did not find the external document reference "DocumentRef-go-lib" in the SPDX document
did not find the external document reference "DocumentRef-go-lib" in the SPDX document
did not find the external document reference "DocumentRef-go-lib" in the SPDX document
did not find the referenced spdx_id "SPDXRef-Makefile" in the SPDX document

sbomasm help includes default CLI messages

sbomasm help

A longer description that spans multiple lines and likely contains
examples and usage of using your application. For example:

Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.

Add support for PLB-SBOM based on CISA guidance

CISA has released a document, which proposes another way of assembling sboms for products. All the details are https://www.cisa.gov/resources-tools/resources/guidance-assembling-group-products

We will add support for PLB sboms to sbom-asm in feb.

https://medium.com/@interlynkblog/plb-sbom-or-how-to-assemble-sbom-for-a-group-of-products-cd58a4ec34ff

Generated SBOM is missing required field `type`

Actual Result
sbomasm assemble -n "mega cdx app" -v "1.0.0" -o final-product.cdx.json ../sbomlc/cdxgen-9.5.1_photon-latest.cdx.json ../sbomlc/cdxgen-9.5.1_piwik-latest.cdx.json

The resulting SBOM (attached) does not have type and therefore fails to parse.

final-product.cdx.json.txt

Expected Result
Warn users when type is unspecified while merging SBOMS

duplicate spdx_id

It is possible that different files contain the same package.

This is a toy example, but in real SBOMs (that I cannot provide for confidentiality reasons), it happens often.

You should create different spdx_ids, or create a single instance of the package if it is exactly the same in both files.

duplicate1.spdx.txt
duplicate2.spdx.txt

sbomasm assemble -n merge -v 1 -t application -o merge.spdx.json *.spdx

merge.spdx.json

pyspdxtools -i merge.spdx.json 
ERROR:root:The document is invalid. The following issues have been found:
every spdx_id must be unique within the document, but found the following duplicates: ['SPDXRef-Package-crypto-js']

Add DT integration.

The user should be able to configure multiple projects in DT which can be assembled into a single project. The user can then request to store it back into DT or the file system.

New version tool detection.

value in sbomasm assemble -t option is not checked

From the help page:

sbomasm assemble --help
Usage:
  sbomasm assemble [flags]

Flags:
  -t, --type string         product type of the assembled sbom (application, framework, library, container, device, firmware)

The string should be checked for the six allowed values.

Currently,

sbomasm assemble -n merge -v 1 -t foobar -o merge.spdx.json *.spdx

gives no error and produces invalid SPDX.

pyspdxtools -i merge.spdx.json
ERROR:root:There have been issues while parsing the provided document:
Error while parsing Package: ['Invalid PrimaryPackagePurpose: foobar']

Support CycloneDX 1.5

The CycloneDX specification was updated to version 1.5: https://cyclonedx.org/news/cyclonedx-v1.5-released/

And tools are already updating to support it, such as Trivy with its 0.43.0 release: https://github.com/aquasecurity/trivy/releases/tag/v0.43.0

Can this tool please also support the latest version of the CycloneDX specification?

LicenseListVersion creates invalid SPDX

example6-src.spdx.txt
example6-lib.spdx.txt
example6-bin.spdx.txt

sbomasm assemble -n merge -v 1 -t application -o merge.spdx.json *.spdx

Result:
merge.spdx.json

pyspdxtools -i merge.spdx.json 
ERROR:root:There have been issues while parsing the provided document:
Error while parsing Document: ['Error while parsing version 3.18.0: 3.18.0 is not a valid version string']

Also, there should be strategy to select the LicenseListVersion in case of different values in the input files.
I think the best strategy is to take the highest value (a lower value would not be good, possibly some used identifiers would not be present in the list).

missing referenced spdx_id in merge

main.spdx.txt
other.spdx.txt

sbomasm assemble -n merge -v 1 -t application -o merge.spdx.json *.spdx

merge.spdx.json

pyspdxtools -i merge.spdx.json 
ERROR:root:The document is invalid. The following issues have been found:
did not find the referenced spdx_id "SPDXRef-Package-other" in the SPDX document
did not find the referenced spdx_id "SPDXRef-Package-other" in the SPDX document

Update README about merge algorithms

We currently support two algorithm

• Hierarchical: This merge algo tries to maintain, the order of the dependent components to its primary component. For spdx this is done via relationships and for cyclonedx via nested components & dependencies.
• Flat: As the name states, are just consolidated lists of components, dependencies, etc.
• Assembly: Merge is very similar to Hierarchical, except that it does not create dependency relationships among the merged sboms.

This is three algorithms, not two.

You should add that Flat is not yet implemented.

What is the default algorithm, i.e. when -a, -fand -mare not used?

"primaryPackagePurpose": "application" is invalid

merge.spdx.json

"primaryPackagePurpose": "application" is invalid, it should be "primaryPackagePurpose": "APPLICATION"

See spdx/tools-python#812

But this is an optional attribute, I would drop it. It was not present in the original files, so I cannot see how you can deduce it.

sbomasm does not work without internet connection

Without internet connect, I get:

sbomasm assemble -n merge -v 1 -t application -o merge.spdx.json *.spdx
panic: Get "https://api.github.com/repos/interlynk-io/sbomasm/releases/latest": proxyconnect tcp: dial tcp xxx.xxxx.xxx.xxx:8000: connect: network is unreachable

goroutine 1 [running]:
github.com/interlynk-io/sbomasm/cmd.checkIfLatestRelease()
	github.com/interlynk-io/[email protected]/cmd/root.go:71 +0x1b8
github.com/interlynk-io/sbomasm/cmd.Execute()
	github.com/interlynk-io/[email protected]/cmd/root.go:43 +0x1c
main.main()
	github.com/interlynk-io/[email protected]/main.go:19 +0x1c

Why does sbomasm need internet connection? Only to check if we have the latest release?
Is the content of the input files sent to Interlynk? That would cause confidentiality issues.

Merge multiple DT projects

As a user of DT, i would like to provide sbomasm with multiple project ids and it should merge it and output it either to a file or to another DT project.

Hierarchical merges assumes dependencies. Should it not allow simple containment

It seems like a hierarchical merge will always generate dependency data forcing the merged sboms to become nodes in the resulting sbom dependency tree. On the level above the individual sboms dependency trees.

Many systems (like Dependency Track) makes the assumption that the top level in the dependency tree is the application direct dependencies.

However if an application is stitched together from multiple (unrelated) components it makes no sense to claim that there is a dependency relationship between the combined application and the components. Here the relationship is simply a containment.

If this was changed applications like DT would again be able to rely on the top level in the dependency tree being the direct dependencies.

At least it should be an option to allow this distinction between containment and dependency.

Containerize sbomasm and host on ghcr

Need to provide sbomasm as a container, and hosted on ghcr. This should ease integration.

Document these steps in the README

sbomasm version displays the default short description

sbomasm version
  ____    ____     ___    __  __      _      ____    __  __
 / ___|  | __ )   / _ \  |  \/  |    / \    / ___|  |  \/  |
 \___ \  |  _ \  | | | | | |\/| |   / _ \   \___ \  | |\/| |
  ___) | | |_) | | |_| | | |  | |  / ___ \   ___) | | |  | |
 |____/  |____/   \___/  |_|  |_| /_/   \_\ |____/  |_|  |_|
sbomasm: A brief description of your application

sbomasm should refuse to merge a single file

If you provide a single input file, sbomasm will create a new file that is more complex than the original file as it will contain one more package "merge".

I do not see the purpose of this.

sbomasm should refuse to merge a single file.

invalid verification_code

test.spdx.txt

sbomasm assemble -n merge -v 1 -t application -o merge.spdx.json test.spdx

merge.spdx.json

pyspdxtools -i merge.spdx.json 
ERROR:root:The document is invalid. The following issues have been found:
value of verification_code must consist of 40 lowercase hexadecimal digits, but is:  (length: 0 digits)
value of verification_code must consist of 40 lowercase hexadecimal digits, but is:  (length: 0 digits)

  {
   "name": "464xlat",
   "SPDXID": "SPDXRef-Package-464xlat",
   "versionInfo": "12",
   "supplier": "Organization: ACME",
   "downloadLocation": "https://github.com/openwrt/openwrt/tree/openwrt-21.02/package/network/ipv6/464xlat",
   "filesAnalyzed": true,
   "packageVerificationCode": {
    "packageVerificationCodeValue": ""
   },
   "licenseConcluded": "GPL-2.0-only",
   "licenseDeclared": "GPL-2.0-only",
   "copyrightText": "NOASSERTION"
  }

Why creating a verification code as it does not exist in the original file?