CLI reference

Find the CUDA your SBOM missed: evidence-backed CUDA identity and security-grade SBOM/VEX for artifacts.

Usage: cudabom [OPTIONS] <COMMAND>

Commands:
  scan       Scan one or more targets for CUDA components
  gate       Scan targets and evaluate a policy, failing the build on violations
  enrich     Enrich an existing CycloneDX SBOM with discovered CUDA components
  vex        Emit CycloneDX VEX for a target
  reconcile  Reconcile a declared CycloneDX SBOM/VEX (e.g. from NGC) against the CUDA components cudabom discovers in a target
  explain    Explain why a finding was identified
  db         Manage the local advisory database
  update     Fetch the published data bundle (fingerprint DB + advisory index) into the local data directory that scans read by default
  schema     Print the JSON Schema of cudabom's native output
  version    Print version information for the tool and its data
  help       Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`
  -q, --quiet       Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output
  -h, --help        Print help
  -V, --version     Print version

Scan one or more targets for CUDA components

Usage: cudabom scan [OPTIONS] <TARGET>...

Arguments:
  <TARGET>...
          One or more targets to scan (files or directories)

Options:
      --format <FORMAT>
          Output format
          
          [default: table]
          [possible values: table, json, cyclonedx, sarif, markdown]

  -o, --output <FILE>
          Write output to a file instead of stdout

      --db <FILE>
          Path to a fingerprint database (JSON) used for identification. When omitted, an empty database is used, so only structural signals produce findings

      --advisories <FILE>
          Path to a local advisory index (JSON) used to correlate findings against known NVIDIA security advisories. When omitted, no advisory correlation is performed. Absence of a match is never treated as proof of safety

      --fail-on <FAIL_ON>
          When to return a non-zero exit code. `scan` is a reporting command and defaults to `none` (exit 0 on success) so identifying CUDA does not fail a build; use `found` or `affected` to opt into CI failure, or `gate` for full policy enforcement

          Possible values:
          - none:     Never fail on results (always exit 0 on success). The default
          - found:    Fail when any CUDA component is identified (regardless of advisories)
          - affected: Fail only when an identified component is `affected` by an advisory
          
          [default: none]

      --all-files
          List every file walked in the `table` output, including the uninteresting ones (source headers, package metadata). By default the table shows only files that carry a signal (ELF, GPU code, archives, parse errors) and collapses the rest into a one-line summary. Only affects `--format table`

  -v, --verbose...
          Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`

  -q, --quiet
          Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Scan targets and evaluate a policy, failing the build on violations

Usage: cudabom gate [OPTIONS] <TARGET>...

Arguments:
  <TARGET>...  One or more targets to scan (files or directories)

Options:
      --policy <FILE>      Path to a policy file (JSON). When omitted, the built-in secure default is used: fail on any `affected` advisory verdict
      --db <FILE>          Path to a fingerprint database (JSON) used for identification
      --advisories <FILE>  Path to a local advisory index (JSON) used to correlate findings
      --format <FORMAT>    Output format for the gate decision [default: table] [possible values: table, json]
  -v, --verbose...         Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`
  -q, --quiet              Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output
  -h, --help               Print help
  -V, --version            Print version

Enrich an existing CycloneDX SBOM with discovered CUDA components

Usage: cudabom enrich [OPTIONS] --sbom <FILE> <TARGET>...

Arguments:
  <TARGET>...  One or more targets to scan for CUDA components to add

Options:
      --sbom <FILE>    The existing CycloneDX SBOM (JSON) to enrich
      --db <FILE>      Path to a fingerprint database (JSON) used for identification
  -o, --output <FILE>  Write the enriched SBOM to a file instead of stdout
  -v, --verbose...     Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`
  -q, --quiet          Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output
  -h, --help           Print help
  -V, --version        Print version

Emit CycloneDX VEX for a target

Usage: cudabom vex [OPTIONS] <TARGET>...

Arguments:
  <TARGET>...  One or more targets to scan (files or directories)

