Documentation/sbom/sbom.md

   1 # Software Bill of Materials (SBOM)
   2
   3 SBOM is a collection of information of each software component
   4 you are supplying/building. Similar to a package manager on Linux
   5 based systems, it holds information of as many software parts as
   6 possible. This information can be a version, name of the software, URL,
   7 license information and more. A SBOM can be saved in various formats.
   8 In coreboot it's saved as "uSWID" file. uSWID is not a standard or
   9 specification but it doesn't need to be, since it's basically just an
  10 array/list of CoSWID (Concise Software Identification) files which in
  11 turn are specified by a RFC specification. CoSWID files are saved in a
  12 CBOR format. CBOR is like JSON if JSON were a binary format. Similar
  13 to a package manager the CoSWID format can link multiple softwares
  14 together. For example on most modern Intel systems FSP is included as
  15 a dependency of coreboot. That kind of relationship between software
  16 components (among others) can be expressed in an uSWID file. That makes
  17 firmware/software much more transparent. One could for example create a
  18 software that takes a coreboot firmware image as input and
  19 automatically creates a graph with all software components the coreboot
  20 image contains and their relationship to each other.
  21
  22
  23 ## SWID/CoSWID
  24
  25 SWID is a standard hidden behind an ISO paywall.
  26 It generally identifies/describes Software components. Since SWID files
  27 are written in XML, they can get too large for devices with network and
  28 storage constraints. CoSWID is basically SWID but in CBOR binary
  29 format, which makes it far smaller compared to its big brother. Also,
  30 CoSWID is a RFC specification (so publicly accessible). Therefore
  31 CoSWID is the standard used in coreboot SBOM. But one CoSWID file/tag
  32 can only describe one single software, but since software is usually
  33 composed of multiple parts (especially in firmware with many binary
  34 blobs) uSWID was born as a container format to hold multiple CoSWID
  35 files. It also has a magic value, that makes software capable of
  36 extracting uSWID/CoSWID data without the need to understand the
  37 underlying format of the binary (in coreboot it's the CBFS and in EDK2
  38 it's the COFF). To get a simple overview of how a SWID/CoSWID file
  39 looks like, just take a look at the various "templates" in src/sbom/.
  40 There are of course other SBOM specifications out there, but most of
  41 them are rather blown up and don't support a binary format at all.
  42
  43
  44 ## coreboot implementation
  45
  46 Quick overview of how things are generated:
  47
  48 ![Generation of an SBOM File in coreboot][sbom_generation]
  49
  50 [sbom_generation]: sbom_generation.svg
  51
  52 After all SBOM data has been fetched from all the software components,
  53 the 'goswid' tool links them all together into one sbom.uswid file.
  54 Therefore the goswid tool is basically a linker that takes multiple
  55 CoSWID/SWID files and converts them into one uSWID file. Although the
  56 image shows only Files in JSON format it is also possible to supply
  57 them in XML or CBOR format.
  58
  59 The final SBOM file is located inside the CBFS.
  60 For each software component in coreboot SBOM, there is an option in
  61 Kconfig (usually called `CONFIG_INCLUDE_[software-name]_SBOM`) to either
  62 include or not include SBOM metadata for the specified software.
  63 Furthermore there is a `CONFIG_SBOM_[software-name]_PATH` option which
  64 contains a path to a SWID/CoSWID file in a format of choice
  65 (being either JSON, XML or CBOR). `CONFIG_SBOM_[software-name]_PATH`
  66 option usually defaults to a very generic CoSWID file in JSON format
  67 (which are stored in src/sbom/). That at least gives minimal
  68 information like the name of the software and maybe a version.
  69 But it is always preferred, that the `CONFIG_SBOM_[software-name]_PATH`
  70 is set to a custom CoSWID/SWID file that contains much more information
  71 (like version/commit-hash, license, URL, dependencies, ...).
  72 Therefore using the defaults is by any means to be avoided, since they
  73 hold very little information or even worse wrong information.
  74 Furthermore some of these Kconfig options have a suboption
  75 (usually called `CONFIG_SBOM_[software-name]_GENERATE`) to generate
  76 some basic SBOM data for the specified software component, in order to
  77 get at least some bit of information about it by analyzing the binary
  78 (for binary blobs) or querying information via git (for open source
  79 projects). This is for example currently done for all payloads. For
  80 each payload the commit hash used in the build is taken and put into
  81 the SBOM file. For open-source projects (like all payloads) crucial
  82 information like the current commit-hash of the payload can easily be
  83 put into the SBOM file. Extracting information out of binary blobs is a
  84 bit trickier for obvious reasons. For closed source binary blobs it is
  85 therefore recommended that vendors and software-engineers create a SBOM
  86 file as part of their build process and add a path to that SBOM file
  87 via Kconfig options in coreboot (`CONFIG_SBOM_[software-name]_PATH`).
  88 That way the final SBOM has much more useful and correct data.
  89
  90
  91 ## Build coreboot with SBOM
  92
  93 Directly under the 'General setup' Kconfig menu is a
  94 'Software Bill of Materials (SBOM)' submenu where all options are to
  95 enable/disable SBOM integration in to the corebeoot build.
  96 Therefore one can just enable/disable them via `make menuconfig`.
  97
  98
  99 ## What to do as Developer of a binary blob (which is used in coreboot)
 100
 101 1. Generate a SWID/CoSWID/uSWID File in either JSON, XML or CBOR Format
 102 as part of your software build process
 103
 104 2. Supply that generated File along with your binary blob (preferably
 105 not inside the blob)
 106
 107 3. To build coreboot: Add `CONFIG_SBOM_[software-name]_PATH` to your
 108 defconfig pointing to your [software-name] generated File.
 109
 110
 111 ## What to do as Developer of an open source project (which is used in coreboot)
 112
 113 1. Generate a SWID/CoSWID/uSWID file in either JSON, XML or CBOR format
 114 as part of your software's build process. For example in form of a
 115 Makefile target.
 116
 117 2. Change src/sbom/Makefile.mk (in order to know where to find the
 118 CoSWID/SWID/uSWID file) as well as the Makefile in coreboot which
 119 builds said software. For example for GRUB2 that could mean to add a
 120 Makefile target in payloads/external/GRUB2/Makefile.
 121
 122
 123 ## Problems
 124
 125 What to do if the binary blob that is included in coreboot's build
 126 already has a SBOM file embedded in the binary? One could supply the
 127 path of the software binary itself (e.g. me.bin) as SBOM file path for
 128 the software in question. Which would basically mean to set
 129 `CONFIG_SBOM_[software-name]_PATH=/path/to/me.bin`. This is possible
 130 since the 'goswid' tooling is able to extract uSWID information out of
 131 an unknown binary format because of uSWIDs magic value. But even if
 132 coreboot can extract the uSWID data there is still the question of what
 133 to do next. One can do one of the following:
 134
 135   - Do not include the Software's SBOM data in the final SBOM of
 136     coreboot. Data would not be duplicated, but therefore not included
 137     in coreboot SBOM file.
 138
 139   - Extract the uSWID/CoSWID information from the binary and also
 140     include it in the coreboot SBOM. That would mean, that SBOM data
 141     is duplicated.
 142
 143 The first solution should in general be preferred, since its no
 144 problem if SBOM data is located at multiple locations/binaries if they
 145 don't have a direct dependency on each other. It would be good if
 146 software that cannot run on its own only supplies the SBOM data along
 147 with it as kind of extra file instead of embedded in an unknown binary
 148 blob. coreboot can then just take it and include it in its own SBOM
 149 file. If on the other hand the binary can function on its own (e.g. EC
 150 or BMC binary), it is generally preferred that the software supplies
 151 its own SBOM data and coreboot just simply doesn't include it in its
 152 own SBOM file. That would make a more or less clear distinction and
 153 avoids duplication in case the BMC or EC is updated (without updating
 154 coreboot). The distinction is not always easy and this problem is
 155 currently not considered in the implementation, since none of the
 156 software components currently create a SBOM file on their own.