diff mbox series

[12/18] ref-manual: document the sbom-cve-check class, fragment, and variables

Message ID 20260410-second-release-notes-6-0-v1-12-40213436c3ca@bootlin.com
State New
Headers show
Series Updates for upcoming Wrynose release | expand

Commit Message

Antonin Godard April 10, 2026, 2:43 p.m. UTC
Added by commit 8ef22ad9e302 ("sbom-cve-check: Add class for
post-build CVE analysis") in OE-Core.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/classes.rst   | 55 ++++++++++++++++++++++++++++++++++
 documentation/ref-manual/fragments.rst | 20 +++++++++++++
 documentation/ref-manual/variables.rst | 38 +++++++++++++++++++++++
 3 files changed, 113 insertions(+)
diff mbox series

Patch

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index d29339491..5a119da71 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -2760,6 +2760,61 @@  configuration checks from the ``local.conf`` configuration file to
 prevent common mistakes that cause build failures. Distribution policy
 usually determines whether to include this class.
 
+.. _ref-classes-sbom-cve-check:
+
+``sbom-cve-check``
+==================
+
+The :ref:`ref-classes-sbom-cve-check` class uses the `sbom-cve-check
+<github.com/bootlin/sbom-cve-check>`__ command-line tool for post-build CVE
+analysis. It relies on the :ref:`ref-classes-create-spdx` class as SPDX files
+are the input of this tool.
+
+This class should be enabled through the :ref:`ref-fragments-core-yocto-sbom-cve-check`
+fragment:
+
+.. code-block:: console
+
+   $ bitbake-config-build enable-fragment core/yocto/sbom-cve-check
+
+After building an image, ``sbom-cve-check`` will generate one or more reports in
+the :term:`DEPLOY_DIR_IMAGE` directory depending on the current value of
+:term:`SBOM_CVE_CHECK_EXPORT_VARS`.
+
+See the variables starting with ``SBOM_CVE_CHECK_`` in the :doc:`Yocto Project
+Reference Manual glossary </ref-manual/variables>` to learn more on how to
+configure the behavior of this class.
+
+.. _ref-classes-sbom-cve-check-recipe:
+
+``sbom-cve-check-recipe``
+=========================
+
+The :ref:`ref-classes-sbom-cve-check-recipe` class uses the `sbom-cve-check
+<github.com/bootlin/sbom-cve-check>`__ command-line tool for post-build CVE
+analysis of a recipe. It relies on the :ref:`ref-classes-create-spdx` class as
+SPDX files are the input of this tool.
+
+This class can be inherited in any recipe. Compared to the
+:class:`ref-classes-sbom-cve-check` class, this class only uses the SBOM of the
+recipe (after the ``create_recipe_sbom`` is run) to determine which is the
+underlying software and do the analysis, meaning that building the recipe itself
+isn't necessary.
+
+To use this class, inherit it in the recipe and run:
+
+.. code-block:: console
+
+   $ bitbake <recipe> -c sbom_cve_check_recipe
+
+After running the command, ``sbom-cve-check`` will generate one or more reports
+in the :term:`DEPLOY_DIR_IMAGE` directory depending on the current value of
+:term:`SBOM_CVE_CHECK_EXPORT_VARS`.
+
+See the variables starting with ``SBOM_CVE_CHECK_`` in the :doc:`Yocto Project
+Reference Manual glossary </ref-manual/variables>` to learn more on how to
+configure the behavior of this class.
+
 .. _ref-classes-scons:
 
 ``scons``
diff --git a/documentation/ref-manual/fragments.rst b/documentation/ref-manual/fragments.rst
index 9449f4648..8da14a038 100644
--- a/documentation/ref-manual/fragments.rst
+++ b/documentation/ref-manual/fragments.rst
@@ -204,6 +204,26 @@  The ``core/yocto/root-login-with-empty-password`` :term:`configuration fragment`
 can be used to allow to login as the ``root`` user to login without a password
 on the serial console and over SSH.
 
+.. _ref-fragments-core-yocto-sbom-cve-check:
+
+``core/yocto/sbom-cve-check``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``core/yocto/sbom-cve-check`` :term:`configuration fragment` can be used
+to set up the build to use the :ref:`ref-classes-sbom-cve-check` class .
+
+This configuration fragment does multiple things:
+
+-  Add the :ref:`ref-classes-create-spdx` class to the list of globally
+   inherited classes, as it depends on it.
+
+-  Sets the source revision (:term:`SRCREV`) of the input CVE databases to
+   :term:`AUTOREV`, so these databases are automatically fetched and updated
+   when starting a build.
+
+-  Include the VEX statements to the input SPDX document using the
+   :term:`SPDX_INCLUDE_VEX` variable.
+
 Yocto Project Autobuilder Fragments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index b698e865f..d8cadef3e 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -8742,6 +8742,44 @@  system and gives an overview of their function and contents.
       list, then the build system reports a warning that indicates the
       current host distribution has not been tested as a build host.
 
+   :term:`SBOM_CVE_CHECK_EXPORT_VARS`
+      When inheriting the :ref:`ref-classes-sbom-cve-check` class, this variable
+      holds the list of variables that declare export files to generate.
+
+      Each variable must have a ``type`` and an ``ext`` flag set:
+
+      -  The ``type`` flag contains the value that is passed to the
+         ``--export-type`` command line argument of ``sbom-cve-check``.
+
+      -  The ``ext`` flag contains the filename extension (suffix). The output
+         filename is going will be ``${IMAGE_NAME}${ext}``.
+
+      For example::
+
+         SBOM_CVE_CHECK_EXPORT_VARS = "SBOM_CVE_CHECK_EXPORT_SPDX3"
+         SBOM_CVE_CHECK_EXPORT_SPDX3[type] = "spdx3"
+         SBOM_CVE_CHECK_EXPORT_SPDX3[ext] = ".sbom-cve-check.spdx.json"
+
+   :term:`SBOM_CVE_CHECK_EXTRA_ARGS`
+      When inheriting the :ref:`ref-classes-sbom-cve-check` class, this variable
+      can be used to pass extra arguments to the ``sbom-cve-check`` command-line
+      tool.
+
+      See the `documentation <https://sbom-cve-check.readthedocs.io/en/latest/index.html>`__
+      of ``sbom-cve-check`` for more information.
+
+   :term:`SBOM_CVE_CHECK_SCAN_SCOPE`
+      When inheriting the :ref:`ref-classes-sbom-cve-check` class, this
+      variable controls whether to scan target and native, just target, or just
+      native recipes.
+
+      Valid values are:
+
+      -  ``target`` (default): recipes are scanned in their target context
+      -  ``native``: recipes are scanned in their :ref:`ref-classes-native` context
+      -  ``both``: recipes are scanned in both their target and
+         :ref:`ref-classes-native` context
+
    :term:`SDK_ARCH`
       The target architecture for the SDK. Typically, you do not directly
       set this variable. Instead, use :term:`SDKMACHINE`.