vulnlog fmt

vulnlog fmt rewrites Vulnlog files in the canonical style, in place. With --check, it reports the files that aren’t in the canonical style and doesn’t change them.

Synopsis

vulnlog fmt [--check] <inputs>...
vulnlog fmt [--check] -

Arguments and options

Name Value Default Description

<inputs>

One or more Vulnlog files, or -

required

Files to format. - reads one file from stdin and writes the formatted file to stdout.

--check

none

off

Don’t write anything. List each file that isn’t in the canonical style, with the rule and line of each difference, and exit with code 3.

For global options and standard input and output, see Global options and Standard input and output.

Behaviour

The canonical style fixes the layout of a Vulnlog file: the schema header and --- at the top, the order of fields, and the style of each list and text value. Two people who change the same file get the same layout.

fmt removes YAML comments, which aren’t part of the format, and prints a warning when a file contains any. For the fields that hold notes, see File format.

fmt only needs a file it can parse. It formats a file that has validation errors and doesn’t report them. vulnlog validate checks the validation rules.

With several files, fmt writes none of them if one can’t be parsed. It names the file and exits with code 2.

vulnlog modify add and vulnlog modify copy write their files in the same canonical style.

Exit codes

Code When

0

Every file is formatted, or with --check, every file is already in the canonical style.

1

A general error. For the general errors, see Exit codes.

2

A file can’t be parsed.

3

With --check, at least one file isn’t in the canonical style.

Examples

Format a file that’s already canonical:

$ vulnlog fmt acme-shop.vl.yaml
Unchanged: acme-shop.vl.yaml

Check a copy of acme-shop.vl.yaml where someone wrote the releases of CVE-2023-32681 as a block list and added a comment:

$ vulnlog fmt --check acme-shop.vl.yaml
warning: acme-shop.vl.yaml: not canonically formatted
  [non-canonical-array-style] vulnerabilities[CVE-2023-32681].releases: Line 49: canonical style for this list is a flow array, e.g. key: [value].
  [comments-not-preserved] YAML comments are removed on write.

The exit code is 3. Format the file to fix it:

$ vulnlog fmt acme-shop.vl.yaml
warning: acme-shop.vl.yaml: contains YAML comments; they are removed on write
  hint: record notes in schema fields (e.g. comment, analysis)
Formatted: acme-shop.vl.yaml

Format from stdin to stdout:

$ vulnlog fmt - < acme-shop.vl.yaml > formatted.vl.yaml