1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
[](https://github.com/siemens/debsbom/actions/workflows/test.yml)
[](https://siemens.github.io/debsbom)
# debsbom - SBOM generator for Debian-based distributions
`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).
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 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.
## Usage
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} ...
SBOM tool for Debian systems.
positional arguments:
{generate,merge,download,source-merge,repack,export}
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
options:
-h, --help show this help message and exit
--version show program's version number and exit
-v, --verbose be more verbose
--progress report progress
--json make output machine readable
```
## Scope of the tool
The primary goal is to generate Software Bills of Materials (SBOMs) for Debian-based systems, focusing on security and license clearing requirements.
The `generate` command operates entirely offline, making it suitable for use in air-gapped networks or environments where internet connectivity is restricted.
### Goals
The `generate` command creates comprehensive SBOMs that include all installed software packages and their dependencies (binary, source package and
`built-using`[[1]](https://www.debian.org/doc/debian-policy/ch-relationships.html#s-built-using)).
These SBOM outputs are designed to serve as reliable input for vulnerability management systems and license compliance checks.
The tool provides auxiliary commands for package source retrieval. These enable users to:
1. Retrieve packages from Debian's upstream repositories and report missing packages.
2. Convert the multi-archive source packages into a single artifact (one archive per source package)
At its core, this tool was designed to fulfill these SBOM generation requirements while maintaining:
1. A minimal dependency footprint: avoid huge dependency graph of external software ecosystems (like Go or Rust)
2. Strict focus on Debian-specific package formats
3. Clear separation between binary packages and their corresponding source packages
4. Use official SPDX / CycloneDX libraries to ensure syntactic and semantic correctness
### Non Goals
- License and copyright text extraction from source packages
- Real-time vulnerability database integration
- Signing and attestation of generated artifacts
## Package Relations
A Debian distribution is composed of source packages and binary packages.
Binary packages are installed into the root filesystem, while the source packages are the originals from which those binaries are built.
Some binary packages are installed explicitly by the user; others appear automatically as dependencies of the explicitly‑installed packages.
The SBOM mirrors this relationship, using the `distro-package` entry as the single central node for traversing the package graph.
```
distro-package
├─ binary-package-foo
├─── source-package-foo
├─── binary-dep-of-foo
├─ binary-package-bar
├─── source-package-bar
└─── binary-dep-of-bar
```
### Source-Binary
To differentiate binary and source packages in the SBOM a different approach for each SBOM standard is required.
#### CycloneDX
In the CDX format it is currently not possible to mark a component as a source package. There is an ongoing discussion [[2]](https://github.com/CycloneDX/specification/issues/612) which, while looking promising, will not land in the standard for quite some time. In the meantime source packages can only be identified by their PURL by looking at the `arch=source` qualifier. The relationships between a binary and its source package is done with a simple dependency.
#### SPDX
We differentiate a source package by setting `"primaryPackagePurpose": "SOURCE"` as opposed to `LIBRARY` for binary packages. Their relationship is expressed with the `GENERATES` relation. For packages that are marked as `Built-Using` in the dpkg status file, we use the `GENERATED_FROM` relation. This expresses the same semantic in SPDX, but this way it can still be identified if it is a proper source/binary relationship or a built-using one.
## Limitations
### Vendor Packages
Vendor packages are currently not identified. Identifying them is important to emit the correct PURL. Right now we make no difference between vendor and official packages. That means we emit potentially incorrect PURLs for vendor packages.
Reliably and correctly identifying if a package is a vendor package or not is non-trivial without access to the internet. For this reason we do not attempt it. If you have vendor packages in your distribution we assume you know them, and if not you can identify them in postprocessing. A simple way is to use `debsbom download` and look for any packages that failed to download, or whose checksums do not match.
|
