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