blob: f51d08f84daf8064033fc3719cfb14ae9eecdb08 [file] [log] [blame]
Andrew Geissler517393d2023-01-13 08:55:19 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Creating a Software Bill of Materials
4*************************************
5
6Once you are able to build an image for your project, once the licenses for
7each software component are all identified (see
8":ref:`dev-manual/licenses:working with licenses`") and once vulnerability
9fixes are applied (see ":ref:`dev-manual/vulnerabilities:checking
10for vulnerabilities`"), the OpenEmbedded build system can generate
11a description of all the components you used, their licenses, their dependencies,
12their sources, the changes that were applied to them and the known
13vulnerabilities that were fixed.
14
15This description is generated in the form of a *Software Bill of Materials*
16(:term:`SBOM`), using the :term:`SPDX` standard.
17
18When you release software, this is the most standard way to provide information
19about the Software Supply Chain of your software image and SDK. The
20:term:`SBOM` tooling is often used to ensure open source license compliance by
21providing the license texts used in the product which legal departments and end
22users can read in standardized format.
23
24:term:`SBOM` information is also critical to performing vulnerability exposure
25assessments, as all the components used in the Software Supply Chain are listed.
26
27The OpenEmbedded build system doesn't generate such information by default.
28To make this happen, you must inherit the
29:ref:`ref-classes-create-spdx` class from a configuration file::
30
31 INHERIT += "create-spdx"
32
33You then get :term:`SPDX` output in JSON format as an
34``IMAGE-MACHINE.spdx.json`` file in ``tmp/deploy/images/MACHINE/`` inside the
35:term:`Build Directory`.
36
37This is a toplevel file accompanied by an ``IMAGE-MACHINE.spdx.index.json``
38containing an index of JSON :term:`SPDX` files for individual recipes, together
39with an ``IMAGE-MACHINE.spdx.tar.zst`` compressed archive containing all such
40files.
41
42The :ref:`ref-classes-create-spdx` class offers options to include
43more information in the output :term:`SPDX` data, such as making the generated
44files more human readable (:term:`SPDX_PRETTY`), adding compressed archives of
45the files in the generated target packages (:term:`SPDX_ARCHIVE_PACKAGED`),
46adding a description of the source files used to generate host tools and target
47packages (:term:`SPDX_INCLUDE_SOURCES`) and adding archives of these source
48files themselves (:term:`SPDX_ARCHIVE_SOURCES`).
49
50Though the toplevel :term:`SPDX` output is available in
51``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`, ancillary
52generated files are available in ``tmp/deploy/spdx/MACHINE`` too, such as:
53
54- The individual :term:`SPDX` JSON files in the ``IMAGE-MACHINE.spdx.tar.zst``
55 archive.
56
57- Compressed archives of the files in the generated target packages,
58 in ``packages/packagename.tar.zst`` (when :term:`SPDX_ARCHIVE_PACKAGED`
59 is set).
60
61- Compressed archives of the source files used to build the host tools
62 and the target packages in ``recipes/recipe-packagename.tar.zst``
63 (when :term:`SPDX_ARCHIVE_SOURCES` is set). Those are needed to fulfill
64 "source code access" license requirements.
65
Patrick Williams8e7b46e2023-05-01 14:19:06 -050066See also the :term:`SPDX_CUSTOM_ANNOTATION_VARS` variable which allows
67to associate custom notes to a recipe.
68
Andrew Geissler517393d2023-01-13 08:55:19 -060069See the `tools page <https://spdx.dev/resources/tools/>`__ on the :term:`SPDX`
70project website for a list of tools to consume and transform the :term:`SPDX`
71data generated by the OpenEmbedded build system.
72
Andrew Geissler6aa7eec2023-03-03 12:41:14 -060073See also Joshua Watt's
74`Automated SBoM generation with OpenEmbedded and the Yocto Project <https://youtu.be/Q5UQUM6zxVU>`__
75presentation at FOSDEM 2023.