feat: compare reference and target SBOMs, show extra components in target

Add a `compare` command to identify components present in the target SBOM but
missing in the reference/base SBOM. Highlight these extra components and create
a new SBOM containing only the extras. Help track already sent or cleared
components and identify additional components that require license clearing.

Signed-off-by: badrikesh prusty <badrikesh.prusty@siemens.com>

Author: baprusty

docs/source/commands.rst

@@ -10,3 +10,4 @@ Commands
   commands/repack
   commands/export
   commands/merge
+  commands/compare

docs/source/commands/compare-description.inc

@@ -0,0 +1,46 @@
+The ``compare`` 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 compare would produce:
+
+.. code-block::
+
+    compare-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.

docs/source/commands/compare.rst

@@ -0,0 +1,7 @@
+``compare`` command
+===================
+
+.. include:: compare-description.inc
+
+.. note::
+   Only SBOMs of the same type can be compared. Specifying both SPDX and CDX SBOMs will cause an error.

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-compare", "debsbom-compare", "debsbom compare command", [author], 1),
     (
         "man/debsbom-source-merge",
         "debsbom-source-merge",

docs/source/examples.rst

@@ -128,62 +128,25 @@ For that, provide both an SBOM, as well as a set of "to-be-processed" packages v
 Compare SBOMs
 ~~~~~~~~~~~~~
 
-The SBOMs produced by ``debsbom`` can be further processed with existing tools – for example, the `CycloneDX CLI <https://github.com/CycloneDX/cyclonedx-cli>`_.
-Comparing two SBOMs directly is outside the scope of ``debsbom``, but you can determine which components have changed by using a short snippet such as the one shown below.
-
-Locate Changes
-^^^^^^^^^^^^^^
-
-.. code-block:: bash
-
-    cyclonedx-cli diff --component-versions --output-format json \
-        sbom.old.cdx.json sbom.cdx.json | \
-    jq -r '.componentVersions[] | select(.added!=[] or .removed!=[]) | {"added": .added[0].purl, "removed": .removed[0].purl}'
-    # {"added", "purl-a-1.1", "removed": "purl-a-1.0"}
-    # {...}
-
-A similar output can be generated by just using ``jq`` and ``diff``:
-
-.. code-block:: bash
-
-    diff --color \
-        <(jq -r --sort-keys '.components[].purl' sbom.old.cdx.json) \
-        <(jq -r --sort-keys '.components[].purl' sbom.cdx.json)
+The :doc:`/commands/compare` 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.
 
 Identify new Components
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Consider you only want to know the changed and added components, e.g. for license clearing.
+Use ``debsbom compare`` when you only want to see changed or added components, e.g., to generate an
+SBOM for license clearance.
 
 .. code-block:: bash
 
-    PURLS=$( \
-        diff -U0 \
-            <(jq -r --sort-keys '.components[].purl' sbom.old.cdx.json) \
-            <(jq -r --sort-keys '.components[].purl' sbom.cdx.json) \
-            | grep ^+pkg | sed 's/^+//' \
-    )
-
-The PURLs can be used as input to debsbom to download / merge components:
+   debsbom compare sbom.old.cdx.json sbom.cdx.json extras.cdx.json
 
-.. code-block:: bash
-
-    echo "$PURLS" | debsbom download --sources --binaries
-
-Once downloaded, it is possible to merge the source packages:
-
-.. code-block:: bash
-
-    echo "$PURLS" | debsbom source-merge --apply-patches
-
-And the same list of packages can be repacked:
+You can also pass SBOMs via stdin, but you also have to pass the SBOM type in this case:
 
 .. code-block:: bash
 
-    echo "$PURLS" | debsbom repack \
-        --apply-patches
-        sbom.cdx.json \
-        sbom.cdx.repacked.json
+   cat sbom.old.spdx.json sbom.spdx.json | debsbom compare -t spdx - - -o -
 
 Export as Graph
 ~~~~~~~~~~~~~~~

docs/source/man/debsbom-compare.rst

@@ -0,0 +1,23 @@
+:orphan:
+
+debsbom compare
+===============
+
+.. argparse::
+    :module: debsbom.cli
+    :func: setup_parser
+    :prog: debsbom
+    :path: compare
+    :manpage:
+
+    .. automodule:: debsbom.commands.compare.CompareCmd
+        :noindex:
+
+    .. include:: ../commands/compare-description.inc
+
+SEE ALSO
+--------
+
+:manpage:`debsbom-generate(1)`
+
+.. include:: _debsbom-man-footer.inc

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.compare import CompareCmd
 
 # 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"))
+    CompareCmd.setup_parser(
+        subparser.add_parser("compare", help="compare SBOMs and list new components")
+    )
 
     return parser
 
@@ -97,6 +101,8 @@ def main():
             ExportCmd.run(args)
         elif args.cmd == "merge":
             MergeCmd.run(args)
+        elif args.cmd == "compare":
+            CompareCmd.run(args)
     except DistroArchUnknownError as e:
         logger.error(f"debsbom: error: {e}. Set --distro-arch to dpkg architecture (e.g. amd64)")
         sys.exit(-2)

src/debsbom/commands/compare.py

@@ -0,0 +1,131 @@
+# Copyright (C) 2025 Siemens
+#
+# SPDX-License-Identifier: MIT
+
+import json
+from pathlib import Path
+import sys
+
+
+from ..bomwriter import BomWriter
+from .input import GenerateInput, warn_if_tty
+from ..sbom import SBOMType
+
+
+class CompareCmd(GenerateInput):
+    """
+    Compare two SBOMs and generate a new SBOM containing only the additional components found in the target
+    """
+
+    @classmethod
+    def run(cls, args):
+        inputs = [
+            ("base", args.base_sbom),
+            ("target", args.target_sbom),
+        ]
+
+        base_json_obj = target_json_obj = None
+        base_path = target_path = None
+        base_sbom_fmt = target_sbom_fmt = None
+        base_sbom_obj = target_sbom_obj = None
+
+        json_sboms = []
+        stdin_consumed = False
+
+        for kind, sbom_arg in inputs:
+            # read from stdin
+            if sbom_arg == "-":
+                warn_if_tty()
+                if args.sbom_type is None:
+                    raise ValueError("option --sbom-type is required when reading SBOMs from stdin")
+
+                if not stdin_consumed:
+                    decoder = json.JSONDecoder()
+                    s = sys.stdin.read()
+                    json_obj, _ = decoder.raw_decode(s)
+                    len_s = len(s)
+                    read_total = 0
+                    while read_total < len_s:
+                        json_obj, read = decoder.raw_decode(s[read_total:])
+                        read_total += read
+                        json_sboms.append(json_obj)
+
+                    stdin_consumed = True
+
+                # Pop the next object for this argument
+                try:
+                    json_obj = json_sboms.pop(0)
+                except IndexError:
+                    raise ValueError("Not enough SBOMs provided on stdin")
+
+                fmt = args.sbom_type
+
+                if kind == "base":
+                    base_json_obj = json_obj
+                    base_sbom_fmt = fmt
+                else:
+                    target_json_obj = json_obj
+                    target_sbom_fmt = fmt
+
+            else:
+                sbom_path = Path(sbom_arg)
+                if ".spdx" in sbom_path.suffixes:
+                    fmt = "spdx"
+                elif ".cdx" in sbom_path.suffixes:
+                    fmt = "cdx"
+                else:
+                    raise ValueError(f"cannot detect SBOM format for {sbom_arg}")
+
+                if kind == "base":
+                    base_path = sbom_path
+                    base_sbom_fmt = fmt
+                else:
+                    target_path = sbom_path
+                    target_sbom_fmt = fmt
+
+        if base_sbom_fmt != target_sbom_fmt:
+            raise ValueError("can not compare mixed SPDX and CycloneDX documents")
+
+        SBOMType.from_str(target_sbom_fmt).validate_dependency_availability()
+
+        from ..compare.compare import SbomCompare
+
+        bom = SbomCompare.run_compare(
+            fmt=target_sbom_fmt,
+            args=args,
+            base_json_obj=base_json_obj,
+            target_json_obj=target_json_obj,
+            base_path=base_path,
+            target_path=target_path,
+        )
+
+        sbom_type = SBOMType.SPDX if target_sbom_fmt == "spdx" else SBOMType.CycloneDX
+
+        if args.out == "-":
+            BomWriter.write_to_stream(bom, sbom_type, sys.stdout, args.validate)
+        else:
+            out = args.out
+            suffix = ".spdx.json" if target_sbom_fmt == "spdx" else ".cdx.json"
+            if not out.endswith(suffix):
+                out += suffix
+            BomWriter.write_to_file(bom, sbom_type, Path(out), args.validate)
+
+    @classmethod
+    def setup_parser(cls, parser):
+        cls.parser_add_generate_input_args(parser, default_out="extras")
+        parser.add_argument(
+            "-t",
+            "--sbom-type",
+            choices=["cdx", "spdx"],
+            help="expected SBOM type when reading SBOMs from stdin, required when reading from stdin",
+        )
+        parser.add_argument(
+            "base_sbom",
+            metavar="BASE_SBOM",
+            help="Path to the base (reference) SBOM file",
+        )
+        parser.add_argument(
+            "target_sbom",
+            metavar="TARGET_SBOM",
+            help="Path to the target (new) SBOM file",
+        )