KernelSbom

A script to generate an SPDX-format Software Bill of Materials (SBOM) for the vmlinux kernel build. The eventual goal is to integrate the sbom/ directory into the linux/scripts/ directory in the official linux source tree.

Getting Started

1. Provide a linux source and output tree, e.g., by downloading precompiled test data from KernelSbom-TestData

   test_archive="linux.v6.17.tinyconfig.tar.gz"
   curl -L -o "$test_archive" "https://fileshare.tngtech.com/d/e69946da808b41f88047/files/?p=%2F$test_archive&dl=1"
   tar -xzf "$test_archive"

   or cloning the linux repo and building your own config

   git clone --depth 1 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
   cd linux
   make <config> O=kernel_build
   make -j$(nproc) O=kernel_build

2. Clone the repository

   git clone git@github.com:TNG/KernelSbom.git
   cd KernelSbom
   

3. Run the sbom.py script

   python3 sbom/sbom.py \
     --src-tree ../linux \
     --output-tree ../linux/kernel_build \
     --root-output-in-tree vmlinux \
     --spdx sbom.spdx.json \
     --used-files sbom.used_files.txt

   Starting from vmlinux, the script builds the cmd graph, a directed acyclic graph where nodes are filenames and edges represent build dependencies extracted from .<filename>.cmd files. Based on the cmd graph, the final sbom.used_files.txt and sbom.spdx.json files are generated and saved to disk. The sbom.used_files.txt file is a flat list of all files from the source tree that were used to build vmlinux. The sbom.spdx.json file contains an SPDX document that describes the complete build process leading to vmlinux.

Directory Structure

• sbom/
  • sbom.py - The main script responsible for generating the SBOM.
  • sbom/lib/sbom - Library modules used by the main script.
  • sbom/lib/sbom_tests - Unit tests for the library modules.
• sbom_analysis - Additional scripts for analyzing the outputs produced by the main script.
  • sbom_analysis/cmd_graph_based_kernel_build - Validation of cmd graph completeness by rebuilding the linux kernel only with files referenced in the cmd graph.
  • sbom_analysis/cmd_graph_visualization - Interactive visualization of the cmd graph
• testdata_generation - Describes how the precompiled kernel builds in KernelSbom-TestData were generated.

The main contribution is the content of the sbom directory which eventually should be moved into the linux/scripts/ directory in the official linux source tree.

Development

Activate the venv and install build dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install pre-commit reuse ruff
pre-commit install

When committing, reuse lint is run as a pre-commit hook to ensure all files have compliant license headers.
If any file is missing a license header, you can add it using:

reuse annotate --license="GPL-2.0-only" --copyright="TNG Technology Consulting GmbH" --template default <filename>

Note: If the annotated file contains a shebang, reuse annotate will insert an empty line after it. This empty line must be removed manually.