feat: add delta command to show components added in target SBOM

baprusty · fmoessbauer · commit bba7c08f164e · 2026-02-10T10:13:00.000+01:00
Introduce a `delta` command that compares base/reference and target
SBOMs and identifies components present only in the target. The command
generates a new SBOM containing these additional components, making it
easier to track previously cleared components and identify new ones
requiring license clearance.

[Felix: major code cleanup and refactoring to use more debsbom internal
infrastructure]

Signed-off-by: Badrikesh Prusty &lt;badrikesh.prusty@siemens.com&gt;
Signed-off-by: Felix Moessbauer &lt;felix.moessbauer@siemens.com&gt;
diff --git a/README.md b/README.md
@@ -14,19 +14,20 @@ Source packages are especially relevant for security as CVEs in the Debian ecosy
 Please refer to the [debsbom documentation](https://siemens.github.io/debsbom/).
 
 ```
-usage: debsbom [-h] [--version] [-v] [--progress | --json] {generate,merge,download,source-merge,repack,export} ...
+usage: debsbom [-h] [--version] [-v] [--progress | --json] {generate,merge,download,source-merge,repack,export,delta} ...
 
 SBOM tool for Debian systems.
 
 positional arguments:
-  {generate,merge,download,source-merge,repack,export}
+  {generate,merge,download,source-merge,repack,export,delta}
                         sub command help
     generate            generate a SBOM for a Debian system
     merge               merge multiple SBOMs
     download            download referenced packages
     source-merge        merge referenced source packages
     repack              repack sources and sbom
     export              export SBOM as graph
+    delta               list components added in target SBOM
 
 options:
   -h, --help            show this help message and exit
diff --git a/docs/source/commands.rst b/docs/source/commands.rst
@@ -10,3 +10,4 @@ Commands
   commands/repack
   commands/export
   commands/merge
+  commands/delta
diff --git a/docs/source/commands/delta-description.rst b/docs/source/commands/delta-description.rst
@@ -0,0 +1,46 @@
+The ``delta`` command compares two SBOMs and produces a new SBOM containing only the
+components that are present in the target SBOM but not in the base (reference) SBOM.
+
+The most common use-case is identifying new or added components between two builds, images, or
+distribution states (for example, comparing a previous release SBOM against a newer one),
+including filtering out already license-cleared components to generate an SBOM containing only
+components pending license clearance.
+
+The comparison is directional:
+
+* Base SBOM – treated as the reference
+* Target SBOM – treated as the new or updated SBOM
+
+Given the following structure:
+
+Base SBOM
+
+.. code-block::
+
+    base-root
+    |- binary-dep1
+    |  |- source-dep1
+    |- binary-dep2
+
+Target SBOM
+
+.. code-block::
+
+    target-root
+    |- binary-dep1
+    |  |- source-dep1
+    |- binary-dep2
+    |- binary-dep3
+    |  |- source-dep3
+
+Running delta would produce:
+
+.. code-block::
+
+    delta-doc-root
+    |- binary-dep3
+    |  |- source-dep3
+
+Components are considered the same if they share the same PURL (Package URL). Only components
+that are new in the target SBOM, along with their nested dependencies, are included in the
+resulting SBOM.
diff --git a/docs/source/commands/delta.rst b/docs/source/commands/delta.rst
@@ -0,0 +1,7 @@
+``delta`` command
+=================
+
+.. include:: delta-description.inc
+
+.. note::
+   Only SBOMs of the same type can be compared. Specifying both SPDX and CDX SBOMs will cause an error.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -71,6 +71,7 @@
     ("man/debsbom-generate", "debsbom-generate", "debsbom generate command", [author], 1),
     ("man/debsbom-merge", "debsbom-merge", "debsbom merge command", [author], 1),
     ("man/debsbom-repack", "debsbom-repack", "debsbom repack command", [author], 1),
+    ("man/debsbom-delta", "debsbom-delta", "debsbom delta command", [author], 1),
     (
         "man/debsbom-source-merge",
         "debsbom-source-merge",
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -185,6 +185,26 @@ And the same list of packages can be repacked:
         sbom.cdx.json \
         sbom.cdx.repacked.json
 
+Delta SBOMs
+~~~~~~~~~~~
+
+The :doc:`/commands/delta` compares a base (reference) SBOM with a target (new) SBOM and produces
+a new SBOM containing only the components present in the target. The typical use-case is identifying
+newly added or changed components between two builds or releases.
+
+Use ``debsbom delta`` when you only want to see changed or added components, e.g., to generate an
+SBOM for license clearance.
+
+.. code-block:: bash
+
+   debsbom delta sbom.old.cdx.json sbom.cdx.json extras.cdx.json
+
+You can also pass SBOMs via stdin, but you also have to pass the SBOM type in this case:
+
+.. code-block:: bash
+
+   cat sbom.old.spdx.json sbom.spdx.json | debsbom delta -t spdx - - -o -
+
 Export as Graph
 ~~~~~~~~~~~~~~~
 
diff --git a/docs/source/man/debsbom-delta.rst b/docs/source/man/debsbom-delta.rst
@@ -0,0 +1,23 @@
+:orphan:
+
+debsbom delta
+=============
+
+.. argparse::
+    :module: debsbom.cli
+    :func: setup_parser
+    :prog: debsbom
+    :path: delta
+    :manpage:
+
+    .. automodule:: debsbom.commands.delta.DeltaCmd
+        :noindex:
+
+    .. include:: ../commands/delta-description.inc
+
+SEE ALSO
+--------
+
+:manpage:`debsbom-generate(1)`
+
+.. include:: _debsbom-man-footer.inc
diff --git a/src/debsbom/cli.py b/src/debsbom/cli.py
@@ -18,6 +18,7 @@
 from .commands.source_merge import SourceMergeCmd
 from .commands.repack import RepackCmd
 from .commands.export import ExportCmd
+from .commands.delta import DeltaCmd
 
 # Attempt to import optional download dependencies to check their availability.
 # The success or failure of these imports determines if download features are enabled.
@@ -64,6 +65,9 @@ def setup_parser():
     )
     RepackCmd.setup_parser(subparser.add_parser("repack", help="repack sources and sbom"))
     ExportCmd.setup_parser(subparser.add_parser("export", help="export SBOM as graph"))
+    DeltaCmd.setup_parser(
+        subparser.add_parser("delta", help="list components changed in target SBOM")
+    )
 
     return parser
 
@@ -97,6 +101,8 @@ def main():
             ExportCmd.run(args)
         elif args.cmd == "merge":
             MergeCmd.run(args)
+        elif args.cmd == "delta":
+            DeltaCmd.run(args)
     except DistroArchUnknownError as e:
         logger.error(f"debsbom: error: {e}. Set --distro-arch to dpkg architecture (e.g. amd64)")
         sys.exit(-2)
diff --git a/src/debsbom/commands/delta.py b/src/debsbom/commands/delta.py
@@ -0,0 +1,50 @@
+# Copyright (C) 2025 Siemens
+#
+# SPDX-License-Identifier: MIT
+
+from ..delta.delta import DeltaGenerator
+from .output import SbomOutput
+from .input import GenerateInput, SbomInput
+from ..bomreader.bomreader import BomReader
+
+
+class DeltaCmd(GenerateInput, SbomInput):
+    """
+    Compute the delta between base and target SBOMs, producing a new SBOM containing only
+    additional components from the target.
+    """
+
+    @classmethod
+    def run(cls, args):
+        readers = cls.create_sbom_processors(
+            args, BomReader, sbom_args=["base_sbom", "target_sbom"], sbom_allow_multiple=True
+        )
+        if len(readers) != 2:
+            raise ValueError("can only compare exactly two SBOMs")
+
+        sbom_types = set([r.sbom_type() for r in readers])
+        if len(sbom_types) > 1:
+            raise ValueError("can not compare mixed SPDX and CycloneDX documents")
+        sbom_type = readers[0].sbom_type()
+
+        docs = [r.read() for r in readers]
+
+        delta_generator = DeltaGenerator.create(
+            sbom_type=sbom_type,
+            distro_name=args.distro_name,
+            distro_supplier=args.distro_supplier,
+            distro_version=args.distro_version,
+            base_distro_vendor=args.base_distro_vendor,
+            spdx_namespace=args.spdx_namespace,
+            cdx_serialnumber=args.cdx_serialnumber,
+            timestamp=args.timestamp,
+        )
+        bom = delta_generator.delta(base_sbom=docs[0], target_sbom=docs[1])
+        SbomOutput.write_out_arg(bom, sbom_type, args.out, args.validate)
+
+    @classmethod
+    def setup_parser(cls, parser):
+        cls.parser_add_generate_input_args(parser, default_out="extras")
+        cls.parser_add_sbom_input_args(
+            parser, required=True, sbom_args=["base_sbom", "target_sbom"]
+        )
diff --git a/src/debsbom/commands/output.py b/src/debsbom/commands/output.py
@@ -2,12 +2,15 @@
 #
 # SPDX-License-Identifier: MIT
 
+import logging
 from pathlib import Path
 import sys
 
 from ..sbom import SBOMType
 from ..bomwriter.bomwriter import BomWriter
 
+logger = logging.getLogger(__name__)
+
 
 class SbomOutput:
     """
@@ -18,8 +21,10 @@ class SbomOutput:
     def write_out_arg(cls, bom, bomtype: SBOMType, out: str, validate: bool):
         writer = BomWriter.create(bomtype)
         if out == "-":
+            logger.info("Emit SBOM on stdout")
             writer.write_to_stream(bom, sys.stdout, validate=validate)
         else:
             if not out.endswith(f".{bomtype}.json"):
                 out += f".{bomtype}.json"
+            logger.info(f"Write SBOM to file {out}")
             writer.write_to_file(bom, Path(out), validate=validate)
diff --git a/src/debsbom/delta/cdx.py b/src/debsbom/delta/cdx.py
@@ -0,0 +1,85 @@
+# Copyright (C) 2025 Siemens
+#
+# SPDX-License-Identifier: MIT
+
+from cyclonedx.model.bom import Bom
+from cyclonedx.model.dependency import Dependency
+import itertools
+import logging
+from uuid import uuid4
+
+from .delta import DeltaGenerator
+from ..generate.cdx import make_distro_component, make_metadata
+
+logger = logging.getLogger(__name__)
+
+
+class CdxDeltaGenerator(DeltaGenerator):
+    def delta(self, base_sbom, target_sbom) -> Bom:
+        components = {}
+        non_purl_components = []
+        dependencies = {}
+        ref_map = {}
+
+        non_purl_components.append(target_sbom.metadata.component)
+
+        # Get the components list of base/reference SBOM
+        base_components = {
+            component.purl: component
+            for component in base_sbom.components
+            if component.purl is not None
+        }
+
+        for component in target_sbom.components:
+            purl = component.purl
+            if purl is None:
+                logger.warning(f"missing PURL for component '{component.name}'")
+                non_purl_components.append(component)
+                continue
+            else:
+                logger.debug(f"Checking CDX component '{purl}' in reference SBOM")
+                if purl not in base_components:
+                    logger.debug(f"Adding CDX component '{purl}'")
+                    components[purl] = component
+                    ref_map[component.bom_ref] = components[purl].bom_ref
+
+        for dep in target_sbom.dependencies:
+            if dep.ref not in ref_map:
+                continue
+
+            # Add child dependencies only if they are present in the extra components list
+            child_deps = [ch_dep for ch_dep in (dep.dependencies or []) if ch_dep.ref in ref_map]
+
+            dependencies[dep.ref] = Dependency(ref=dep.ref, dependencies=child_deps)
+
+        distro_component = make_distro_component(
+            self.distro_name, self.distro_version, self.distro_supplier
+        )
+        bom_metadata = make_metadata(distro_component, self.timestamp)
+
+        distro_deps = []
+        target_bom_ref = target_sbom.metadata.component.bom_ref
+        distro_deps.append(Dependency(ref=target_bom_ref))
+
+        dependency = Dependency(
+            ref=distro_component.bom_ref,
+            dependencies=distro_deps,
+        )
+        logger.debug(f"Created distro dependency: {dependency}")
+        dependencies[dependency.ref] = dependency
+
+        if self.cdx_serialnumber is None:
+            serial_number = uuid4()
+        else:
+            serial_number = self.cdx_serialnumber
+
+        components = itertools.chain(components.values(), non_purl_components)
+
+        bom = Bom(
+            serial_number=serial_number,
+            metadata=bom_metadata,
+            components=list(components),
+            dependencies=dependencies.values(),
+        )
+
+        return bom
diff --git a/src/debsbom/delta/delta.py b/src/debsbom/delta/delta.py
@@ -0,0 +1,54 @@
+# Copyright (C) 2025 Siemens
+#
+# SPDX-License-Identifier: MIT
+
+from abc import abstractmethod
+from datetime import datetime
+from uuid import UUID
+
+from ..sbom import SBOMType
+
+
+class DeltaGenerator:
+    """Base class for generating delta SBOMs."""
+
+    def __init__(
+        self,
+        distro_name: str,
+        distro_supplier: str | None = None,
+        distro_version: str | None = None,
+        base_distro_vendor: str | None = "debian",
+        spdx_namespace: tuple | None = None,  # 6 item tuple representing an URL
+        cdx_serialnumber: UUID | None = None,
+        timestamp: datetime | None = None,
+    ):
+        self.distro_name = distro_name
+        self.distro_supplier = distro_supplier
+        self.distro_version = distro_version
+        self.base_distro_vendor = base_distro_vendor
+        self.namespace = spdx_namespace
+        self.cdx_serialnumber = cdx_serialnumber
+        if timestamp is None:
+            self.timestamp = datetime.now()
+        else:
+            self.timestamp = timestamp
+
+    @staticmethod
+    def create(sbom_type: SBOMType, **kwargs) -> "DeltaGenerator":
+        sbom_type.validate_dependency_availability()
+        if sbom_type is SBOMType.SPDX:
+            from .spdx import SpdxDeltaGenerator
+
+            return SpdxDeltaGenerator(**kwargs)
+        elif sbom_type is SBOMType.CycloneDX:
+            from .cdx import CdxDeltaGenerator
+
+            return CdxDeltaGenerator(**kwargs)
+        else:
+            raise NotImplementedError()
+
+    @classmethod
+    @abstractmethod
+    def delta(cls, base_sbom, target_sbom):
+        """Compute the delta between base and target SBOMs."""
+        raise NotImplementedError()
diff --git a/src/debsbom/delta/spdx.py b/src/debsbom/delta/spdx.py

Original file line number	Diff line number	Diff line change
`@@ -71,6 +71,7 @@`
`71`	`71`	`("man/debsbom-generate", "debsbom-generate", "debsbom generate command", [author], 1),`
`72`	`72`	`("man/debsbom-merge", "debsbom-merge", "debsbom merge command", [author], 1),`
`73`	`73`	`("man/debsbom-repack", "debsbom-repack", "debsbom repack command", [author], 1),`
	`74`	`+ ("man/debsbom-delta", "debsbom-delta", "debsbom delta command", [author], 1),`
`74`	`75`	`(`
`75`	`76`	`"man/debsbom-source-merge",`
`76`	`77`	`"debsbom-source-merge",`