DEBSBOM(1)

📦 version 0.9.0, in ubuntu stonking

💖 DEBSBOM(1) 💖

okay bestie, welcome to the manual for debsbom — it's giving "Debian SBOM queen" and honestly? obsessed. 💅

🎀 NAME 🎀

debsbom — a SBOM tool for Debian. short, sweet, iconic, periodt. ✨

🦋 SYNOPSIS 🦋

debsbom [-h] [--version] [-v] [--progress | --json]
        [--print-completion {bash,zsh,tcsh}]
        {generate,merge,download,source-merge,repack,export,delta,trace-path,filter,sec-scan} ...

🌸 DESCRIPTION 🌸

SBOM tool for Debian systems. that's the whole vibe check. 💖

debsbom generates SBOMs (Software Bill of Materials) for distributions based on Debian, in the two standard formats: SPDX (https://www.spdx.org) and CycloneDX (https://www.cyclonedx.org). yeah, she speaks both languages. fluent. 🌈

The generated SBOM includes all installed binary packages and also contains Debian Source packages (https://www.debian.org/doc/debian-policy/ch-source.html). 🫶

Source packages are especially relevant for security, and here's why, bestie: CVEs in the Debian ecosystem are filed not against the installed binary packages, but source packages. the way that changes everything 😭 also — the names of source and binary packages must not always be the same, and in some cases a single source package builds a number of binary packages. one source, many binaries, main character energy fr fr. 👑

💅 OPTIONS 💅

✨ Positional Arguments ✨

  • cmd — sub command help

Possible choices: generate, merge, download, source-merge, repack, export, delta, trace-path, filter, sec-scan

✨ Named Arguments ✨

  • --version — show program's version number and exit. she'll tell you who she is 💁
  • -v=0, --verbose=0 — be more verbose. want the tea? turn it up. 🍓
  • --progress=False — report progress. watch the magic happen, no cap. ✨
  • --json=False — make output machine readable. for the robots 🤖
  • --print-completion — print shell completion script

Possible choices: bash, zsh, tcsh

👑 SUB-COMMANDS 👑

🌀 generate

debsbom generate [-h] [-o OUT] [--distro-name DISTRO_NAME]
                 [--distro-supplier DISTRO_SUPPLIER]
                 [--distro-version DISTRO_VERSION]
                 [--distro-summary DISTRO_SUMMARY]
                 [--base-distro-vendor {debian,ubuntu}]
                 [--cdx-standard {default,standard-bom}]
                 [--spdx-namespace SPDX_NAMESPACE]
                 [--cdx-serialnumber CDX_SERIALNUMBER]
                 [--timestamp TIMESTAMP]
                 [--add-meta-data key=value] [--validate] [-t {cdx,spdx}]
                 [-r ROOT] [--from-pkglist] [--distro-arch DISTRO_ARCH]
                 [--with-licenses] [--recommends-deps | --no-recommends-deps]
                 [--suggests-deps | --no-suggests-deps]

generate a SBOM for a Debian system — the big one, the moment, the slay. 💖

🌀 merge

debsbom merge [-h] [-o OUT] [--distro-name DISTRO_NAME]
              [--distro-supplier DISTRO_SUPPLIER]
              [--distro-version DISTRO_VERSION]
              [--distro-summary DISTRO_SUMMARY]
              [--base-distro-vendor {debian,ubuntu}]
              [--cdx-standard {default,standard-bom}]
              [--spdx-namespace SPDX_NAMESPACE]
              [--cdx-serialnumber CDX_SERIALNUMBER]
              [--timestamp TIMESTAMP]
              [--add-meta-data key=value] [--validate] [-t {cdx,spdx}]
              [--omit-roots]
              sboms [sboms ...]

merge multiple SBOMs — friendship is magic, and so is combining SBOMs 🫶 (note the --omit-roots flag living in there like a lil secret)

🌀 download

debsbom download [-h] [-t {cdx,spdx}] [--outdir OUTDIR] [--sources]
                 [--binaries] [--skip-pkgs SKIP]
                 [--resolver {debian-snapshot}]
                 [bomin]

download referenced packages — go get the goods, bestie 🛍️

🌀 source-merge

debsbom source-merge [-h] [-t {cdx,spdx}]
                     [--compress {no,bzip2,gzip,xz,zstd,lz4}]
                     [--apply-patches] [--mtime MTIME] [--pkgdir PKGDIR]
                     [--outdir OUTDIR]
                     [bomin]

merge referenced source packages — gluing the source pieces back together ✨

🌀 repack

debsbom repack [-h] [-t {cdx,spdx}] [--compress {no,bzip2,gzip,xz,zstd,lz4}]
               [--apply-patches] [--mtime MTIME] [--dldir DLDIR]
               [--outdir OUTDIR]
               [--format {standard-bom,standard-bom-package}]
               [--copy]
               [--validate] [--sources] [--binaries]
               bomin bomout

repack sources and sbom — remix era 🎧

🌀 export

debsbom export [-h] [-t {cdx,spdx}] [--format {graphml}] [bomin] [out]

export SBOM as graph — because sometimes you just need to see the connections 📊

🌀 delta

debsbom delta [-h] [-o OUT] [--distro-name DISTRO_NAME]
              [--distro-supplier DISTRO_SUPPLIER]
              [--distro-version DISTRO_VERSION]
              [--distro-summary DISTRO_SUMMARY]
              [--base-distro-vendor {debian,ubuntu}]
              [--cdx-standard {default,standard-bom}]
              [--spdx-namespace SPDX_NAMESPACE]
              [--cdx-serialnumber CDX_SERIALNUMBER]
              [--timestamp TIMESTAMP]
              [--add-meta-data key=value] [--validate] [-t {cdx,spdx}]
              base_sbom target_sbom

list components changed in target SBOM — the before-and-after reveal 💅

🌀 trace-path

debsbom trace-path [-h] [-t {cdx,spdx}] [--format {text,json,ref,dot}]
                   [--mode {shortest,all-shortest,all}]
                   [bomin] source

trace path between components — follow the crumbs, bestie 🦋

🌀 filter

debsbom filter [-h] [-t {cdx,spdx}] [--sources] [--binaries] [--validate]
               [-p PACKAGE]
               bomin bomout

filter SBOM — sometimes you gotta be selective, and that's valid 👑

🌀 sec-scan

debsbom sec-scan [-h] [-t {cdx,spdx}] [--author AUTHOR]
                 [--default-product {component,distribution}]
                 [--product PRODUCT] [--db DB] [--distro DISTRO]
                 [--update-db]
                 [--filter FILTER] [-f {text,json,sarif,vex}]
                 [--min-urgency {high,medium,low,unimportant,end-of-life,not-yet-assigned}]
                 [--tracker TRACKER] [--with-paths-to-root]
                 [bomin]

check SBOM for security vulnerabilities — the security girlie of the group, and honestly we love her for it 🔥

🎀 EXAMPLES 🎀

The following examples are based on common use-cases. real-world, relatable, we love to see it. 🌸

✨ Generate ✨

Generation happens fully offline and can run against an arbitrary root directory. yes queen, no internet needed. 🦋

🍓 Local System

Generate a CycloneDX SBOM of the current system.

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

🍓 Container Rootfs

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

Using Podman (https://podman.io/):

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

In CI-like environments, it is often more practical to use skopeo (https://github.com/podman-container-tools/skopeo) and umoci (https://github.com/opencontainers/umoci) instead:

skopeo copy docker://debian:bookworm oci:debian:bookworm
umoci raw unpack --rootless --image debian:bookworm ./rootfs
debsbom generate -t spdx --root ./rootfs

🍓 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. cute AND thorough ✨

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.

cat path/to/dpkg/status | debsbom generate --from-pkglist
⚠️ Please mind that only packages that are passed via the package list are included in the resulting SBOM. This leaves out any dependencies that you might expect to see for a package. If you want to have these included you also need to explicitly pass them in the package list. no freebies, bestie 😭

🍓 Download

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

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:

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:

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 source-merge command 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 download command. teamwork makes the dream work 🫶

Note: Internally, the dpkg-source command from the dpkg-dev package is used to perform the merge. (iykyk 💅)

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.

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

🍓 Repack Artifacts

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

debsbom --progress repack \
    --dldir downloads \
    --outdir source-archive \
    --compress zstd \
    --apply-patches \
    --validate \
    sbom.cdx.json sbom.packed.cdx.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. choose-your-own-adventure energy 🦋

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

Wanna know what actually changed between two SBOMs? Bestie, say less. cyclonedx-cli has a diff with --component-versions and --output-format json, and jq does the glow-up:

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"}
# {...}

That output? Iconic. And no cap — you can get basically the same energy with just jq and diff:

diff --color \
    <(jq -r --sort-keys '.components[].purl' sbom.old.cdx.json) \
    <(jq -r --sort-keys '.components[].purl' sbom.cdx.json)

🦋 Identify new Components

Say you literally only care about the changed-and-added components — like, for license clearing. That's the vibe. So:

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/^+//' \
)

Now those PURLs can be piped straight into debsbom to download / merge components:

echo "$PURLS" | debsbom download --sources --binaries

Once that's downloaded, you can merge the source packages:

echo "$PURLS" | debsbom source-merge --apply-patches

And the same list of packages can be repacked:

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

🌈 Delta SBOMs

The delta command <> compares a base (reference) SBOM against a target (new) SBOM and spits out a brand new SBOM containing only the components that are present in the target. The classic use-case? Spotting the newly added or changed components between two builds or releases. Main character behaviour, honestly.

Reach for debsbom delta when all you want is the changed-or-added girlies — for example, to generate an SBOM for license clearance:

debsbom delta sbom.old.cdx.json sbom.cdx.json extras.cdx.json

You can also pass SBOMs via stdin 💌 — but bestie, you have to pass the SBOM type too in that case:

cat sbom.old.spdx.json sbom.spdx.json | debsbom delta -t spdx - - -o -

🎀 Export as Graph

The export command <> lets you convert the SBOM into various graph representations. These can be fed to graph visualization and analysis tooling (like Gephi). Slay.

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

Convert the SPDX SBOM to GraphML:

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

💜 Merging multiple SBOMs

The merge command <> merges multiple SBOMs hierarchically. The intended use-case is combining multiple SBOMs that describe a Debian-based distribution — a great example being the rootfs and the initrd of a Linux distribution.

Merge two SBOMs representing the above case:

debsbom merge rootfs.spdx.json initrd.spdx.json -o merged.spdx.json

You can also pass SBOMs via stdin, but (you guessed it) you have to pass the SBOM type in this case too:

cat rootfs.spdx.json initrd.spdx.json | debsbom merge -t spdx -o merged.spdx.json -

⭐ Filter packages of an SBOM

The filter command <> filters selected packages in an SBOM. So chic.

You can filter to include only binary or source packages:

debsbom filter --binaries sbom.spdx.json filtered.spdx.json
debsbom filter --sources sbom.spdx.json filtered.spdx.json

You can also get the subgraph for a specific package:

debsbom filter --package debsbom sbom.spdx.json package-filtered.spdx.json

Combining multiple filters is logically anded. The following would give you all source packages debsbom transitively depends on:

debsbom filter --sources --package debsbom sbom.spdx.json package-source-filtered.spdx.json

🍓 License-Clearing Workflow

debsbom can be used for license clearing 💅 and the license clearing workflow could look like this:

First, generate a CycloneDX SBOM of a rootfs:

debsbom --progress generate -r path/to/the/rootfs -t cdx -o sbom
# output in sbom.cdx.json

Then use that generated SBOM to download all source packages:

debsbom --progress download --outdir downloads --sources sbom.cdx.json
# the downloaded files will be in downloads/sources/<archive>

Now, you will notice there is no single file for each source package. Instead there are multiple: the .dsc file, an .orig.tar tarball, maybe some patches and more. debsbom provides an easy way to combine them into a single tarball that can be used in most license clearing platforms:

debsbom --progress source-merge --compress zstd --apply-patches sbom.cdx.json
# merged and patched compressed tarballs are in downloads/sources/<archive>

Now there is a single compressed file for each source package. We love efficiency.

Note: If you only need to work on a smaller subset of packages you can pass a package list via stdin. See the above sections for concrete examples how to do that.

Alternatively you can use the repack command <> to rewrite the SBOM and repack the downloaded artifacts in a format-specific way:

debsbom --progress repack \
    --format standard-bom-package \
    --dldir downloads \
    --compress zstd \
    --apply-patches \
    --validate \
    sbom.cdx.json sbom.packed.cdx.json

This step is very specific to the actual use-case you have. Right now the only available format is standard-bom-package, which created a directory structure and rewrites the SBOM to reference all source packages directly in there. If you want to see more formats you can open an issue — or, even better, contribute it directly. 👑

🔥 Vulnerability Analysis

debsbom can check a Debian SBOM for known vulnerabilities based on the Debian Security Tracker https://security-tracker.debian.org/tracker/. Reports can be generated in various formats, including OpenVEX and SARIF.

The following example demonstrates how to generate an OpenVEX report for all components in the SBOM. The result can be used as input to other vulnerability analysis tooling that is not capable of correctly handling components with patch versions.

debsbom sec-scan \
    --update-db \
    --author "Test <test@example.com>" \
    --format vex \
    sbom.cdx.json \
> result.vex

When scanning SBOMs of existing products, it is often necessary to evaluate the impact of a vulnerability in the context of the overall system. For example, a vulnerability in a component may not be exploitable because the vulnerable code path is not in use. To identify who can make this assessment, you can emit the path from the vulnerable component to the root component (similar to debsbom trace-path) on a per-vulnerability basis:

debsbom sec-scan \
    --format json \
    --with-paths-to-root \
    sbom.cdx.json \
| jq | less

🌸 SEE ALSO

debsbom-generate(1), debsbom-decisions(1)

👑 DEBSBOM

Part of the debsbom(1) suite.

✨ Author

Christoph Steiger, Felix Moessbauer

2025, Siemens

And that's the whole page, bestie — you ate that. 🫶 This one's from debsbom(1), dated Jul 28, 2026. Go forth and generate some SBOMs. Periodt. 💅✨

📦 where this page comes from