# 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(*values)

  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, dependency_refs: dict[str, Package], native_arch: 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(*values)

  Supported SBOM types

  CycloneDX = (0,)

    CycloneDX

  SPDX = (1,)

    SPDX

  validate_dependency_availability() → None

    Check if the required imports for the SBOM type are available. Raises RuntimeError if not available.

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] | None = None, pre_depends: list[Dependency] | None = None, provides: list[VirtualPackage] | None = None, recommends: list[Dependency] | None = None, suggests: list[Dependency] | None = None, built_using: list[Dependency] | None = None, static_built_using: list[Dependency] | None = None, description: str | None = None, essential: bool = False, priority: DebianPriority | None = None, homepage: str | None = None, checksums: dict[ChecksumAlgo, str] | None = None, manually_installed: bool = True, status: DpkgStatus = DpkgStatus.DEBSBOM_UNKNOWN)

  Incomplete representation of a Debian binary package.

  property all_depends: Iterable[Dependency]

    Returns an iterator containing both “Depends” and “Pre-Depends.

  classmethod from_deb822(package) → BinaryPackage

    Create a `BinaryPackage` from a deb822 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.

  satisfies(dependency: Dependency) → bool

    Returns True if the binary package satisfies the dependency.

  source_package() → SourcePackage | None

    Construct a source package from the referenced source dependency.

  property unique_depends: list[Dependency]

    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.

  property unique_recommends: list[Dependency]

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

  property unique_suggests: list[Dependency]

    Returns the unique suggestions 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.DebianPriority(*values)

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.

  is_satisfying_version(other: Version) → bool

    Returns True if the passed version satisfies the dependencies version constraint.

class debsbom.dpkg.package.DpkgStatus(*values)

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

  is_binary() → bool

    Helper to check if the package is a binary package

  is_source() → bool

    Helper to check if the package is a source package

  merge_with(other: Package)

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

  classmethod parse_pkglist_stream(stream: IOBase) → 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: IOBase, 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(*values)

  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] | None = None, homepage: str | None = None, vcs: VcsInfo | None = None, checksums: dict[ChecksumAlgo, str] | None = None, copyright: Copyright | None = None)

  Representation of a Debian Source package. The checksums refer to the .dsc file.

  dscfile() → str

    Return the name of the .dsc file

  static from_deb822(package) → SourcePackage

    Create a package from a deb822 representation. If the deb822 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.

class debsbom.dpkg.package.VcsInfo(type: VcsType, locator: str)

  Internal representation of the Vcs-<type> information for a source package.

class debsbom.dpkg.package.VcsType(*values)

class debsbom.dpkg.package.VirtualPackage(name: str, version: Version | None = None)

  Virtual Package, as declared in the Provides field.

  classmethod best_match(candidates: list[tuple[VirtualPackage, BinaryPackage]], dependency: Dependency) → type[BinaryPackage] | None

    Return the best matching virtual package that satisifes the dependency.

  satisfies(dep: Dependency) → bool

    Returns True if this virtual package satisfies the dependency.

debsbom.dpkg.package.filter_binaries(pkgs: Iterable[Package]) → Iterable[BinaryPackage]

  Free function to only return binary packages

debsbom.dpkg.package.filter_installed(pkgs: Iterable[BinaryPackage]) → Iterable[BinaryPackage]

  Free function to only return installed binary packages.

debsbom.dpkg.package.filter_sources(pkgs: Iterable[Package]) → Iterable[SourcePackage]

  Free function to only return source packages

## BOM Processing

class debsbom.bomreader.bomreader.BomReader

  Base class for SBOM importers

  classmethod create(filename: Path, bomtype: SBOMType | None = None)

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

  classmethod from_json(json_obj, bomtype: SBOMType)

    Factory to create a processor for the given sbom json object.

  classmethod from_stream(stream: IOBase, bomtype: SBOMType)

    Factory to create a processor for the given stream.

class debsbom.resolver.resolver.PackageResolver

  Creates internal package representations of an arbitrary package input. The packages are iteratively resolved. Iterable class.

  classmethod create(filename: Path, bomtype: SBOMType | None = None) → PackageResolver

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

  classmethod from_json(json_obj, bomtype: SBOMType) → PackageResolver

    Factory to create a PackageResolver for the given SBOM type from a json object.

  classmethod from_stream(stream: IOBase, bomtype: SBOMType) → PackageResolver

    Factory to create a PackageResolver for the given SBOM type that parses a stream.

  abstractmethod root_component_name() → str | None

    Return the name of the root component.

class debsbom.resolver.resolver.PackageStreamResolver(pkgstream: IOBase)

  Handles universal package ingress. Emits (partial) package instances, depending on input. Iterable class.

