sec-scan command

The command reads an SBOM and checks all referenced source packages for vulnerability based on the Debian security tracker data. The output can be written in various formats, including OpenVEX and SARIF.

Note

This command can be executed in an air-gapped environment if the db is already downloaded.

Scans packages from an SBOM for security vulnerabilities.

usage: debsbom sec-scan [-h] [-t {cdx,spdx}] [--author AUTHOR]
                        [--default-product {component,distribution}]
                        [--product PRODUCT] [--db DB] [--distro DISTRO]
                        [--update-db] [--filter FILTER]
                        [-f {text,json,sarif,vex}]
                        [--min-urgency {high,medium,low,unimportant,end-of-life,not-yet-assigned}]
                        [--tracker TRACKER] [--with-paths-to-root]
                        [bomin]

Positional Arguments

bomin

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

Named Arguments

-t, --sbom-type

Possible choices: cdx, spdx

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

--author

author of the document (-f vex only)

--default-product

Possible choices: component, distribution

controls whether the component or distribution is used as the product in VEX statements (-f vex only, default: ‘component’)

Default: 'component'

--product

product to use in VEX statements, overwrites the behavior of –default-product (-f vex only)

--db

path to Debian security tracker JSON database (default: ~/.cache/debsbom/security-tracker.json)

Default: ~/.cache/debsbom/security-tracker.json

--distro

Debian distribution to check (default: ‘trixie’)

Default: 'trixie'

--update-db

download the security tracker database (from –tracker) and store it at the path specified by –db

Default: False

--filter

limit search to a specific package name

-f, --format

Possible choices: text, json, sarif, vex

output format (default: ‘text’)

Default: 'text'

--min-urgency

Possible choices: high, medium, low, unimportant, end-of-life, not-yet-assigned

filter CVEs by urgency (default: ‘not-yet-assigned’)

Default: 'not-yet-assigned'

--tracker

URL of upstream debian security tracker (default: ‘https://security-tracker.debian.org/tracker’)

Default: 'https://security-tracker.debian.org/tracker'

--with-paths-to-root

emit path from component to root per affected package (-f json only)

Default: False

JSON Output Schema

When the application is run with JSON output enabled (via the --json flag), status messages are emitted as single-line JSON objects to standard output. Each line represents a distinct scan result (e.g. vulnerability affecting a package).

The schema for these JSON objects is as follows:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/siemens/debsbom/refs/heads/main/src/debsbom/schema/schema-sec-scan.json",
  "title": "Security Scan Result",
  "definitions": {
    "vulnerability": {
      "type": "object",
      "required": [
        "id",
        "status",
        "urgency",
        "tracker"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Vulnerability identifier (CVE or temporary ID)"
        },
        "status": {
          "type": "string",
          "enum": [
            "resolved",
            "undetermined",
            "open"
          ],
          "description": "Current vulnerability status"
        },
        "urgency": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low",
            "unimportant",
            "end-of-life",
            "not-yet-assigned"
          ],
          "description": "Urgency level"
        },
        "fixed-in": {
          "type": [
            "string"
          ],
          "description": "Version in which the vulnerability is fixed"
        },
        "desc": {
          "type": [
            "string"
          ],
          "description": "Vulnerability description"
        },
        "tracker": {
          "type": [
            "string"
          ],
          "format": "uri",
          "description": "URL to the vulnerability tracker entry"
        },
        "debianbug": {
          "type": "integer",
          "description": "Debian bug id"
        },
        "bugreport": {
          "type": [
            "string"
          ],
          "format": "uri",
          "description": "URL to the debian bug tracker entry"
        }
      },
      "additionalProperties": false
    },
    "pathsToRoot": {
      "type": "object",
      "properties": {
        "allShortest": {
          "type": "array",
          "items": {
            "$ref": "schema-trace-path.json"
          }
        }
      }
    }
  },
  "type": "object",
  "required": [
    "package",
    "purl",
    "vulnerability"
  ],
  "properties": {
    "package": {
      "type": "string",
      "description": "Package name and version"
    },
    "purl": {
      "type": "string",
      "description": "Package URL (PURL) identifier"
    },
    "vulnerability": {
      "$ref": "#/definitions/vulnerability"
    },
    "pathsToRoot": {
      "$ref": "#/definitions/pathsToRoot"
    }
  },
  "additionalProperties": false
}