DISTRO2SBOM

The DISTRO2SBOM generates a SBOM (Software Bill of Materials) for either an installed application or a complete system installation in a number of formats including SPDX and CycloneDX. An SBOM for an installed package will identify all of its dependent components.

It is intended to be used as part of a continuous integration system to enable accurate records of SBOMs to be maintained and also to support subsequent audit needs to determine if a particular component (and version) has been used.

Installation

To install use the following command:

pip install distro2sbom

Alternatively, just clone the repo and install dependencies using the following command:

pip install -U -r requirements.txt

The tool requires Python 3 (3.7+). It is recommended to use a virtual python environment especially if you are using different versions of python. virtualenv is a tool for setting up virtual python environments which allows you to have all the dependencies for the tool set up in a single environment, or have different environments set up for testing using different versions of Python.

Usage

usage: distro2sbom [-h] [--distro {rpm,deb,windows,auto}] [-i INPUT_FILE] [-n NAME] [-r RELEASE] [-p PACKAGE] [-s] [--root ROOT] [--distro-namespace DISTRO_NAMESPACE] [-d] [--sbom {spdx,cyclonedx}]
                   [--format {tag,json,yaml}] [-o OUTPUT_FILE] [-V]

Distro2Sbom generates a Software Bill of Materials for the specified package or distribution.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit

Input:
  --distro {rpm,deb,windows,auto}
                        type of distribution (default: auto)
  -i INPUT_FILE, --input-file INPUT_FILE
                        name of distribution file
  -n NAME, --name NAME  name of distribution
  -r RELEASE, --release RELEASE
                        release identity of distribution
  -p PACKAGE, --package PACKAGE
                        identity of package within distribution
  -s, --system          generate SBOM for installed system
  --root ROOT           location of distribution packages
  --distro-namespace DISTRO_NAMESPACE
                        namespace for distribution

Output:
  -d, --debug           add debug information
  --sbom {spdx,cyclonedx}
                        specify type of sbom to generate (default: spdx)
  --format {tag,json,yaml}
                        specify format of software bill of materials (sbom) (default: tag)
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        output filename (default: output to stdout)

Operation

The --distro option is used to identify the type of distribution. The default option is auto which attempts to determine the type of distribution by searching for the presence of key applications required by the tool. If none of the required applications are found, the tool terminates.

The --name option and --release option is used to identify the name and release of the distribution. These options are optional but if they are specified, values for both options are required. If they are not specified, values for these options shall be obtained from system files installed on the system.

The --input-file option is used to provide a filename containing the list of packages installed on the system. The format of the file is dependent on the specified --distro option.

• deb. The file used is the output of the following command

  dpkg -l > [filename.out]

  Sample file contents

  Desired=Unknown/Install/Remove/Purge/Hold
  | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
  |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
  ||/ Name                                             Version                             Architecture Description
  +++-================================================-===================================-============-==================================================================================
  ii  acl                                              2.3.1-1                             amd64        access control list - utilities
  ii  adduser                                          3.129                               all          add and remove users and groups
  ii  adwaita-icon-theme                               43-1                                all          default icon theme of GNOME
  ii  alien                                            8.95.6                              all          convert and install rpm and other packages
  ii  alsa-tools                                       1.2.5-2                             amd64        Console based ALSA utilities for specific hardware

• rpm. The file used is the output of the following command. Note that it is recommended to sort the list of files as this makes it easier to find the packages in the SBOM.

  rpm -qa | sort > [filename.out]

  Sample file contents

  accountsservice-0.6.55-10.el9.x86_64
  accountsservice-libs-0.6.55-10.el9.x86_64
  acl-2.3.1-3.el9.x86_64
  adcli-0.9.1-7.el9.x86_64
  adwaita-cursor-theme-40.1.1-3.el9.noarch
  adwaita-icon-theme-40.1.1-3.el9.noarch

• windows. The file used is the output of the following command

  get-wmiobject -class win32_product | Out-file -filePath [filename.out]

  Sample file contents

  IdentifyingNumber : {....}
  Name              : Python 3.10.5 Utility Scripts (64-bit)
  Vendor            : Python Software Foundation
  Version           : 3.10.5150.0
  Caption           : Python 3.10.5 Utility Scripts (64-bit)
  

