Skip to content

Add documentation for SBOM #676

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yogeshhegde wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Add documentation for SBOM #676

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
007d0df
feat(linux): Add SBOM section to release notes
yogeshhegde Apr 16, 2026
41da0b5
feat(linux): Add how to guide for working with SBOMs
yogeshhegde Apr 16, 2026
e7f9c4b
feat(linux): Add link to working with SBOM
yogeshhegde Apr 16, 2026
89572e6
feat(linux): Add SBOM section to release notes for AM62DX
yogeshhegde Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions configs/AM62LX/AM62LX_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,7 @@ linux/How_to_Guides/Target/How_To_Enable_M2CC3301_in_linux
linux/How_to_Guides/Target/Runtime_debug_unlock_on_secure_device
linux/How_to_Guides/FAQ/How_to_Check_Device_Tree_Info
linux/How_to_Guides/FAQ/How_to_Integrate_Open_Source_Software
linux/How_to_Guides/FAQ/How_to_work_with_SBOM
linux/How_to_Guides_Hardware_Setup_with_CCS
linux/How_to_Guides/Hardware_Setup_with_CCS/AM62Lx_EVM_Hardware_Setup
linux/Demo_User_Guides/index_Demos
Expand Down
1 change: 1 addition & 0 deletions configs/AM62PX/AM62PX_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,7 @@ linux/How_to_Guides/Target/Runtime_debug_unlock_on_secure_device
linux/How_to_Guides/Target/How_to_Tune_Real_Time_Linux
linux/How_to_Guides/FAQ/How_to_Check_Device_Tree_Info
linux/How_to_Guides/FAQ/How_to_Integrate_Open_Source_Software
linux/How_to_Guides/FAQ/How_to_work_with_SBOM
linux/How_to_Guides_Hardware_Setup_with_CCS
linux/How_to_Guides/Hardware_Setup_with_CCS/AM62Px_EVM_Hardware_Setup
linux/How_to_Guides/Target/How_To_Carve_Out_CMA
Expand Down
1 change: 1 addition & 0 deletions configs/AM62X/AM62X_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,7 @@ linux/How_to_Guides/Target/Runtime_debug_unlock_on_secure_device
linux/How_to_Guides/Target/How_to_Tune_Real_Time_Linux
linux/How_to_Guides/FAQ/How_to_Check_Device_Tree_Info
linux/How_to_Guides/FAQ/How_to_Integrate_Open_Source_Software
linux/How_to_Guides/FAQ/How_to_work_with_SBOM
linux/How_to_Guides_Hardware_Setup_with_CCS
linux/How_to_Guides/Hardware_Setup_with_CCS/AM62x_EVM_Hardware_Setup

Expand Down
1 change: 1 addition & 0 deletions configs/AM64X/AM64X_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,7 @@ linux/How_to_Guides/Hardware_Setup_with_CCS/AM64x_EVM_Hardware_Setup
linux/How_to_Guides/FAQ/How_to_Verify_Ipc_Linux_R5
linux/How_to_Guides/FAQ/How_to_Check_Device_Tree_Info
linux/How_to_Guides/FAQ/How_to_Integrate_Open_Source_Software
linux/How_to_Guides/FAQ/How_to_work_with_SBOM
linux/How_to_Guides/Target/Processor_SDK_Linux_File_System_Optimization_Customization

devices/AM64X/index_RTOS
Expand Down
7 changes: 7 additions & 0 deletions source/devices/AM62DX/linux/Release_Specific_Release_Notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,13 @@ found on the SDK download page or in the installed directory as indicated below.

- Linux Manifest: :file:`<PSDK_PATH>/manifest/software_manifest.htm`

Software Bill of Materials (SBOM)
=================================

|__SDK_FULL_NAME__| releases include Software Bill of Materials (SBOM) files in SPDX 3.0
format for Yocto. SBOM for released artifacts be found on the |__SDK_DOWNLOAD_URL__|.
For more refer :ref:`Working with SBOM <how-to-work-with-sbom>`.

Release 12.00.00.07.04
======================

Expand Down
8 changes: 8 additions & 0 deletions source/devices/AM62LX/linux/Release_Specific_Release_Notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,14 @@ found on the SDK download page or in the installed directory as indicated below.
- Debian Manifest: `TI debian software manifest 11.01.16.13
<https://dr-download.ti.com/software-development/software-development-kit-sdk/MD-YjEeNKJJjt/11.01.16.13/software_manifest_debian_am62lxx-evm_am62lxx-evm.htm>`__

Software Bill of Materials (SBOM)
=================================

