This case study is split into the following parts:
- About Our Author
- Choosing the OpenChain Telco SBOM Guide
- Structure Of This Case Study
- Definitions / Specifications
- Schema Considerations
- Tooling for Implementation
- A Practical Example
- Conclusion and Future Work
About Our Author:
David (Dongwei) Liu is a Research and Development (R&D) Engineer in ByteDance with a focus on Open Source and Software Supply Chain Security and Compliance. His personal interests include 3D Printing Technology (including the making 3D Printing Machines). He can be found on GitHub at https://github.com/ammend
Mental Model Applied To This Case Study:
This is a case study explaining how to use the OpenChain Telco SBOM Guide to improve the quality of SBOMs in deployment. It is approached from the perspective of real-world use inside a company, and contains some technical descriptions to help with automation. The workflow described can be visualized in the following image:
Definitions / Specifications:
It is important to start with definitions around the topic of SBOMs. Having formal definitions, identifying types, and so on allows us to establish specifications for developing a solution.
Defining SBOM:
This case study is focused on Software Bill of Materials (SBOM). In this case study, we define an SBOM as a formal record that lists all the components, libraries, and subsystems that are included in a given software product or system. It provides transparency about what is “inside” a product and allows others to better understand its composition. Well-known SBOM formats include SPDX and CycloneDX.
SBOM Type:
We found there are two different kinds of SBOM type. One is primary SBOM type, which means the SBOM is used for describing product purpose. Another is generative type, which means the generating period of the SBOM of the product.
Primary SBOM in SPDX:
Primary SBOM in CycloneDX:
Generative SBOMs according to CISA:
We record both of these types in our database.
SBOM Core Elements:
SPDX:
NTIA SBOM:
Choosing the OpenChain Telco SBOM Guide:
The OpenChain Telco SBOM Guide was developed for a considerable period through the OpenChain Telco Work Group before reaching 1.0 status in 2024. A few factors came into play when selecting the OpenChain Telco SBOM Guide version 1.0 as the basis of our work:
- It is SPDX Compatible and meets the NTIA Minimum Elements For a Software Bill of Materials
- It is complementary to the OpenChain ISO/IEC 5230 standard
- It supports tag/value and JSON output
- It is freely available on GitHub
- Its structure can be used as a declarable community specification
- It was developed openly by and for the community
Perhaps most importantly, the structure of the OpenChain Telco SBOM Guide means there is no need for repeated SBOM information supplements from other participants in the supply chain.
Schema Considerations:
Requirement Levels:
We used IETF RFC 2119 as the basis of our definitions. The key words defined are “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL”.
A schema is a technology validator to verify output data in these terms. The influence of the data field can be shown below.
- Field existence. This means there may be a field in target data.
- Field mandatory. This means there must be a field in target data
OpenChain Telco SBOM Guide JSON Schema:
The JSON Schema Result:
Generating Process:
This works in progress. The process of generating JSON schema of the Guide from scratch can be shown below.
Why is there a schema fixing stage for SPDX?
We discovered that the official JSON schema implementations in SPDX GitHub were not consistent with the official SPDX specifications. We submitted Pull Requests to the official SPDX GitHub project that have been adopted as a fix for the 2.3.1 milestone. See https://github.com/spdx/spdx-spec/pull/1020 and https://github.com/spdx/spdx-spec/pull/1021.
In a situation where such bugs exist, doing a fix is both an effective method of implementing a solution, and providing a case study to address a broken feature or add functionality.
In our case, we focused on arranging the order of fields in implementation according to the order of fields in official specifications to make things more human-readable. In the original JSON schema implementation of SPDX the orders of fields was inconsistent.
Differences between the OpenChain Telco SBOM Guide 1.0 and SPDX 2.3:
The differences we identified between Open Chain Telco SBOM Guide and SPDX 2.3 are:
- For the OpenChain Telco SBOM Guide, the field comment in field createInfo is declared as mandatory;
- The field copyrightText, licenseConcluded, licenseDeclared, supplier, versionInfo in field packages are declared as mandatory;
- It adds descriptions into some fields json schema;
- And it has a revised $id and title.
This is illustrated below:
Plain Text
internal $ python3 json_schema_compare.py -f ../openchain-telco-sbom-guide-1.0-schema.json spdx-v2.3-fix-schema.jso
n
{
"field_mandatory_comparison": {
"more_fields": [
"doc(object)->creationInfo(object)->comment",
"doc(object)->packages(array)->packages_item(object)->copyrightText",
"doc(object)->packages(array)->packages_item(object)->licenseConcluded",
"doc(object)->packages(array)->packages_item(object)->licenseDeclared",
"doc(object)->packages(array)->packages_item(object)->supplier",
"doc(object)->packages(array)->packages_item(object)->versionInfo"
]
},
"field_existence_comparison": {}
}
Tooling for Implementation:
Introduction:
An SBOM tool enables automatic generation of SBOM records. Specifically, they tend to:
- Scan local files to generate basic SBOM information like hash, version, package dependencies and relationships
- Then cross-check with trusted external component license and security sources.
- With a focus on package license info and package security info
Many opensource tools do the first job, such as syft and cycloneDX CLI. Some examples can be found at this link: https://spdx.dev/use/tools/open-source-tools/
OpenChain Telco SBOM Guide Tool:
We have extended the Syft tool to support OpenChain Telco SBOM Guide. Syft is a CLI tool and library for generating a Software Bill of Materials from container images and filesystems. Our contribution can be found here: https://github.com/ammend/syft.
To run Syft for the OpenChain Telco SBOM Guide the following command is used:
SQL
./syft scan golang_example -o octsg-json@1.0 --file golang_example.sbom.json
“octsg-json” is abbreviation of OpenChain Telco SBOM Guide JSON Schema
A Practical Example:
Context:
We develop customized tools in ByteDance to collect dependencies of different kinds of artifacts. Below we will present an example using Golang. All of the example code is maintained at: https://github.com/ammend/openchain-telco-guide-examples
Golang Example:
Our SBOM example was created in a project called golang_example:
Our example used a web framework called gin and provided the analyzed SBOM result as shown below. In the code we only ask to import 1 third-party dependency, yet in total we import 19 dependencies. This is why code review and clear processes are important.
Package level:
File Level:
Relationship Level:
Conclusion and Future Work:
Questions for the future include:
- How to build a trusted source or upstream
- How to address situations of NOASSERTION when it comes to licenses, as outputs from Syft are not sufficient to cover this use case
- How to build a trusted source codebase from commercial or community tools
- How to improve the use of SBOM and potentially the scope of their use
- How to refine the type of declaration used for external commercial purposes
- How to refine governance for internal development
- How to create effective upstream contribution workflows
If you want to know more, we can talk to each other via GitHub or through the OpenChain China Work Group WeChat Group.
Note: ByteDance activity extends beyond being a user of the Telco SBOM Guide. David (Dongwei) Liu has also contributed a schema for the Telco SBOM Guide 1.0 which is merged into the official OpenChain Telco Work Group GitHub.
