# `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"
            },
            "nodsa": {
              "type": [
                "string"
              ],
              "description": "Reason why no DSA is issued"
            }
          },
          "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
    }