Options:
      --db <FILE>          Path to a fingerprint database (JSON) used for identification
      --advisories <FILE>  Path to a local advisory index (JSON). VEX statements come from the resulting advisory verdicts; without it, the VEX document has an SBOM but no vulnerability statements
  -o, --output <FILE>      Write output to a file instead of stdout
  -v, --verbose...         Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`
  -q, --quiet              Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output
  -h, --help               Print help
  -V, --version            Print version

Reconcile a declared CycloneDX SBOM/VEX (e.g. from NGC) against the CUDA components cudabom discovers in a target

Usage: cudabom reconcile [OPTIONS] <TARGET>...

Arguments:
  <TARGET>...  One or more targets to scan (files or directories)

Options:
      --sbom <FILE>               A declared CycloneDX SBOM (JSON) to reconcile against, e.g. the SBOM NGC publishes for an image. May be combined with `--vex`
      --vex <FILE>                A declared CycloneDX VEX (JSON) to reconcile against, e.g. the VEX NGC publishes for an image. VEX statements are attached to matched components
      --ngc-image <ORG/REPO:TAG>  Fetch the declared SBOM and VEX from NVIDIA NGC for this image, given as `org/repository:tag` (e.g. `nvidia/pytorch:26.01-py3`). Requires an NGC API key in `--ngc-api-key` or the `NGC_API_KEY` environment variable. This is the only networked path; `--sbom`/`--vex` files stay offline
      --ngc-api-key <KEY>         NGC API key for `--ngc-image`. Falls back to the `NGC_API_KEY` environment variable, which is preferred so the key stays out of shell history and process listings
      --db <FILE>                 Path to a fingerprint database (JSON) used for identification
      --format <FORMAT>           Output format [default: table] [possible values: table, json, cyclonedx, sarif, markdown]
  -o, --output <FILE>             Write output to a file instead of stdout
  -v, --verbose...                Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`
  -q, --quiet                     Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output
  -h, --help                      Print help
  -V, --version                   Print version

Explain why a finding was identified

Usage: cudabom explain [OPTIONS] <TARGET>...

Arguments:
  <TARGET>...  One or more targets to scan (files or directories)

Options:
      --id <FINDING_ID>  The finding id to explain. When omitted, all findings are listed with their ids so one can be chosen
      --db <FILE>        Path to a fingerprint database (JSON) used for identification
      --format <FORMAT>  Output format [default: text] [possible values: text, json]
  -v, --verbose...       Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`
  -q, --quiet            Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output
  -h, --help             Print help
  -V, --version          Print version

Manage the local advisory database

Usage: cudabom db [OPTIONS] <COMMAND>

Commands:
  build   Build a normalized advisory index from local CSAF documents
  status  Report mapped and unmapped products from local CSAF documents
  update  Fetch CSAF from upstream over the network and rebuild the index
  help    Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`
  -q, --quiet       Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output
  -h, --help        Print help
  -V, --version     Print version

Fetch the published data bundle (fingerprint DB + advisory index) into the local data directory that scans read by default

Usage: cudabom update [OPTIONS]

Options:
      --tag <TAG>           Release tag to install (e.g. `v1.2.3`). When omitted, the latest release is resolved and installed
      --data-dir <DIR>      Install into this directory instead of the resolved per-user data directory (`$CUDABOM_DATA_DIR`, `$SNAP_USER_DATA/cudabom`, `$XDG_DATA_HOME/cudabom`, or `~/.local/share/cudabom`)
      --owner <OWNER>       Repository owner the bundle is published from (defaults to the cudabom project)
      --repo <REPO>         Repository name (defaults to the cudabom project)
      --api-url <URL>       Override the GitHub REST API base (release lookup), e.g. a mirror
      --download-url <URL>  Override the release-asset download base URL
      --max-retries <N>     Maximum download attempts per request (including the first). Default 5
      --retry-base-ms <MS>  Base backoff in milliseconds for the first retry. Default 500
      --no-retry            Disable retries entirely (single attempt per request)
  -v, --verbose...          Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`
  -q, --quiet               Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output
  -h, --help                Print help
  -V, --version             Print version

Print the JSON Schema of cudabom's native output

Usage: cudabom schema [OPTIONS]

Options:
  -v, --verbose...  Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`
  -q, --quiet       Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output
  -h, --help        Print help
  -V, --version     Print version

Print version information for the tool and its data

Usage: cudabom version [OPTIONS]

Options:
  -v, --verbose...  Increase diagnostic detail on stderr. Repeat for more (`-vv`). This is the single knob for verbosity across every subcommand; it never changes the machine-readable output written to stdout or `--output`
  -q, --quiet       Suppress non-essential diagnostics on stderr, leaving only errors. Like `--verbose`, this is global and does not affect stdout output
  -h, --help        Print help
  -V, --version     Print version