|__SDK_FULL_NAME__| releases include Software Bill of Materials (SBOM) files in SPDX 3.0
format for Yocto and CycloneDX 1.6 format for Buildroot. SBOMs for all released artifacts
are bundled into a single archive and can be found on the |__SDK_DOWNLOAD_URL__|.
For more refer :ref:`Working with SBOM <how-to-work-with-sbom>`.

Comment thread
yogeshhegde marked this conversation as resolved.
Release 12.00.00.07.04
======================

Expand Down
7 changes: 7 additions & 0 deletions source/devices/AM62PX/linux/Release_Specific_Release_Notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,13 @@ found on the SDK download page or in the installed directory as indicated below.
- Debian Manifest: `TI debian software manifest 11.01.16.13
<https://dr-download.ti.com/software-development/software-development-kit-sdk/MD-9ti3Ig9hNi/11.01.16.13/software_manifest_debian_am62pxx-evm_am62pxx-evm.htm>`__

Software Bill of Materials (SBOM)
=================================

|__SDK_FULL_NAME__| releases include Software Bill of Materials (SBOM) files in SPDX 3.0
format by default. SBOMs for all released artifacts are bundled into a single
archive and can be found on the |__SDK_DOWNLOAD_URL__|.
For more refer :ref:`Working with SBOM <how-to-work-with-sbom>`.

Release 12.00.00.07.04
======================
Expand Down
8 changes: 8 additions & 0 deletions source/devices/AM62X/linux/Release_Specific_Release_Notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,14 @@ found on the SDK download page or in the installed directory as indicated below.

- Linux Manifest: :file:`<PSDK_PATH>/manifest/software_manifest.htm`

Software Bill of Materials (SBOM)
=================================

|__SDK_FULL_NAME__| releases include Software Bill of Materials (SBOM) files in SPDX 3.0
format for Yocto and CycloneDX 1.6 format for Buildroot. SBOMs for all released artifacts
are bundled into a single archive and can be found on the |__SDK_DOWNLOAD_URL__|.
For more refer :ref:`Working with SBOM <how-to-work-with-sbom>`.

Release 12.00.00.07.04
======================

Expand Down
7 changes: 7 additions & 0 deletions source/devices/AM64X/linux/Release_Specific_Release_Notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,13 @@ found on the SDK download page or in the installed directory as indicated below.

- Linux Manifest: :file:`<PSDK_PATH>/manifest/software_manifest.htm`

Software Bill of Materials (SBOM)
=================================

|__SDK_FULL_NAME__| releases include Software Bill of Materials (SBOM) files in SPDX 3.0
format by default. SBOMs for all released artifacts are bundled into a single
archive and can be found on the |__SDK_DOWNLOAD_URL__|.
For more refer :ref:`Working with SBOM <how-to-work-with-sbom>`.

Release 12.00.00.07.04
======================
Expand Down
175 changes: 175 additions & 0 deletions source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst
View file
Open in desktop
Copy link
Copy Markdown
Member

@StaticRocket StaticRocket Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you use auto-numbered lists for this instead of manual numbering?

Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
.. _how-to-work-with-sbom:
Copy link
Copy Markdown
Member

@cshilwant cshilwant Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This newly added section doesn't seem to follow the guidelines of section headers

https://github.com/TexasInstruments/processor-sdk-doc?tab=contributing-ov-file#headings--sections

Copy link
Copy Markdown
Contributor Author

@yogeshhegde yogeshhegde Apr 17, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

But few questions,

  1. Why do we follow Python Developer's Guide for documenting , what benefits do we get by following this guide just for heading ?
    • rst does not put any limitations on the section headers, the doc says whatever we encounter 1st is h1 and so on.
    • Since for h1 and h2 the characters underlining are different why do we need an overline just for h1 and h2 ? Since it is just for aesthetic purposes why not overline for all or no overline for all? Why not simplify and use one format for headings?
  2. I see alot of .rst files not following the format, is there a plan to fix those documents?


###############################################################
How to Guide for working with Software Bill of Materials (SBOM)

Check warning on line 4 in source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Headings] Use sentence-style capitalization in 'How to Guide for working with Software Bill of Materials (SBOM)'.

Raw Output:
{"message": "[RedHat.Headings] Use sentence-style capitalization in 'How to Guide for working with Software Bill of Materials (SBOM)'.", "location": {"path": "source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst", "range": {"start": {"line": 4, "column": 1}}}, "severity": "INFO"}
###############################################################

********
Glossary
********

.. glossary::

SBOM
Software Bill of Materials - is a comprehensive list of all the software components, dependencies, and metadata associated with an application.

SPDX
Software Package Data Exchange - is an open standard (or format) for communicating Software Bill of Materials (SBOM) information including components, licenses, copyrights, and security references.

