.. _os-sbom:

############################################
Software Inventory and Vulnerability Reports
############################################

Report Configuration
====================

The common KAS fragment ``ci/fragments/base.yml`` adds ``meta-cyclonedx`` and
inherits ``cyclonedx-export cve-check``. It selects CycloneDX specification
``1.6`` and includes unpatched vulnerability information. Extension layers can
supply their own reporting policy, documented in their respective ``README.md``
files. Inspect the complete fragment combination to establish which reports a
build generates.

.. list-table:: Report outputs
   :header-rows: 1

   * - Output
     - Location relative to the build directory
     - Purpose
   * - SPDX
     - ``tmp/deploy/spdx/<spdx-version>/<machine>/``
     - Yocto software and licensing inventory, when the selected configuration
       inherits SPDX generation. Archive names and aggregation depend on that
       configuration.
   * - CycloneDX SBOM
     - ``tmp/deploy/cyclonedx-export/<recipe>-<machine>-bom.json``
     - Image-specific component and dependency inventory.
   * - CycloneDX VEX
     - ``tmp/deploy/cyclonedx-export/<recipe>-<machine>-vex.json``
     - Vulnerability information exported alongside the component inventory.
   * - CVE check
     - Image reports under ``tmp/deploy/images/<machine>/`` and recipe reports
       under ``tmp/deploy/cve/``
     - Matches against the vulnerability database and the recipe patch state.
       Available filenames and JSON/text formats depend on the inherited
       ``cve-check`` configuration.

There is no single SBOM covering every OrchestraOS target or image. Minimal,
graphical, and initramfs images have different contents. Firmware and boot
components included through ``CYCLONEDX_EXTRA_RUNTIME_RECIPES`` are recorded
with the main image; the initramfs deliberately clears that setting to avoid a
dependency cycle with boot-component generation.

The common configuration retains the exporter defaults for runtime package
coverage. A report must not be described as an inventory of every build-host
tool or every source recipe without checking its actual contents.

Enabling or Disabling Reports
=============================

For a configuration that does not already enable reports, add a local KAS
fragment:

.. code-block:: yaml

   header:
     version: 19
   local_conf_header:
     software-reports: |
       INHERIT += "cyclonedx-export cve-check"
       CYCLONEDX_SPEC_VERSION = "1.6"
       SPDX_PRETTY = "1"

When an included fragment uses ``INHERIT:remove`` to disable reporting, remove
that policy in the configuration you maintain before enabling the classes.
A later ``INHERIT +=`` does not cancel an active BitBake ``:remove`` override.
The ``meta-cyclonedx`` layer must also be present. ``SPDX_PRETTY`` controls
formatting when SPDX generation is enabled; it does not enable SPDX generation
by itself.

To disable CycloneDX and CVE checking for a local configuration:

.. code-block:: text

   INHERIT:remove = "cyclonedx-export cve-check"

CVE checking needs access to its configured vulnerability data source and can
reuse a cached database. Preserve the report generation date and database
context with the image. Report generation can require network access even when
most source and compilation tasks are cached.

Interpreting and Delivering Reports
===================================

Compare the report's machine, image recipe, version, and component revisions
with the image being delivered. A generated VEX file is not automatically a
reviewed statement that every listed vulnerability is exploitable or resolved.
Investigate version matches, backported patches, package selection, and product
exposure before issuing a vulnerability disposition.

Deliver reports alongside their matching image and checksum files. An engineering
summary does not replace the original machine-readable inventory.