Usage

The cvescan program

The cvescan program is invoked in the following way :

Usage: cvescan [OPTIONS] COMMAND [ARGS]...

  Lists all known security vulnerabilities for a given build.

Options:
  -h, --help     Show this message and exit.
  -d, --debug    Enables debug information.
  -v, --version  Prints software version.
  --config PATH  Override default configuration file.

Commands:
  datasources-update  Updates vulnerability sources.
  export-report       Transforms JSON reports to other exploitable formats.
  filter-report       Filters out reports false positives.
  run                 Scans, filters and exports.
  scan-inventory      Scans SBOM to list all applicable CVEs.
  serve-ui            Launches a local server for the CVE Scan Web Interface.
  version             Prints software version.

cvescan proposes several commands that serve various purposes:

datasources-update to update the Linux upstream, Ubuntu CVE Tracker and CVE database local cache,
scan-inventory to extract vulnerabilities for a given inventory from the CVE database and output the results in a vulnerability report,
filter-report to automatically detect and flag false positives from an existing vulnerability report,
export-report to convert a vulnerability report to a useable file format,
run to chain the scan-inventory, filter-report and export-report commands in one run.
serve-ui to launch the CVE Scan Web interface.

The datasources-update command

Usage: cvescan datasources-update [OPTIONS] [KEYS]...

  Updates vulnerability sources.

Options:
  -h, --help                   Show this message and exit.
  --timeout TEXT               Optional timeout, either an integer interpreted
                               as seconds or in a time expression format e.g.
                               "45m30s" or "1h".
  --snapshot SNAPSHOT          Creates a snapshot of the current vulnerability
                               sources.
  --restore-snapshot SNAPSHOT  Restores the vulnerability sources from the
                               given snapshot.

This command is used to update [[sources]].

TIMEOUT Optional:

A length of time (in seconds) after which the update operation will be cancelled, and can be used to ensure that this will not block indefinitely subsequent operations (e.g. when it is run in a pipeline).

SNAPSHOT Optional:

The snapshot archive to create or restore local source mirrors to.

The scan-inventory command

Usage: cvescan scan-inventory [OPTIONS]

  Scans SBOM to list all applicable CVEs.

Options:
  -h, --help                      Show this message and exit.
  --uct-dir UCT_DIR               Ubuntu CVE tracker directory path.
  --keep-package KEPT_PACKAGES    Scan package even if not on the image
  --inventory-format INV_FORMAT   Inventory file format.
  --inventory INVENTORY           Path to the inventory file or root directory
                                  (spdx specific).
  -o, --output OUTPUT             Output report path.
                                  manifest.
  --scope.transversal TRANSVERSAL Annotations scope 'transversal' attribute
  --scope.project PROJECT         Annotations scope 'project' attribute
  --scope.component COMPONENT     Annotations scope 'component' attribute

Using this command cvescan matches package name and version against NVD CVE entries.

UCT_DIR Optional:

The directory holding the UCT mirror (as described in Data sources); Using the UCT as a vulnerability source introduces a lot of false positives. Reserve for paranoid usage.

KEPT_PACKAGES Optional:

is a list of packages that are not on the root filesystem image (e.g. linux_kernel), but should be included in the analysis;

INV_FORMAT Optional, Default: cvescan:

One of {cvescan, cyclonedx-json , spdx-json}, as specified in Inventories;

INVENTORY Required:

A file (or directory when aggregating SPDX JSON files)holding the inventory in the specified format;

OUTPUT Optional, Inferred from INVENTORY:

The filename (or path) of the JSON report to be produced. When this option is not set, CVE Scan will use a basename + timestamp for the reports it generates, which is either inferred from the inventory filename, or set in the configuraiton file. In this case a symbolic link named after the basename will be produced, linking to the latest version of the report.

TRANSVERSAL, PROJECT and COMPONENT Optional:

Allow to set some scope specifiers for the generated report (see Scopes for details).

Note

The inventory may contain information about packages that participate in the build process but do not make it to the image Examples include the cross toolchain but also interpreters (perl, python etc.). Any package that does not have at least one associated runtime package is discarded. To include packages that are not on the root filesystem image use the --keep-package option.

The filter-report command

Usage: cvescan filter-report [OPTIONS]

  Filters out reports false positives.