CycloneDX
CycloneDX is a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction.

VEX
Vulnerability Exploitability eXchange - is a standardized format for sharing information about vulnerabilities and their exploitability.

***************
Generating SBOM
***************

|__SDK_FULL_NAME__| Yocto build generates SBOMs in the following formats and versions:

Check warning on line 29 in source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'SBOMs') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'SBOMs') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst", "range": {"start": {"line": 29, "column": 43}}}, "severity": "INFO"}

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

* - Format
- Version
* - SPDX

Check warning on line 36 in source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPDX') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPDX') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst", "range": {"start": {"line": 36, "column": 8}}}, "severity": "INFO"}
- 3.0
* - CycloneDX
- 1.6

Follow the steps below based on your required format.

Check warning on line 41 in source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.TermsSuggestions] Depending on the context, consider using 'after', 'later', or 'following' rather than 'below'.

Raw Output:
{"message": "[RedHat.TermsSuggestions] Depending on the context, consider using 'after', 'later', or 'following' rather than 'below'.", "location": {"path": "source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst", "range": {"start": {"line": 41, "column": 18}}}, "severity": "INFO"}

Generating SBOM in SPDX 3.0 Format

Check warning on line 43 in source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPDX') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPDX') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst", "range": {"start": {"line": 43, "column": 20}}}, "severity": "INFO"}

Check warning on line 43 in source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Headings] Use sentence-style capitalization in 'Generating SBOM in SPDX 3.0 Format'.

Raw Output:
{"message": "[RedHat.Headings] Use sentence-style capitalization in 'Generating SBOM in SPDX 3.0 Format'.", "location": {"path": "source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst", "range": {"start": {"line": 43, "column": 1}}}, "severity": "INFO"}
==================================

SPDX 3.0 is generated by default when building |__SDK_FULL_NAME__| Yocto, no extra steps required.

Check warning on line 46 in source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.PassiveVoice] 'is generated' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.

Raw Output:
{"message": "[RedHat.PassiveVoice] 'is generated' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.", "location": {"path": "source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst", "range": {"start": {"line": 46, "column": 10}}}, "severity": "INFO"}

Check warning on line 46 in source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPDX') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'SPDX') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst", "range": {"start": {"line": 46, "column": 1}}}, "severity": "INFO"}
If you require additional vulnerability information, follow these steps:

1. Add the following line to your ``local.conf``:
Copy link
Copy Markdown
Member

@cshilwant cshilwant Apr 16, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

role file can be used to highlight the same

Suggested change
1. Add the following line to your ``local.conf``:
1. Add the following line to your :file:`local.conf`:

Copy link
Copy Markdown
Contributor Author

@yogeshhegde yogeshhegde Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the difference between

``local.conf``

&

:file:`local.conf`

How is it rendered different to the user?


.. code-block:: text

INHERIT += "vex"
Comment thread
yogeshhegde marked this conversation as resolved.

2. Build Yocto according to the build instructions in :ref:`Processor SDK - Building the SDK with Yocto <building-the-sdk-with-yocto>`.

Check warning on line 55 in source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.UserReplacedValues] Separate words by underscores in user-replaced values.

Raw Output:
{"message": "[RedHat.UserReplacedValues] Separate words by underscores in user-replaced values.", "location": {"path": "source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst", "range": {"start": {"line": 55, "column": 105}}}, "severity": "INFO"}

The following artifacts will be generated in the Yocto deploy directory:

Check warning on line 57 in source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.PassiveVoice] 'be generated' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.

Raw Output:
{"message": "[RedHat.PassiveVoice] 'be generated' is passive voice. In general, use active voice. Consult the style guide for acceptable use of passive voice.", "location": {"path": "source/linux/How_to_Guides/FAQ/How_to_work_with_SBOM.rst", "range": {"start": {"line": 57, "column": 30}}}, "severity": "INFO"}

.. list-table::
:header-rows: 1
:widths: 50 50

* - File
- Description
* - ``${IMAGE_NAME}.rootfs.spdx.json``
- The SPDX v3.0 SBOM file
* - ``${IMAGE_NAME}.rootfs.json``
- Vulnerability information file generated by ``vex.bbclass``


Generating SBOM in CycloneDX Format
===================================

To generate SBOM in CycloneDX format, follow these steps:

1. Start with the build instructions in :ref:`Processor SDK - Building the SDK with Yocto <building-the-sdk-with-yocto>`
2. After cloning ``oe-layersetup``, uncomment the ``meta-cyclonedx`` line in
the layer configuration file, for example:

Copy link
Copy Markdown
Member