If the specified filename is not found, the tool will terminate.

The --package option is used to identify the name of a package or application installed on the system. If the specified package or application is not found, the tool terminates. This option is not supported if the --distro option is set to 'windows'.

The --system option is used to generate an SBOM for all the applications installed on the system. Note that this option will take some time to complete as it is dependent on the number of installed applications. This option is not supported if the --distro option is set to 'windows'.

The --root option is used to specify an alternative directory location for the installed packages. This option only applies for 'deb' distributions.

The --disto-namespace option is used to specify a namespace to be included in the generated PURL identifiers for the packages.

At least one of the --input-file, --package or --system options must be specified. If multiple options are specified, the --input-file option followed by the --system option will be assumed.

The --sbom option is used to specify the format of the generated SBOM (the default is SPDX). The --format option can be used to specify the formatting of the SBOM (the default is Tag Value format for a SPDX SBOM). JSON format is supported for both SPDX and CycloneDX SBOMs.

The --output-file option is used to control the destination of the output generated by the tool. The default is to report to the console but can be stored in a file (specified using --output-file option).

Examples

SBOM for an Installed Package

To generate an SBOM for the installed zip package.

distro2sbom --distro auto --name <distro name> --release <distro release> --package zip

This will automatically detect the type of distribution and generate an SBOM in SPDX Tag value format to the console.

SBOM for Distribution

To generate an SBOM for a system distribution.

distro2sbom --distro deb --name <distro name> --release <distro release> --input-file <distrofile> --sbom cyclonedx --output-file <distrooutfile>

This will generate an SBOM in CycloneDX JSON value for a distribution file in dpkg format (indicated by the 'deb' option)

SBOM for System

To generate an SBOM for an installed system, obtaining the name and release of the system from installed system files.

distro2sbom --distro deb --system --format json --output-file <distrooutfile>

This will generate an SBOM in SPDX JSON value for a distribution file in dpkg format (indicated by the 'deb' option)

Specific options for rpm/yum based distro

The following [optional] environment variable are available to customize rpm and yum commands used by the tool. This can be usefull for example to enable/disable some repo or to support chrooted environments.

• DISTRO2SBOM_ROOT_PATH The path prefix where to get /etc/os-release
• DISTRO2SBOM_RPM_OPTIONS Additional options passed to rpm commands (used by rpm -qa to list all packages and rpm -qi <pkg> to query information on a package)
• DISTRO2SBOM_YUM_OPTIONS Additional options passed to yum commands (used by yum repoquery --deplist <pkg> to get dependencies)

export DISTRO2SBOM_ROOT_PATH=/path-to-distrib/slash
export DISTRO2SBOM_RPM_OPTIONS="--root /path-to-distrib/slash"
export DISTRO2SBOM_YUM_OPTIONS="--installroot=/path-to-distrib/slash --setopt=reposdir=/path-to-distrib/repos --setopt=install_weak_deps=False --repo=my-repo"
distro2sbom --distro rpm --system --sbom cyclonedx --format json --output-file <distrooutfile>

This will generate an SBOM in CYCLONEDX JSON value for a chrooted distribution located at /path-to-distrib/slash

Licence

Licenced under the Apache 2.0 Licence.

Limitations

This tool is meant to support software development and security audit functions. However, the usefulness of the tool is dependent on the SBOM data which is provided to the tool. Unfortunately, the tool is unable to determine the validity or completeness of such a SBOM file; users of the tool are therefore reminded that they should assert the quality of any data which is provided to the tool.

When processing and validating licenses, the application will use a set of synonyms to attempt to map some license identifiers to the correct SPDX License Identifiers. However, the user of the tool is reminded that they should assert the quality of any data which is provided by the tool particularly where the license identifier has been modified.

Dependencies between applications are only produced for the --package and --system options.

The --package option is not supported if the --distro option is set to 'windows'.

Whilst PURL and CPE references are automatically generated for components, the accuracy of such references cannot be guaranteed as they are dependent on the validity of the data associated with the component.

Feedback and Contributions

Bugs and feature requests can be made via GitHub Issues.