Options:
  -h, --help                      Show this message and exit.
  --inventory-format INV_FORMAT   Inventory file format.
  --inventory INVENTORY           Path to the inventory file or root directory
  --uct-dir UCT_DIR               Ubuntu CVE tracker directory path.
                                  (spdx specific).
  -i, --input INPUT               Input report path.
  -o, --output OUTPUT             Output report path.
  --upstream-uri UPSTREAM_URI     Mainline Linux kernel repository (may be a
                                  path to a local copy)
  --annotations ANNOTATIONS       Manual annotations file path (deprecated)
  --filter-cache FILTER_CACHE     Filter cache directory path.
  --lkconfig LKCONFIG_PATH        Path to the linux kernel options filters
                                  configuration file.
  --git-dir GIT_DIR               Yocto git download directory (typically
                                  $DL_DIR/git2).
  --use-upstream-linux-ref REF    Overrides the git reference from the Yocto
                                  SBOM with the Linux kernel repo mirror
                                  specified from --upstream-uri with a commit
                                  reference <branch|tag|hash>

In this step cvescan uses information from various source to check which CVEs are applicable.

UPSTREAM_URI Required:

The location of the local Linux kernel mirror (see Data sources for details);

ANNOTATIONS Optional:

A file holding manual annotations; This option is deprecated, and kept here for backward compatibility only; annotations files now should be specified with the export-report command

FILTER_CACHE Optional:

A folder to store a filter cache that will be populated on the first filtering command, allowing to massively speed up further filterings;

LKCONFIG_PATH Optional:

The path to the lkconfig.yml file (when not specified CVE Scan will use the lkconfig.yml file in the current directory if present, otherwise it will use its internal one);

GIT_DIR Optional:

The location on the filesystem of the $DL_DIR/git2 Yocto directory which holds the local mirrors for the git repositories that are used during the Yocto build; if not provided, CVE Scan will try to resolve from the Linux kernel URI.

REF Optional:

Points to commit reference (either a hash, tag or branch name) in the repository pointed by UPSTREAM_URI, allowing to approximate the state of the kernel used for building when the GIT_DIR is not specified (typically when one has no access to the Yocto build dir). This option must be used with caution, since it breaks the link with the built kernel, and filter-report could as a consequence rule out vulnerable CVEs.

INPUT Optional, Inferred as {basename}-scan-inventory.report.json:

The JSON report produced by a former invocation of cvescan scan-inventory.

OUTPUT Optional, Inferred as {basename}-filter-report.report.json:

The name of the new, filtered report to be produced.

This filtering step make use of various informations in order to automatically rule out some vulnerabilities.

LKConfig file

It makes use of file named lkconfig.yml which is stored in CVEScan installation. It is possible to set your own lkconfig.yml file by copying it from the root of the CVE Scan repository in the current directory (or in a custom location using the --lkconfig option), and then modifying yourself. It's a YAML file with the following format:

LKCONFIG-FILE   ::= (RULE)*
RULE            ::= VULNERABILITY-NAME: (CONFIGS) | (RATIONALE)
VULNERABILITY-NAME  ::= string
CONFIGS             ::= configs: (SINGLE-CONFIG) | (LIST-OF-CONFIGS)
LIST-OF-CONFIGS     ::=  - SINGLE-CONFIG
                        (- SINGLE-CONFIG)*
SINGLE-CONFIG       ::= string
RATIONALE           ::= rationale: COMMENT
COMMENT             ::= string

(A)* meaning zero or more occurrences of A, (A) | (B) meaning A or B, and where :

VULNERABILITY-NAME is the unique identifier for a vulnerability (e.g. CVE-2020-35501)
SINGLE-CONFIG is a kernel compilation option (e.g. KVM, OVERLAY_FS, IPV6)
COMMENT is a justification string.

These rules allow to provide global filters for the cvescan filter-report command based either on a specific kernel configuration, or in general.

First some packages may have been whitelisted at Yocto recipe level (CVE_CHECK_WHITELIST/CVE_CHECK_IGNORE). Also some CVEs may be fixed by patches referenced by yocto recipes.

Special attention is dedicated to the linux kernel. When a fix is available for a specific CVE, the commit ID of this fix can often be found in the NVD or the UCT. CVE scan examines the git history of the kernel source code for such fix commit IDs and marks the corresponding report entries as patched. CVE Scan also checks the working branch of the kernel for backports (i.e. cherry-picks) fix commits from mainline.