@cshilwant cshilwant Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any reasons we aren't pushing a new oe-config file to oe-layersetup dedicated for SBOMs?
We can avoid the following manual local changes & improve the user experience

Copy link
Copy Markdown
Contributor Author

@yogeshhegde yogeshhegde Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here are few reasons,

  1. CycloneDX SBOM is not default format for SBOM, but there might be some users who want to use the format.
  2. Duplication of oe-config, there are 4 oe-config for 12.00.00 release, creating new oe-config just for cyclonedx would take that number to 8 since we have to give each oe-config with SPDX and CycloneDX SBOM generation.
  3. 8 oe-config will lead to more user confusion instead of improving user experience because for users who just want sane defaults they will be confused which oe-config to use.
  4. oe-layersetup does not allow us to include files / config fragments, while kas (yaml) and repo (xml) both have include files feature where we can create fragments and user can include/exclude fragments enabling/disabling features. This would simplify both maintenance and improve user experience.

With these constraints, I believe this is the best course, since it is just uncommenting a line for the user and they also see less oe-configs.

.. code-block:: text

meta-cyclonedx,https://github.com/iris-GmbH/meta-cyclonedx.git,main,0170751b487162f8e476fd32d441ddfcf24ca78a,layers=

3. Add the following line to your :file:`local.conf`:

.. code-block:: text

INHERIT += "cyclonedx-export"

4. Continue to build Yocto according to the build instructions in :ref:`Processor SDK - Building the SDK with Yocto <building-the-sdk-with-yocto>`.

The following artifacts will be generated in the Yocto deploy directory:

.. list-table::
:header-rows: 1
:widths: 50 50

* - File
- Description
* - :file:`${IMAGE_NAME}.rootfs.cyclonedx.bom.json`
- The CycloneDX SBOM file
* - :file:`${IMAGE_NAME}.rootfs.cyclonedx.vex.json`
- The CycloneDX VEX file

*****************
Working with SBOM
*****************

It is recommended to use open-source tools for working with SBOMs.
The following open-source tools are recommended for working with SBOMs:

.. list-table::
:header-rows: 1
:widths: 20 40 40

* - Format
- Tool
- Description
* - CycloneDX
- `CycloneDX Sunshine <https://github.com/CycloneDX/Sunshine/>`_
- Visualize CycloneDX SBOMs in a human-readable format
* - CycloneDX
- `CycloneDX CLI <https://github.com/CycloneDX/cyclonedx-cli>`_
- BOM analysis, modification, diffing, merging, format conversion, signing and verification.
* - SPDX
- `SPDX Open Source Tools <https://spdx.dev/tools/open-source-tools/>`_
- A collection of open-source tools for working with SPDX SBOMs

.. note::

SPDX 3.0 is not yet widely supported by SPDX tools. Using such tools with
SPDX 3.0 files may give varied or unexpected results.

************
CVE Analysis
************

The `sbom-cve-check <https://pypi.org/project/sbom-cve-check/>`_ tool can be
used to perform CVE analysis on the generated SPDX SBOM.

1. Install the tool:

.. code-block:: console

pip install sbom-cve-check

.. note::

It is recommended to install this tool in a Python virtual environment.

2. Retrieve the following artifacts from the Yocto deploy directory:

.. list-table::
:header-rows: 1
:widths: 50 50

* - File
- Description
* - :file:`${IMAGE_NAME}.rootfs.spdx.json`
- The SPDX v3.0 SBOM file
* - :file:`${IMAGE_NAME}.rootfs.json`
- Vulnerability information file generated by ``vex.bbclass``

3. Run the CVE analysis:

.. code-block:: console

sbom-cve-check --sbom-path ${IMAGE_NAME}.rootfs.spdx.json \
--yocto-vex-manifest ${IMAGE_NAME}.rootfs.json \
--export-type yocto-cve-check-manifest \
--export-path cve-check.json

.. note::

``sbom-cve-check`` only supports SPDX format and does not support CycloneDX.
1 change: 1 addition & 0 deletions source/linux/How_to_Guides_Developer_Notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ Developer Notes
How_to_Guides/FAQ/How_to_Configure_MSMC_memory
How_to_Guides/FAQ/How_to_Check_Device_Tree_Info
How_to_Guides/FAQ/How_to_Integrate_Open_Source_Software
How_to_Guides/FAQ/How_to_work_with_SBOM
How_to_Guides/Host/How_to_Build_a_Ubuntu_Linux_host_under_VMware
How_to_Guides/Host/K3_Resource_Partitioning_Tool
How_to_Guides/Host/How_to_Setup_and_Debug_using_Lauterbach
Expand Down
Loading