Examples
========

The following examples are based on common use-cases.

Generate
~~~~~~~~

Generation happens fully offline and can run against an arbitrary root directory.

Local System
^^^^^^^^^^^^

Generate a CycloneDX SBOM of the current system.

.. code-block:: bash

    debsbom --progress generate -t cdx -o sbom
    # output in sbom.cdx.json

Container Rootfs using Podman
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create the SBOM of a rootless example container.
The ``debsbom`` tool hereby is used from the host (e.g. from a Python venv).

.. code-block:: bash

    CRT=$(podman create debian:bookworm)
    CHROOT=$(podman unshare podman mount $CRT)
    podman unshare debsbom generate -t spdx --root $CHROOT

From Package List
^^^^^^^^^^^^^^^^^

Create the SBOM from a package list. The so provided packages will still be enriched with any available data from the apt cache.

.. code-block:: bash

    echo "htop 3.4.1-5 amd64" | debsbom generate --from-pkglist
    # or in isar manifest format
    echo "json-c|0.16-2|libjson-c5:amd64|0.16-2" | debsbom generate --from-pkglist
    # or with PURLs
    echo "pkg:deb/debian/htop@3.4.1-5?arch=amd64" | debsbom generate --from-pkglist

It further is possible to inject a dpkg status file via stdin (e.g. if you only have that file).
The data is then also resolved from the apt-cache (if available), but this usually only makes sense if you don't have a
chroot and want to create the sbom just from the data in the file.

.. code-block:: bash

    cat path/to/dpkg/status | debsbom generate --from-pkglist

Download
~~~~~~~~

Lookup all packages on the ``snapshot.debian.org`` mirror and download all binary and source artifacts referenced in an SBOM:

.. code-block:: bash

    debsbom --progress \
        download --outdir downloads --sources --binaries sbom.cdx.json
    find downloads -mindepth 1 -maxdepth 1
    # downloads/.cache   <- debsbom metadata to map packages to artifacts
    # downloads/sources  <- files related to source packages (e.g. .dsc, .orig.tar)
    # downloads/binaries <- .deb files

It is also possible to download multiple packages by name, version and architecture:

.. code-block:: bash

    cat <<EOF | debsbom download --binaries --sources
    cpp 4:12.2.0-3 amd64
    guestfs-tools 1.52.3-1 source
    EOF

Alternatively, the download can be executed from the container image:

.. code-block:: bash

    echo "guestfs-tools 1.52.3-1 source" | \
    docker run -v$(pwd)/downloads:/mnt/downloads -i ghcr.io/siemens/debsbom:latest \
        debsbom download --outdir /mnt/downloads --sources

Merge Source Packages
~~~~~~~~~~~~~~~~~~~~~

Debian source packages consist of a ``.dsc`` file along with one or more related artifacts.
The :doc:`commands/source-merge` takes care of merging all referenced artifacts of a debian source package into a single archive.
All referenced files have to be downloaded upfront, by using the :doc:`commands/download`.

.. note::
    Internally, the ``dpkg-source`` command from the ``dpkg-dev`` package is used to perform the merge.

The following example merges all debian source packages referenced in the ``sbom.cdx.json``, applies the debian patches and compresses the new artifacts with ZStandard.

.. code-block:: bash

    debsbom --progress \
        source-merge \
            --compress zstd \
            --apply-patches \
            sbom.cdx.json

Repack Artifacts
~~~~~~~~~~~~~~~~

The :doc:`commands/repack` is similar to the :doc:`commands/source-merge` but performs additional steps to re-layout the downloaded artifacts and recreate the SBOM.
The following example generates a ``standard-bom`` source distribution archive.

.. code-block:: bash

    debsbom --progress repack \
        --dldir downloads \
        --outdir source-archive \
        --compress zstd \
        --apply-patches \
        --validate \
        sbom.spdx.json sbom.packed.spdx.json

It further is possible to only repack (and update in the SBOM) a subset of packages.
For that, provide both an SBOM, as well as a set of "to-be-processed" packages via stdin.

.. code-block:: bash

    echo "bash 5.2.37-2 source" | debsbom -v repack sbom-in.json sbom-out.json

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)

Identify new Components
^^^^^^^^^^^^^^^^^^^^^^^

Consider you only want to know the changed and added components, e.g. for license clearing.

.. 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:

.. 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:

.. code-block:: bash

    echo "$PURLS" | debsbom repack \
        --apply-patches
        sbom.cdx.json \
        sbom.cdx.repacked.json

Export as Graph
~~~~~~~~~~~~~~~

The :doc:`commands/export` allows to convert the SBOM into various graph representations.
These can be used as input to graph visualization and analysis tooling (like Gephi).

.. note::
    We recommend to use the SPDX format as input, as this describes inter package relations
    more precisely.

Convert the SPDX SBOM to GraphML:

.. code-block:: bash

    debsbom export sbom.spdx.json sbom-graph.graphml