Maximilian Brune has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/68995 )
Change subject: Documentation/sbom: Add SBOM Documentation ......................................................................
Documentation/sbom: Add SBOM Documentation
Change-Id: I39fbcba60a0fbdbed9f662119ed7692c0a0fd30e --- M Documentation/index.md A Documentation/sbom/sbom.md A Documentation/sbom/sbom_generation.plantuml A Documentation/sbom/sbom_generation.png 4 files changed, 99 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/95/68995/1
diff --git a/Documentation/index.md b/Documentation/index.md index 0cb462c..416883b 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -193,6 +193,7 @@ * [SuperIO](superio/index.md) * [Vendorcode](vendorcode/index.md) * [Utilities](util.md) +* [Software Bill of Materials](sbom/sbom.md) * [Project infrastructure & services](infrastructure/index.md) * [Boards supported in each release directory](releases/boards_supported_on_branches.md) * [Release notes](releases/index.md) diff --git a/Documentation/sbom/sbom.md b/Documentation/sbom/sbom.md new file mode 100644 index 0000000..caf0f69 --- /dev/null +++ b/Documentation/sbom/sbom.md @@ -0,0 +1,28 @@ +# SBOM (Software Bill of Materials) +SBOM is simply a collection of Information of each Software component you are supplying/building. Similar to a package manager on Linux based Systems, it holds Information of as much Software parts as possible. These Information can be a Version, Name of the software, URL, License Information and more. An SBOM can be saved in various formats. In coreboot it's saved as "uSWID" File. uSWID is not a Standard or Specification but it doesn't need to be, since it's basically just an Array/List of CoSWID Files which in turn are specified by a RFC Spec. CoSWID Files are saved in a CBOR Format. CBOR is like JSON if JSON would be binary format. Similar to a package manager the CoSWID Format can link multiple Software's together. For example on most modern Intel Systems FSP is shipped as a dependency of coreboot. That kind of relationship between Software components (among others) can be expressed in an uSWID File. That makes Firmware/Software much more transparent. One could for example create a Software that takes a Coreboot Firmware Image as Input and automatically creates a Graph with all Software components the Coreboot Image contains and their relationship to each other. + +## SWID/CoSWID File Format +To get a simple overview of how a SWID/CoSWID File looks like, just take a look at the various "templates" in src/sbom/. + +## coreboot implementation +Quick overview of how things are generated: + +![Generation of an SBOM File in coreboot][sbom_generation] + +[sbom_generation]: sbom_generation.png + +After all SBOM data has been fetched from all the software-components, the 'goswid' tool links them all together into one sbom.uswid file. The goswid tool is therefore basically a linker that takes multiple CoSWID/SWID files and converts them into one uSWID File. Although the Image shows only Files in JSON Format it is also possible to supply them in XML or CBOR Format. + +The final SBOM File is located inside the CBFS. +For each Software component in coreboot SBOM, there is an option in Kconfig (usually called CONFIG_INCLUDE_[software-name]_SBOM] to either include or not include SBOM metadata for the specified Software. Furthermore there is a a CONFIG_SBOM_[software-name]_PATH option which contains a path to a SWID/CoSWID File in a Format of choice (being either JSON, XML or CBOR). CONFIG_SBOM_[software-name]_PATH option usually defaults to a very generic CoSWID file in JSON format (which are stored in src/sbom/). That at least gives minimal information like the name of the software and maybe a version. But it is always preferred, that the CONFIG_SBOM_[software-name]_PATH is set to a custom CoSWID/SWID file that contains much more information (like License, URL, version/commit-hash ...). Therefore using the defaults is by any means to be avoided, since they hold very little information or even worse wrong information. +Furthermore some of these Kconfig options have a suboption (usually called CONFIG_[software-name]_SBOM_GENEREATE) to generate some basic SBOM data for the specified Software component, in order to get at least some bit of information about it by analyzing the binary (for binary blobs) or querying Information via git (for open source projects). This is for example currently done for all payloads. For each payload the commit hash used in the build is taken and put into the SBOM File. For open-source projects (like all payloads) crucial information like the current commit-hash of the payload can easily be put into the SBOM file. Extracting Information out of Binary blobs is a bit trickier for obvious reasons. +For closed source binary blobs it is therefore recommended that Vendors/Software-Engineers create an SBOM File as part of their build process and add a path to that SBOM File via Kconfig options in coreboot (usually called CONFIG_[software-name]_SBOM_PATH). That way the final SBOM has much more useful and correct data. + +## What to do as Developer of a binary blob (which is used in coreboot) +1. Generate a SWID/CoSWID/uSWID File in either JSON, XML or CBOR Format as part of your Software build process +2. Supply that generated File along with your binary blob +3. To build coreboot: Add CONFIG_SBOM_[software-name]_PATH to your defconfig pointing to your [software-name] generated File. + +## What to do as Developer of an open source project (which is used in coreboot) +1. Generate a SWID/CoSWID/uSWID File in either JSON, XML or CBOR Format as part of your Software's build process. for example in form of a Makefile target. +2. Change src/sbom/Makefile.inc (in order to know where to find the CoSWID/SWID/uSWID File) as well as the Makefile in coreboot which builds said Software. For example for GRUB2 that could mean to add a Makefile target in payloads/external/GRUB2/Makefile. diff --git a/Documentation/sbom/sbom_generation.plantuml b/Documentation/sbom/sbom_generation.plantuml new file mode 100644 index 0000000..e8d9f1e --- /dev/null +++ b/Documentation/sbom/sbom_generation.plantuml @@ -0,0 +1,61 @@ +@startuml + +map "src/sbom/compiler-gcc.json" as gcc { + software-name => GCC + version => x.y.z + ... => ... +} +map "src/sbom/intel-me.json" as me { + software-name => Intel Mangement Engine + ... => ... +} +map "src/sbom/intel-microcode.json" as ucode { + software-name => Intel Microcode + ... => ... +} +map "src/sbom/generic-ec.json" as ec { + software-name => ecxyz + ... => ... +} +map "src/sbom/generic-fsp.json" as fsp { + software-name => Firmware Support Package + version => x.y.z + ... => ... +} +map "src/sbom/payload-[...].json" as payload { + software-name => ... + version => x.y.z + ... => ... +} +map "src/sbom/coreboot.json" as coreboot { + software-name => coreboot + version => x.y.z + url => coreboot.rocks + ... => ... +} +object "sbom.uswid" as uswid { + merged SBOM data in binary format +} +object goswid { + # ./goswid + --compiler gcc.json + --parent coreboot.json + --requires fsp.json,payload.json + intel-me.json + intel-ec.json + intel-ucode.json + --output sbom.uswid +} + +left to right direction +gcc --> goswid +me --> goswid +ucode --> goswid +goswid <-- ec +goswid <-- fsp +goswid <-- payload + +coreboot -up> goswid +goswid -up> uswid + +@enduml diff --git a/Documentation/sbom/sbom_generation.png b/Documentation/sbom/sbom_generation.png new file mode 100644 index 0000000..7489735 --- /dev/null +++ b/Documentation/sbom/sbom_generation.png Binary files differ