## APT Cache Retrieval

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

  The apt extended states encode information if a package is manually installed or installed via a dependency only. Note, that the PackageFilter maps arch=all binary packages to the architecture they are installed for (usually that’s the distro arch).

  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. Architecture unspecific packages are mapped to the arch of the package that had it as a dependency. As we don’t know that when parsing, we simply scan in all architectures.

class debsbom.apt.cache.Repository(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(), distro_archs=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.

class debsbom.apt.copyright.Copyright(path: Path)

  Copyright information for a source package.

  licenses() → Iterable[License]

    Return all licenses found in the copyright file.

class debsbom.apt.copyright.CopyrightDirectory(path: Path)

  Directory of Debian copyright information.

  copyright(bin_pkg) → Copyright

    Get the copyright information for a binary package.

exception debsbom.apt.copyright.UnknownLicenseError

  License is unknown to the SPDX standard.

## Package Downloader

class debsbom.download.download.DownloadResult(path: pathlib.Path | None, status: debsbom.download.download.DownloadStatus, package: debsbom.dpkg.package.Package, filename: str | None)

class debsbom.download.download.DownloadStatus(*values)

class debsbom.download.download.PackageDownloader(outdir: Path | str = 'downloads', session: 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.

  download(progress_cb=None) → Iterable[DownloadResult]

    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

    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`

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.RemoteFile(checksums: dict[debsbom.util.checksum.ChecksumAlgo, str], filename: str, archive_name: str, downloadurl: str, size: int | None = None)
  archive_name: str

    Debian archive name where the associated package comes from. If unsure use “debian”.

  as_base() → RemoteFile

    Upcast to the RemoteFile base, dropping all additional fields.

  checksums: dict[ChecksumAlgo, str]

    Available checksums for the remote file.

  downloadurl: str

    Full URL to where the file can be downloaded.

  filename: str

    Is used to determine the filename of the downloaded file.

  size: int | None = None

    Size of the file, if available.

exception debsbom.download.resolver.ResolveError

  Exception for any expected error during resolving.

class debsbom.download.resolver.Resolver(cache: PackageResolverCache | None = None)

  Base class for resolvers.

  resolve(p: Package) → list[RemoteFile]

    Resolve a package to a list of remote files to download.

## 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

exception debsbom.repack.merger.ChangelogTimestampError

  Raised when mtime cannot be extracted from the changelog for reproducible builds.

exception debsbom.repack.merger.CorruptedFileError

exception debsbom.repack.merger.DscFileNotFoundError

class debsbom.repack.merger.SourceArchiveMerger(dldir: Path, outdir: Path | None = None, compress: compression = ('cat', [], [], ''))

  Creates a new archive containing the files from the source and the debian archive of a package.

  classmethod locate_artifact(p: Package, basedir: Path) → Path | None

    Locate a related .deb or .dsc file in the downloads dir.

  merge(p: SourcePackage, apply_patches: bool = False, mtime: datetime | None = None) → Path

    The provided package will also be updated with information from the .dsc file.

## Graph Exporting

class debsbom.export.exporter.GraphExporter

  Base class of graph exporters

  classmethod create(filename: Path, bomtype: SBOMType | None = None, format: GraphOutputFormat = GraphOutputFormat.GRAPHML) → GraphExporter

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

  abstractmethod export(output: IOBase)

    Export the graph. Abstract method.

  classmethod from_json(json_obj: IOBase, bomtype: SBOMType, format: GraphOutputFormat) → GraphExporter

    Factory to create a GraphExporter for the given SBOM type that takes a json object.

  classmethod from_stream(stream: IOBase, 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(*values)

  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.

  abstractmethod add_dependencies(graph: Element)

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

  abstractmethod add_keys(graphml: Element)

    Add the graphml keys. Abstract method.

  abstractmethod add_packages(graph: Element)

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

## Dependency Trace Paths

class debsbom.tracepath.walker.GraphWalker

  Base class of graph walkers

  abstractmethod all_shortest(source: PackageURL) → Iterable[list[PackageRepr]]

    Return all shortest path from source to root. Abstract method.

  abstractmethod all_simple(source: PackageURL) → Iterable[list[PackageRepr]]

    Return all non-cyclic path from source to root. Abstract method.

  classmethod create(filename: Path, bomtype: SBOMType | None = None) → GraphWalker

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

  classmethod from_document(document, sbom_type: SBOMType) → GraphWalker

    Factory to create a GraphWalker from an SBOM document instance.

  classmethod from_json(json_obj: IOBase, bomtype: SBOMType) → GraphWalker

    Factory to create a GraphWalker for the given SBOM type that takes a json object.

  classmethod from_stream(stream: IOBase, bomtype: SBOMType) → GraphWalker

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

  abstractmethod shortest(source: PackageURL) → list[PackageRepr]

    Return shortest path from source to root. Abstract method.

exception debsbom.tracepath.walker.NoRootNodeError

class debsbom.tracepath.walker.PackageRepr(name: str, ref: str, version: str | None = None, maintainer: str | None = None, purl: str | None = None)

  Simple package representation that covers meta, source and binary packages.

## Security Scanning

class debsbom.securityscan.scanner.CveEntry(cve: str, debianbug: int | None, description: str | None, status: debsbom.securityscan.scanner.CveStatus, fixed_version: str | None, urgency: debsbom.securityscan.scanner.CveUrgency, nodsa: str | None)

class debsbom.securityscan.scanner.CveStatus(*values)

class debsbom.securityscan.scanner.CveUrgency(*values)

class debsbom.securityscan.scanner.ScanResultItem(package: debsbom.dpkg.package.SourcePackage, vulnerability: debsbom.securityscan.scanner.CveEntry, affected: bool)

class debsbom.securityscan.scanner.SecurityScanner(db: Path, distro: str = 'trixie')

  A security scanner that checks source packages against a Debian security database for known vulnerabilities.

class debsbom.securityscan.writer.ScanResultJsonWriter(graph_walker: GraphWalker | None = None, **args)

class debsbom.securityscan.writer.ScanResultSarifWriter(path: Path, **args)

class debsbom.securityscan.writer.ScanResultTextWriter(packages: list[~debsbom.dpkg.package.Package], sdo_url: str, bdo_url: str, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

class debsbom.securityscan.writer.ScanResultVexWriter(author, product, **args)

class debsbom.securityscan.writer.ScanResultWriter(packages: list[~debsbom.dpkg.package.Package], sdo_url: str, bdo_url: str, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

  Emit the security scan results in the specified format. All instances should be used with a context manager.

  affected_binaries(src_pkg: SourcePackage) → list[BinaryPackage]

    Return binary packages built from or built-using the given source package.

## 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[SnapshotRemoteFile]

    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 SnapshotRemoteFile 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.SnapshotDataLake(url='https://snapshot.debian.org', session: 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[SnapshotRemoteFile]

    Retrieve information about a file by hash.

  get(path: str = None, url: str = None) → Response

    Perform a GET request on the snapshot server. Either a full URL or a path relative to the base URL must be provided.

  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.SnapshotRemoteDscFile(sdl: SnapshotDataLake, dscfile: SnapshotRemoteFile, allfiles: list[SnapshotRemoteFile])

  Wrapper around a RemoteFile to only iterate the files referenced in the dsc file.

  srcfiles() → Iterable[SnapshotRemoteFile]

    Yields RemoteFile objects from self.allfiles that match checksums defined in self._dsc.

class debsbom.snapshot.client.SnapshotRemoteFile(checksums: dict[ChecksumAlgo, str], filename: str, archive_name: str, downloadurl: str, *, size: int = None, path: str, first_seen: int, architecture: str | None = None)

  File on the snapshot farm.

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

    Factory to create a `SnapshotRemoteFile` from a fileinfo object.

exception debsbom.snapshot.client.SnapshotResolveError

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(archive: str | None = None, sha1: str | None = None) → Iterable[SnapshotRemoteFile]

    All files associated with the source package. Returns multiple SnaphshotRemoteFile instances for a single hash in case the file is known under multiple names. If the package is not known to the snapshot mirror, raises NotFoundOnSnapshotError. If the filtering does not match any, return empty iterator.

class debsbom.snapshot.client.UpstreamResolver(sdl: SnapshotDataLake, cache: PackageResolverCache | None = None)

  Helper to lookup packages on an upstream snapshot server. The lookup works as following:

  Binary package: ask the snapshot client for files of a binary package with name, version and architecture

  Source package (with checksum): ask the snapshot client for all files related to the source package identified by name and version. Then, sort the list by to sorting order and filter all .dsc files in the returned list. For each dsc file, fetch it and compute the checksum. If the checksum is not matching, ignore it. If it is matching, yield it and yield all referenced source files of the .dsc file.

  Source package (without checksum): ask the snapshot client for all files related to the source package identified by name and version. Then, sort the list by to sorting order and deduplicate based on (archive_name, filename). Note, that each deduplication contains the most recent file.

  Sorting order: First by archive_name (priority), then by first_seen (descending).

  Checksum computation: The checksums of the returned files are not checked at this stage (except for the .dsc files for source packages with checksum information). This operation is left to the caller (usually the downloader), as it creates potentially a lot of traffic between the snapshot mirror and the downloader. The resolving operations itself are cached in the cache, but the download artifacts have to be cached by the caller.

  resolve(p: Package) → list[RemoteFile]

    Resolve a local package to references on the upstream snapshot mirror