diff options
Diffstat (limited to 'documentation/dev-manual/sbom.rst')
| -rw-r--r-- | documentation/dev-manual/sbom.rst | 83 |
1 files changed, 83 insertions, 0 deletions
diff --git a/documentation/dev-manual/sbom.rst b/documentation/dev-manual/sbom.rst new file mode 100644 index 0000000000..b72bad1554 --- /dev/null +++ b/documentation/dev-manual/sbom.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +Creating a Software Bill of Materials +************************************* + +Once you are able to build an image for your project, once the licenses for +each software component are all identified (see +":ref:`dev-manual/licenses:working with licenses`") and once vulnerability +fixes are applied (see ":ref:`dev-manual/vulnerabilities:checking +for vulnerabilities`"), the OpenEmbedded build system can generate +a description of all the components you used, their licenses, their dependencies, +their sources, the changes that were applied to them and the known +vulnerabilities that were fixed. + +This description is generated in the form of a *Software Bill of Materials* +(:term:`SBOM`), using the :term:`SPDX` standard. + +When you release software, this is the most standard way to provide information +about the Software Supply Chain of your software image and SDK. The +:term:`SBOM` tooling is often used to ensure open source license compliance by +providing the license texts used in the product which legal departments and end +users can read in standardized format. + +:term:`SBOM` information is also critical to performing vulnerability exposure +assessments, as all the components used in the Software Supply Chain are listed. + +The OpenEmbedded build system doesn't generate such information by default. +To make this happen, you must inherit the +:ref:`ref-classes-create-spdx` class from a configuration file:: + + INHERIT += "create-spdx" + +Upon building an image, you will then get: + +- :term:`SPDX` output in JSON format as an ``IMAGE-MACHINE.spdx.json`` file in + ``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`. + +- This toplevel file is accompanied by an ``IMAGE-MACHINE.spdx.index.json`` + containing an index of JSON :term:`SPDX` files for individual recipes. + +- The compressed archive ``IMAGE-MACHINE.spdx.tar.zst`` contains the index + and the files for the single recipes. + +The :ref:`ref-classes-create-spdx` class offers options to include +more information in the output :term:`SPDX` data: + +- Make the json files more human readable by setting (:term:`SPDX_PRETTY`). + +- Add compressed archives of the files in the generated target packages by + setting (:term:`SPDX_ARCHIVE_PACKAGED`). + +- Add a description of the source files used to generate host tools and target + packages (:term:`SPDX_INCLUDE_SOURCES`) + +- Add archives of these source files themselves (:term:`SPDX_ARCHIVE_SOURCES`). + +Though the toplevel :term:`SPDX` output is available in +``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`, ancillary +generated files are available in ``tmp/deploy/spdx/MACHINE`` too, such as: + +- The individual :term:`SPDX` JSON files in the ``IMAGE-MACHINE.spdx.tar.zst`` + archive. + +- Compressed archives of the files in the generated target packages, + in ``packages/packagename.tar.zst`` (when :term:`SPDX_ARCHIVE_PACKAGED` + is set). + +- Compressed archives of the source files used to build the host tools + and the target packages in ``recipes/recipe-packagename.tar.zst`` + (when :term:`SPDX_ARCHIVE_SOURCES` is set). Those are needed to fulfill + "source code access" license requirements. + +See also the :term:`SPDX_CUSTOM_ANNOTATION_VARS` variable which allows +to associate custom notes to a recipe. +See the `tools page <https://spdx.dev/resources/tools/>`__ on the :term:`SPDX` +project website for a list of tools to consume and transform the :term:`SPDX` +data generated by the OpenEmbedded build system. + +See also Joshua Watt's presentations +`Automated SBoM generation with OpenEmbedded and the Yocto Project <https://youtu.be/Q5UQUM6zxVU>`__ +at FOSDEM 2023 and +`SPDX in the Yocto Project <https://fosdem.org/2024/schedule/event/fosdem-2024-3318-spdx-in-the-yocto-project/>`__ +at FOSDEM 2024. |