filter command

Filter SBOMs.

usage: debsbom filter [-h] [-t {cdx,spdx}] [--sources] [--binaries]
                      [--validate] [-p PACKAGE] [--exclude-regex REGEX]
                      [--exclude FILE]
                      bomin bomout

Positional Arguments

bomin

sbom file(s) to process for ‘bomin’. Use ‘-’ to read from stdin

bomout

sbom output file. Use ‘-’ to write to stdout

Named Arguments

-t, --sbom-type

Possible choices: cdx, spdx

SBOM type to process (default: auto-detect), required when reading from stdin

--sources

operate only on source packages (skip binaries)

Default: False

--binaries

operate only on binary packages (skip sources)

Default: False

--validate

validate generated SBOM (only for SPDX)

Default: False

-p, --package

filter the SBOM by only including the package and its dependency subgraph

--exclude-regex

exclude source and binary packages whose entire Debian name matches REGEX; repeatable

--exclude

exclude exact source and binary packages from universal package input

Package exclusions (CycloneDX)

Use --exclude-regex REGEX to exclude source and binary packages by their Debian package name. Each expression must match the entire name, and the option may be repeated. The same name matches all versions and architectures present in the SBOM. An invalid regular expression is an error.

For example, filter out kernel image packages before acquiring sources:

debsbom --json filter input.cdx.json filtered.cdx.json \
    --exclude-regex 'linux-image-.*' > exclusions.json
debsbom download --sources --outdir downloads filtered.cdx.json
debsbom repack --sources --dldir downloads filtered.cdx.json repacked.cdx.json

To exclude packages by exact name, Debian version and architecture, pass a file to --exclude FILE using the same universal ingress formats as From Package List: package lists, Debian PURLs, Isar manifests, or dpkg status files. Both source and binary entries are selected, including source entries inferred from manifests or status files. Versions and architectures must be specified explicitly; use source to select a source package. A binary selector does not match other versions or architectures of the same package.

For example, a package list marks sources with the source architecture:

linux 6.12.73-1 source
example-binary 2:1.0-1 amd64

The equivalent PURL input is:

pkg:deb/debian/linux@6.12.73-1?arch=source
pkg:deb/debian/example-binary@2:1.0-1?arch=amd64

The file and regular-expression options may be combined.

A matching source package is excluded without removing binaries built from it. Dependencies of excluded packages are removed only when no retained package references them.

The global --json option writes the exclusion report to standard output. Use an SBOM output file when requesting a report so that the two JSON documents do not share standard output. Unmatched exclusions do not fail the command. The report follows this schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/siemens/debsbom/refs/heads/main/src/debsbom/schema/schema-filter-report.json",
  "title": "Exclusion Report",
  "description": "The result of excluding packages from an SBOM.",
  "type": "object",
  "$defs": {
    "package": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the package."
        },
        "version": {
          "type": "string",
          "description": "The version of the package."
        },
        "arch": {
          "type": "string",
          "description": "The binary architecture, or source for a source package."
        }
      },
      "required": [
        "name",
        "version",
        "arch"
      ]
    },
    "refs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "properties": {
    "matched_patterns": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Exclusion patterns that matched at least one package."
    },
    "unmatched_patterns": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Exclusion patterns that did not match any package."
    },
    "matched_packages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/package"
      },
      "description": "Exact package exclusions that matched a package."
    },
    "unmatched_packages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/package"
      },
      "description": "Exact package exclusions that did not match any package."
    },
    "removed_binaries": {
      "$ref": "#/$defs/refs",
      "description": "References of the removed binary packages."
    },
    "removed_sources": {
      "$ref": "#/$defs/refs",
      "description": "References of the removed packages."
    }
  },
  "required": [
    "matched_patterns",
    "unmatched_patterns",
    "matched_packages",
    "unmatched_packages",
    "removed_binaries",
    "removed_sources"
  ]
}

Exclusions can be combined with --sources or --binaries; the exclusions are applied first. They cannot be combined with --package, which selects a dependency subgraph. SPDX exclusions are not supported.