.\" Man page generated from reStructuredText .\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "DEBSBOM" "1" "Apr 14, 2026" "" "debsbom" .SH NAME debsbom \- a SBOM tool for Debian .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom [\-h] [\-\-version] [\-v] [\-\-progress | \-\-json] [\-\-print\-completion {bash,zsh,tcsh}] {generate,merge,download,source\-merge,repack,export,delta,trace\-path,filter} ... .EE .UNINDENT .UNINDENT .SH DESCRIPTION .sp SBOM tool for Debian systems. .sp \fBdebsbom\fP generates SBOMs (Software Bill of Materials) for distributions based on Debian in the two standard formats SPDX \% and CycloneDX \%\&. .sp The generated SBOM includes all installed binary packages and also contains Debian Source packages \%\&. .sp Source packages are especially relevant for security as CVEs in the Debian ecosystem are filed not against the installed binary packages, but source packages. 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. .SH OPTIONS .sp \fBPositional Arguments\fP .PP .INDENT 0.0 .TP .B cmd sub command help .sp Possible choices: generate, merge, download, source\-merge, repack, export, delta, trace\-path, filter .UNINDENT .sp \fBNamed Arguments\fP .PP .INDENT 0.0 .TP .B \-\-version show program\(aqs version number and exit .TP .B \-v=0\fP,\fB \-\-verbose=0 be more verbose .TP .B \-\-progress=False report progress .TP .B \-\-json=False make output machine readable .TP .B \-\-print\-completion print shell completion script .sp Possible choices: bash, zsh, tcsh .UNINDENT .SH SUB-COMMANDS .INDENT 0.0 .TP \fBdebsbom 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]\fP generate a SBOM for a Debian system .TP \fBdebsbom 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 ...]\fP merge multiple SBOMs .TP \fBdebsbom download [\-h] [\-t {cdx,spdx}] [\-\-outdir OUTDIR] [\-\-sources] [\-\-binaries] [\-\-skip\-pkgs SKIP] [\-\-resolver {debian\-snapshot}] [bomin]\fP download referenced packages .TP \fBdebsbom source\-merge [\-h] [\-t {cdx,spdx}] [\-\-compress {no,bzip2,gzip,xz,zstd,lz4}] [\-\-apply\-patches] [\-\-mtime MTIME] [\-\-pkgdir PKGDIR] [\-\-outdir OUTDIR] [bomin]\fP merge referenced source packages .TP \fBdebsbom 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\fP repack sources and sbom .TP \fBdebsbom export [\-h] [\-t {cdx,spdx}] [\-\-format {graphml}] [bomin] [out]\fP export SBOM as graph .TP \fBdebsbom 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\fP list components changed in target SBOM .TP \fBdebsbom trace\-path [\-h] [\-t {cdx,spdx}] [\-\-format {text,json,ref,dot}] [\-\-mode {shortest,all\-shortest,all}] [bomin] source\fP trace path between components .TP \fBdebsbom filter [\-h] [\-t {cdx,spdx}] [\-\-sources] [\-\-binaries] [\-\-validate] bomin bomout\fP filter SBOM by sources or binaries .UNINDENT .SH EXAMPLES .sp The following examples are based on common use\-cases. .SS Generate .sp Generation happens fully offline and can run against an arbitrary root directory. .SS Local System .sp Generate a CycloneDX SBOM of the current system. .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom \-\-progress generate \-t cdx \-o sbom # output in sbom.cdx.json .EE .UNINDENT .UNINDENT .SS Container Rootfs using Podman .sp Create the SBOM of a rootless example container. The \fBdebsbom\fP tool hereby is used from the host (e.g. from a Python venv). .INDENT 0.0 .INDENT 3.5 .sp .EX CRT=$(podman create debian:bookworm) CHROOT=$(podman unshare podman mount $CRT) podman unshare debsbom generate \-t spdx \-\-root $CHROOT .EE .UNINDENT .UNINDENT .SS From Package List .sp Create the SBOM from a package list. The so provided packages will still be enriched with any available data from the apt cache. .INDENT 0.0 .INDENT 3.5 .sp .EX echo \(dqhtop 3.4.1\-5 amd64\(dq | debsbom generate \-\-from\-pkglist # or in isar manifest format echo \(dqjson\-c|0.16\-2|libjson\-c5:amd64|0.16\-2\(dq | debsbom generate \-\-from\-pkglist # or with PURLs echo \(dqpkg:deb/debian/htop@3.4.1\-5?arch=amd64\(dq | debsbom generate \-\-from\-pkglist .EE .UNINDENT .UNINDENT .sp 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\(aqt have a chroot and want to create the sbom just from the data in the file. .INDENT 0.0 .INDENT 3.5 .sp .EX cat path/to/dpkg/status | debsbom generate \-\-from\-pkglist .EE .UNINDENT .UNINDENT .SS Download .sp Lookup all packages on the \fBsnapshot.debian.org\fP mirror and download all binary and source artifacts referenced in an SBOM: .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom \-\-progress \e 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 .EE .UNINDENT .UNINDENT .sp It is also possible to download multiple packages by name, version and architecture: .INDENT 0.0 .INDENT 3.5 .sp .EX cat < 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 \%<>\&. .sp \fBNote:\fP .INDENT 0.0 .INDENT 3.5 Internally, the \fBdpkg\-source\fP command from the \fBdpkg\-dev\fP package is used to perform the merge. .UNINDENT .UNINDENT .sp The following example merges all debian source packages referenced in the \fBsbom.cdx.json\fP, applies the debian patches and compresses the new artifacts with ZStandard. .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom \-\-progress \e source\-merge \e \-\-compress zstd \e \-\-apply\-patches \e sbom.cdx.json .EE .UNINDENT .UNINDENT .SS Repack Artifacts .sp 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 \fBstandard\-bom\-package\fP source distribution archive. .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom \-\-progress repack \e \-\-dldir downloads \e \-\-outdir source\-archive \e \-\-compress zstd \e \-\-apply\-patches \e \-\-validate \e sbom.cdx.json sbom.packed.cdx.json .EE .UNINDENT .UNINDENT .sp 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 \(dqto\-be\-processed\(dq packages via stdin. .INDENT 0.0 .INDENT 3.5 .sp .EX echo \(dqbash 5.2.37\-2 source\(dq | debsbom \-v repack sbom\-in.json sbom\-out.json .EE .UNINDENT .UNINDENT .SS Compare SBOMs .sp The SBOMs produced by \fBdebsbom\fP can be further processed with existing tools – for example, the CycloneDX CLI \%\&. Comparing two SBOMs directly is outside the scope of \fBdebsbom\fP, but you can determine which components have changed by using a short snippet such as the one shown below. .SS Locate Changes .INDENT 0.0 .INDENT 3.5 .sp .EX cyclonedx\-cli diff \-\-component\-versions \-\-output\-format json \e sbom.old.cdx.json sbom.cdx.json | \e jq \-r \(aq.componentVersions[] | select(.added!=[] or .removed!=[]) | {\(dqadded\(dq: .added[0].purl, \(dqremoved\(dq: .removed[0].purl}\(aq # {\(dqadded\(dq, \(dqpurl\-a\-1.1\(dq, \(dqremoved\(dq: \(dqpurl\-a\-1.0\(dq} # {...} .EE .UNINDENT .UNINDENT .sp A similar output can be generated by just using \fBjq\fP and \fBdiff\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX diff \-\-color \e <(jq \-r \-\-sort\-keys \(aq.components[].purl\(aq sbom.old.cdx.json) \e <(jq \-r \-\-sort\-keys \(aq.components[].purl\(aq sbom.cdx.json) .EE .UNINDENT .UNINDENT .SS Identify new Components .sp Consider you only want to know the changed and added components, e.g. for license clearing. .INDENT 0.0 .INDENT 3.5 .sp .EX PURLS=$( \e diff \-U0 \e <(jq \-r \-\-sort\-keys \(aq.components[].purl\(aq sbom.old.cdx.json) \e <(jq \-r \-\-sort\-keys \(aq.components[].purl\(aq sbom.cdx.json) \e | grep ^+pkg | sed \(aqs/^+//\(aq \e ) .EE .UNINDENT .UNINDENT .sp The PURLs can be used as input to debsbom to download / merge components: .INDENT 0.0 .INDENT 3.5 .sp .EX echo \(dq$PURLS\(dq | debsbom download \-\-sources \-\-binaries .EE .UNINDENT .UNINDENT .sp Once downloaded, it is possible to merge the source packages: .INDENT 0.0 .INDENT 3.5 .sp .EX echo \(dq$PURLS\(dq | debsbom source\-merge \-\-apply\-patches .EE .UNINDENT .UNINDENT .sp And the same list of packages can be repacked: .INDENT 0.0 .INDENT 3.5 .sp .EX echo \(dq$PURLS\(dq | debsbom repack \e \-\-apply\-patches sbom.cdx.json \e sbom.cdx.repacked.json .EE .UNINDENT .UNINDENT .SS Delta SBOMs .sp The delta command \%<> 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. .sp Use \fBdebsbom delta\fP when you only want to see changed or added components, e.g., to generate an SBOM for license clearance. .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom delta sbom.old.cdx.json sbom.cdx.json extras.cdx.json .EE .UNINDENT .UNINDENT .sp You can also pass SBOMs via stdin, but you also have to pass the SBOM type in this case: .INDENT 0.0 .INDENT 3.5 .sp .EX cat sbom.old.spdx.json sbom.spdx.json | debsbom delta \-t spdx \- \- \-o \- .EE .UNINDENT .UNINDENT .SS Export as Graph .sp The export command \%<> allows one to convert the SBOM into various graph representations. These can be used as input to graph visualization and analysis tooling (like Gephi). .sp \fBNote:\fP .INDENT 0.0 .INDENT 3.5 We recommend to use the SPDX format as input, as this describes inter package relations more precisely. .UNINDENT .UNINDENT .sp Convert the SPDX SBOM to GraphML: .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom export sbom.spdx.json sbom\-graph.graphml .EE .UNINDENT .UNINDENT .SS Merging multiple SBOMs .sp The merge command \%<> merges multiple SBOMs hierarchically. The intended use\-case is to combine multiple SBOMs describing a Debian\-based distribution. A good example is the rootfs and the initrd of a Linux distribution. .sp Merge two SBOMs representing the above case: .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom merge rootfs.spdx.json initrd.spdx.json \-o merged.spdx.json .EE .UNINDENT .UNINDENT .sp You can also pass SBOMs via stdin, but you also have to pass the SBOM type in this case: .INDENT 0.0 .INDENT 3.5 .sp .EX cat rootfs.spdx.json initrd.spdx.json | debsbom merge \-t spdx \-o merged.spdx.json \- .EE .UNINDENT .UNINDENT .SS License\-Clearing Workflow .sp \fBdebsbom\fP can be used for license clearing. The license clearing workflow could look like this: .sp First, generate a CycloneDX SBOM of a rootfs: .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom \-\-progress generate \-r path/to/the/rootfs \-t cdx \-o sbom # output in sbom.cdx.json .EE .UNINDENT .UNINDENT .sp Use the generated SBOM to download all source packages: .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom \-\-progress download \-\-outdir downloads \-\-sources sbom.cdx.json # the downloaded files will be in downloads/sources/ .EE .UNINDENT .UNINDENT .sp You will notice that there is no single file for each source package. Instead there is multiple: the .dsc file, an .orig.tar tarball, maybe some patches and more. \fBdebsbom\fP provides an easy way to combine them into a single tarball that can be used in most license clearing platforms: .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom \-\-progress source\-merge \-\-compress zstd \-\-apply\-patches sbom.cdx.json # merged and patched compressed tarballs are in downloads/sources/ .EE .UNINDENT .UNINDENT .sp Now there is a single compressed file for each source package. .sp \fBNote:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .sp Alternatively you can use the repack command \%<> to rewrite the SBOM and repack the downloaded artifacts in a format\-specific way: .INDENT 0.0 .INDENT 3.5 .sp .EX debsbom \-\-progress repack \e \-\-format standard\-bom\-package \e \-\-dldir downloads \e \-\-compress zstd \e \-\-apply\-patches \e \-\-validate \e sbom.cdx.json sbom.packed.cdx.json .EE .UNINDENT .UNINDENT .sp This step is very specific to the actual use\-case you have. Right now the only available format is \fBstandard\-bom\-package\fP, 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. .SH SEE ALSO .sp \fBdebsbom\-generate(1)\fP, \fBdebsbom\-decisions(1)\fP .SH DEBSBOM .sp Part of the \fBdebsbom(1)\fP suite. .SH Author Christoph Steiger, Felix Moessbauer .SH Copyright 2025, Siemens .\" End of generated man page.