If, for a given CVE, a fix is available, but not applied, cvescan checks whether the vulnerable code was included in the build. If not, the CVE is whitelisted.

The export-report command

Usage: cvescan export-report [OPTIONS]

  Transforms JSON reports to other exploitable formats.

Options:
  -h, --help                      Show this message and exit.
  --format [text|junit|cyclonedx-json|csv|yaml]
                                  Output report format.
  --filter-score-type [Any|CVSSv2|CVSSv3]
                                  Specifies which score field to compare to
                                  the value of --keep-scores-above.  [default:
                                  Any]
  --keep-scores-above DECIMAL     Export only CVE with a score higher than or
                                  equal to argument, see also --filter-score-
                                  type.
  --match-attack-vector TEXT      Export only CVE with an attack/access vector
                                  matching argument.
  -i, --input NAMEDREPORT         Input report path and optionnally custom
                                  name, passed as path_to_report:name. Report
                                  name is only taken into account when more
                                  than one report is passed.  [required]
  -o, --output PATH               Output report path.
  --annotations PATH              Manual annotations file path.
  --uct-dir PATH                  Ubuntu CVE tracker directory path.
  --vulnerable-only               Exclude non-vulnerable CVEs from output.
  --override-vulnerable-manual-assessment BOOLEAN
                                  Do not apply vulnerable manual assessment
                                  from annotations when cvescan determines a
                                  vulnerability does not apply.

Finally, the JSON-format report may be converted to one of the following formats: CSV, text (YAML), or JUnit.

EXPORT_FORMAT Optional, Default: csv:

Specifies the output format for the report (either cyclonedx-json for CycloneDX VEX, csv for a comma-delimited text export, text for a YAML export, or junit for a JUnit test suite};

ANNOTATIONS Optional:

A file holding manual annotations, as decribed here; these annotations are combined with the fields from the input reports to provide final statuses for vulnerabilities in the exported report;

NAMEDREPORT Required:

The JSON report produced by a former invocation of cvescan scan-inventory or cvescan filter-report;

Only supported with CSV export format: this can be passed multiple times to consolidate reports, each with an associated name, employing syntax -i path/to/report_file:report_name.

- Each report must have a unique name.

- Naming on command line is however optional: `-i path/to/report_file` is kept as a valid syntax, in which case `report_file` will be used as report name.

- When more than one report is passed as argument, an extra column titled `Source Report Name` is added to output CSV file, repeating originating report name.

OUTPUT Optional:

The filename (or path) of the CycloneDX, CSV, text or JUnit report to be produced.

The run command

Usage: cvescan run [OPTIONS]

  Scans and filters

Options:
  -h, --help                      Show this message and exit.
  --format [cyclonedx-json|csv|text|yaml|junit]
                                  Output report format.
  -o, --output PATH               Output report path.
  --inventory PATH                Path to the inventory file or root directory
                                  (spdx specific).
  --inventory-format [cyclonedx-json|cvescan|spdx-json]
                                  Inventory file format.
  --annotations PATH              Manual annotations file path.
  --filter-cache PATH             Filter cache directory path.
  --git-dir PATH                  Yocto git download directory (typically
                                  $DL_DIR/git2).
  --keep-package TEXT             Scan package even if not on the image
                                  manifest.
  --uct-dir PATH                  Ubuntu CVE tracker directory path.
  --upstream-uri PATH             Mainline Linux kernel repository (may be a
                                  path to a local copy)
  --use-upstream-linux-ref TEXT   Overrides the git reference from the Yocto
                                  SBOM with the Linux kernel repo mirror
                                  specified from --upstream-uri with a commit
                                  reference <branch|tag|hash>
  --scope.transversal TEXT        Annotations scope 'transversal' attribute
  --scope.project TEXT            Annotations scope 'project' attribute
  --scope.component TEXT          Annotations scope 'component' attribute

To perform the scan, filter, and export operations in one step use the run command.

The serve-ui command

Usage: cvescan serve-ui [OPTIONS]

  Launches a local server for the CVE Scan Web Interface.

Options:
  -h, --help
  -p, --port PORT  Serves the UI on the specified port (default value : 8000)

This command launches a web server with the CVE Scan Web interface. Once launched point your favourite browser to https://localhost:PORT.

The configuration file

To simplify the CLI usage, you can use a dedicated configuration file.