Vulnlog CLI

The vulnlog command reads and writes Vulnlog files. Each task is a command, and some commands are grouped under report, modify, and vex.

Synopsis

vulnlog [<global-options>] <command> [<options>] [<files>...]

Global options go before the command. Command options and files go after it, in any order.

$ vulnlog -v report impact acme-shop.vl.yaml --as-of 4.3.0

vulnlog without arguments, or any command with --help, prints its usage.

Commands

Command Description

vulnlog init

Create a Vulnlog file with only the required sections.

vulnlog validate

Check Vulnlog files and report errors, warnings, and infos.

vulnlog fmt

Rewrite Vulnlog files in the canonical style, or check that they’re in it.

vulnlog modify add

Add a vulnerability entry, or update an existing one, from the command line.

vulnlog modify copy

Copy vulnerability entries from one Vulnlog file into others.

vulnlog suppress

Generate suppression files for your scanners.

vulnlog report impact

Generate an HTML report of how vulnerabilities affect your releases.

vulnlog report changelog

List the vulnerabilities each release fixed, as text or Markdown.

vulnlog vex openvex

Generate OpenVEX documents, which tell your customers' tools whether a release is affected by a vulnerability. Incubating.

Global options

Name Value Default Description

--version

none

none

Print the version, for example vulnlog version 0.19.0, and exit.

-v, --verbose

none

off

Print verbose: diagnostic lines on stderr. Repeat it as -vv to also print debug: lines and the full stack trace of an unexpected error. A third -v adds nothing.

-q, --quiet

none

off

Don’t print status lines such as Wrote: vex.json. Errors, warnings, and infos still print, except info: no fixed vulnerabilities to report of report changelog. You can’t combine it with -v.

-h, --help

none

none

Print the usage of vulnlog or of the command it follows, and exit.

For the message levels and the exit codes, see Exit codes and messages.

Input files

Commands read the Vulnlog files you name as arguments. A file name must follow the naming rules in File format, otherwise the command stops before it reads the file.

init reads no file. modify add reads zero or more files. suppress and vex openvex read one file. modify copy reads one source file and one or more target files. validate, fmt, and the report commands read one or more files. The report commands merge their files into one report, and every file must have the same project block.

Standard input and output

- in place of a file name reads the Vulnlog file from stdin:

$ vulnlog validate - < acme-shop.vl.yaml

You can pass - once, and not together with file names. validate, fmt, suppress, the report commands, and vex openvex accept -. modify add and modify copy write to their files, so they need real files. In messages, stdin appears as <stdin>.

-o - writes the output to stdout. init and report changelog write to stdout by default.

$ vulnlog suppress acme-shop.vl.yaml --reporter trivy -o - > .trivyignore.yaml

Stdout carries only the output: a generated file, a report, or formatted YAML. Every message goes to stderr, at every verbosity. Redirect stderr to keep the messages, for example 2> vulnlog.log.

Filter options

suppress, report impact, and report changelog accept these options to select entries. Each filter narrows the selection, so combined filters select only entries that match all of them.

Name Value Default Description

--reporter

A reporter, for example trivy

all reporters

Select entries with a report from this reporter. For the values, see Supported scanners.

--as-of

A release ID, for example 4.3.0

all releases

Show the state as of this release. The selection covers this release and every release listed before it. A resolution in a later release doesn’t count yet.

--tag

A tag ID, for example backend

all entries, tagged or not

Select entries with this tag. Repeat the option to select entries with any of the tags.

An unknown reporter, release, or tag stops the command with exit code 5. A hint lists the releases or tags the file knows, or all supported reporters:

$ vulnlog report impact acme-shop.vl.yaml --as-of 4.5.0
error: Release not found: 4.5.0
  hint: Known releases: 4.2.0, 4.3.0, 4.4.0

With -v, a command shows what a filter matched. This command writes the suppression file to /dev/null and shows only the messages:

$ vulnlog -v suppress acme-shop.vl.yaml --as-of 4.2.0 --reporter trivy -o - > /dev/null
verbose: parsed acme-shop.vl.yaml: schema version 1, releases: 3, tags: 4, vulnerabilities: 6
verbose: as-of filter expanded to releases: 4.2.0
verbose: reporter filter: trivy
verbose: wrote <stdout>: trivy format, 1 entry