API Reference

Warning

The API is not stable (yet) and by that should not be imported into third party modules.

SBOM Utilities

class debsbom.sbom.BOM_Standard(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Controls the data representation and added values in the SBOM

class debsbom.sbom.BomSpecific

Mixin to denote that a class processes bom type specific data

classmethod sbom_type() → SBOMType

Type of SBOM this class can handle

class debsbom.sbom.CDXType

CycloneDX type mixin

class debsbom.sbom.Reference(target: str, is_source: bool = False)

Generic reference in a SBOM.

as_str(sbom_type: SBOMType) → str

Return a string representation for the given SBOM type.

classmethod lookup(pkg: BinaryPackage, dep: Dependency, sbom_type: SBOMType, known_refs: Set[str]) → str | None

For imprecise references (without architecture), locate the matching reference id within the id passed as known_refs. Returns None if not found. To avoid downstream double caching of IDs in two formats, we pass the known_refs as a string set.

static make_from_dep(dep: Dependency, to_arch: str | None = None) → Reference

Return a reference to a package from a dependency. If the dependency does not specify an architecture, the caller is responsible for providing this in to_arch.

static make_from_pkg(pkg: Package) → Reference

Return a reference to a package in the list of all packages. This representation must match the one returned by make_from_dep.

class debsbom.sbom.SBOMType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Supported SBOM types

CycloneDX = (0,)

CycloneDX

SPDX = (1,)

SPDX

class debsbom.sbom.SPDXType

SPDX type mixin

Package Representations

class debsbom.dpkg.package.BinaryPackage(name: str, version: str | Version, section: str | None = None, maintainer: str | None = None, architecture: str | None = None, source: Dependency | None = None, depends: list[Dependency] = [], built_using: list[Dependency] = [], description: str | None = None, homepage: str | None = None, checksums: dict[ChecksumAlgo, str] | None = None, manually_installed: bool = True)

Incomplete representation of a Debian binary package.

classmethod from_dep822(package) → BinaryPackage

Create a BinaryPackage from a dep822 representation.

property locator: str

Return the name (and path if available) of the .deb file

merge_with(other: BinaryPackage)

Copy properties from other which are unset on our side. Merge lists and dicts. Or booleans.

purl(vendor='debian') → PackageURL

Return the PURL of the package.

property unique_depends

Returns the unique dependencies without version. The raw dependencies can include version specifiers, but as only a single version can be installed at a time, we ignore them.

class debsbom.dpkg.package.ChecksumAlgo(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

class debsbom.dpkg.package.Dependency(name: str, archqual: str | None = None, version: tuple[str, Version] | None = None, arch: str | None = None, restrictions: str | None = None)

Representation of a dependency for a package.

class debsbom.dpkg.package.Package(name: str, version: str | Version)

Base class for binary and source packages.

property filename: str

Return the filename part from the locator of a package.

classmethod from_purl(purl: str) → Package

Create a package from a PURL. Note, that the package only encodes information that can be derived from the PURL.

classmethod inject_src_packages(binpkgs: Iterable[BinaryPackage]) → Iterable[Package]

Create and inject referenced source packages

merge_with(other: Package)

Copy the corresponding values of the other package for each unset field.

classmethod parse_pkglist_stream(stream: IO) → PkgListStream

Parses a stream of space separated tuples describing packages (name, version, arch), PURLs, isar manifest data (<src name>|<src version>|<bin name>:<bin arch>|<bin version>) or a dpkg-status file. If not passing a dpkg-status file, each line describes one package. Example: gcc 15.0-1 amd64 g++ 15.0-1 amd64

classmethod parse_status_file(status_file: Path) → PkgListStream

Parse a dpkg status file and returns packages with their relations.

classmethod referenced_src_packages(binpkgs: Iterable[BinaryPackage]) → Iterable[SourcePackage]

Create and return referenced source packages

class debsbom.dpkg.package.PkgListStream(stream: IO, kind: PkgListType, pkgs: Iterable[Package])

Wrapper around a packages iterator that takes care of closing the attached stream (either on StopIteration or via context manager). It further allows to return the source type of data from which the packages are created.

close()

explicitly close the stream

class debsbom.dpkg.package.PkgListType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Type of package list data (e.g. PURL or dpkg status file)

class debsbom.dpkg.package.SourcePackage(name: str, version: str | Version, maintainer: str | None = None, binaries: list[str] = [], homepage: str | None = None, vcs_browser: str | None = None, vcs_git: str | None = None, checksums: dict[ChecksumAlgo, str] | None = None)

Representation of a Debian Source package.

dscfile() → str

Return the name of the .dsc file

static from_dep822(package) → SourcePackage

Create a package from a dep822 representation. If the dep822 input is a .dsc file, the name is read from the source property.

property locator: str

Path to file if set or name of .dsc file

merge_with(other: SourcePackage)

Copy properties from other which are unset on our side. Merge lists.

purl(vendor='debian') → PackageURL

Return the PURL of the package.

APT Cache Retrieval

class debsbom.apt.cache.ExtendedStates(auto_installed: set[tuple[str, str]])

The apt extended states encode information if a package is manually installed or installed via a dependency only.

PackageFilter

alias of BinaryPackage

classmethod from_file(file: str | Path, filter_fn: Callable[[BinaryPackage], bool] | None = None) → ExtendedStates

Factory to create instance from the apt extended states file

is_manual(name: str, arch: str) → bool

True if package is explicitly installed

class debsbom.apt.cache.Repository(in_release_file: Path, origin: str | None, codename: str | None, architectures: list[str], components: list[str] | None = None, version: Version | None = None, description: str | None = None)

Represents a debian repository as cached by apt.

BinaryPackageFilter

alias of BinaryPackage

SourcePackageFilter

alias of SourcePackage

binpackages(filter_fn: Callable[[BinaryPackage], bool] | None = None, ext_states: ExtendedStates = ExtendedStates(auto_installed=set())) → Iterable[BinaryPackage]

Get all binary packages from this repository

classmethod from_apt_cache(lists_dir: str | Path) → Iterable[Repository]

Create repositories from apt lists directory.

sources(filter_fn: Callable[[SourcePackage], bool] | None = None) → Iterable[SourcePackage]

Get all source packages from this repository.

Package Downloader

class debsbom.download.download.PackageDownloader(outdir: ~pathlib._local.Path | str = 'downloads', session: ~requests.sessions.Session = <requests.sessions.Session object>)

Retrieve package artifacts from upstream. Files are only retrieved once by comparison with the data in the local downloads directory.

classmethod checksum_ok(pkg: Package, file: Path) → bool

Check if the checksum of a file matches the checksums of the package. If no checksums are provided, return true.

download(progress_cb=None) → Iterable[Path]

Download all files and yield the file paths to the on-disk object. Files that are already there are not downloaded again, but still reported.

register(files: list[RemoteFile], package: Package | None = None) → None

Register a list of files corresponding to a package for download.

stat() → statistics

Returns a tuple (files to download, total size, cached files, cached bytes)

debsbom.download.download.StatisticsType

alias of statistics

Package Resolving

class debsbom.download.resolver.PackageResolverCache

Maps packages to RemoteFile instances to avoid expensive calls to the upstream mirror. This dummy implementation can be used to not cache.

insert(p: SourcePackage | BinaryPackage, files: list[RemoteFile]) → None

Insert package files into cache

lookup(p: SourcePackage | BinaryPackage) → list[RemoteFile] | None

Lookup package files in cache

class debsbom.download.resolver.PersistentResolverCache(cachedir: Path)

Trivial implementation of a file-backed cache. Each cache entry is stored as individual file in the cachedir.

insert(p: SourcePackage | BinaryPackage, files: list[RemoteFile]) → None

Insert package files into cache

lookup(p: SourcePackage | BinaryPackage) → list[RemoteFile] | None

Lookup package files in cache

class debsbom.download.resolver.UpstreamResolver(sdl: ~debsbom.snapshot.client.SnapshotDataLake, cache: ~debsbom.download.resolver.PackageResolverCache = <debsbom.download.resolver.PackageResolverCache object>)

Helper to lookup packages on an upstream snapshot server.

resolve(p: Package) → list[RemoteFile]

Resolve a local package to references on the upstream snapshot mirror

Artifact Repacking

class debsbom.repack.packer.BomTransformer

class debsbom.repack.packer.Packer

Abstract class for Packer implementations to re-layout the downloaded artifacts

class debsbom.repack.packer.StandardBomPacker(dldir: Path | str = 'downloads', outdir: Path | str = 'standard-bom-package', compress: compression = ('cat', [], [], ''), apply_patches: bool = False)

Creates a Standard-BOM Package

Graph Exporting

class debsbom.export.exporter.GraphExporter

Base class of graph exporters

static create(filename: Path, format: GraphOutputFormat) → GraphExporter

Factory to create a GraphExporter for the given SBOM type (based on the filename extension).

abstract export(output: IO)

Export the graph. Abstract method.

static from_stream(stream: IO, bomtype: SBOMType, format: GraphOutputFormat) → GraphExporter

Factory to create a GraphExporter for the given SBOM type that takes the SBOM as stream.

class debsbom.export.exporter.GraphOutputFormat(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum of supported graph formats

class debsbom.export.graphml.GraphMLExporter

Base class for exporting a graph as GraphML. Implementations need to provide add_keys, add_packages and add_dependencies.

abstract add_dependencies(graph: Element)

Add the inter-package dependencies as edges. Abstract method.

abstract add_keys(graphml: Element)

Add the graphml keys. Abstract method.

abstract add_packages(graph: Element)

Add all packages from the sbom as nodes. Abstract method.

Debian Snapshot Client

This module contains wrappers of the snapshot.debian.org machine-usable interface documented in https://salsa.debian.org/snapshot-team/snapshot/raw/master/API.

class debsbom.snapshot.client.BinaryPackage(sdl: SnapshotDataLake, binname: str, binversion: str, srcname: str | None, srcversion: str | None)

Binary package in a specific version

files(arch: str | None = None) → Iterable[RemoteFile]

All files associated with this binary package (e.g. per-architecture)

If no architecture is specified, all packages are returned. Otherwise, only the packages with the matching architecture are returned. If we have information about the source package as well, we precisely resolve the binary package including the original path on the debian mirror. If not, we just resolve the file. The difference is only in the metadata, the file itself is the same in both cases.

Returns multiple RemoteFile instances for a single hash in case the file is known under multiple names.

exception debsbom.snapshot.client.NotFoundOnSnapshotError

The requested file is not found on the snapshot mirror

class debsbom.snapshot.client.Package(sdl: SnapshotDataLake, name: str)

Source package name (without specific version)

versions() → Iterable[SourcePackage]

Iterate all versions of a SourcePackage.

class debsbom.snapshot.client.RemoteFile(hash: str, filename: str, size: int, archive_name: str, path: str, first_seen: int, downloadurl: str, architecture: str | None = None)

File on the snapshot farm

static fromfileinfo(sdl, hash: str, fileinfo: Mapping) → RemoteFile

Factory to create a RemoteFile from a fileinfo object.

class debsbom.snapshot.client.SnapshotDataLake(url='https://snapshot.debian.org', session: ~requests.sessions.Session = <requests.sessions.Session object>)

Snapshot instance to query against. If you use this API from a tool, please use a dedicated requests session and set a custom user-agent header.

fileinfo(hash: str) → Iterable[RemoteFile]

Retrieve information about a file by hash.

packages() → Iterable[Package]

Iterate all known packages on the mirror. The request is costly. If you need to access a package by name, create the Package directly.

exception debsbom.snapshot.client.SnapshotDataLakeError

All client exceptions inherit from this

class debsbom.snapshot.client.SourcePackage(sdl: SnapshotDataLake, name: str, version: str)

Source package in a specific version

binpackages() → Iterable[BinaryPackage]

All binary packages created from this source package

srcfiles() → Iterable[RemoteFile]

All files associated with the source package. Returns multiple RemoteFile instances for a single hash in case the file is known under multiple names.