Validate and format files

Check that your Vulnlog files are valid and in the canonical style before you commit them.

Before you start

  • One or more Vulnlog files, for example acme-shop.vl.yaml.

Validate

  1. Run vulnlog validate with one or more files:

    $ vulnlog validate acme-shop.vl.yaml
    info: acme-shop.vl.yaml: releases[4.4.0]: Unreferenced release ID '4.4.0'.
    1 info
    Validated: acme-shop.vl.yaml
  2. Read the messages. Each line names the level, the file, and the field it’s about:

    info: acme-shop.vl.yaml: releases[4.4.0]: Unreferenced release ID '4.4.0'.
    info: acme-shop.vl.yaml: tags[frontend]: Unreferenced tag ID 'frontend'.
    error: acme-shop.vl.yaml: vulnerabilities[CVE-2021-23337].tags[web]: References undefined tags 'web'. Defined tags: backend, container, frontend, worker
    1 error, 2 infos
      hint: ask for help at https://github.com/vulnlog/vulnlog/discussions/categories/q-a

    For what each level means, see Exit codes and messages.

  3. Fix every error: line, then validate again. For what a message means, see Troubleshooting.

To fail on warnings too, add --strict, and fix the warning: lines as well. In this copy of the file, the analysis date of CVE-2024-3094 is a day before its report date:

$ vulnlog validate --strict acme-shop.vl.yaml
info: acme-shop.vl.yaml: releases[4.4.0]: Unreferenced release ID '4.4.0'.
warning: acme-shop.vl.yaml: vulnerabilities[CVE-2024-3094].analyzed_at: Analyzed date '2026-07-01' is before earliest reported date '2026-07-02'.
1 warning, 1 info
  hint: ask for help at https://github.com/vulnlog/vulnlog/discussions/categories/q-a

Format

Every command that writes a Vulnlog file writes it in the canonical style. After you edit a file by hand, format it:

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

A file that’s already canonical shows Unchanged.

fmt removes YAML comments, except the # $schema: line at the top, and warns when it does:

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

Move such notes into comment or analysis before you format.

To check the format without changing the file, add --check. It lists what isn’t canonical. In this copy of the file, someone wrote the releases of Log4Shell as a block list:

$ vulnlog fmt --check acme-shop.vl.yaml
warning: acme-shop.vl.yaml: not canonically formatted
  [non-canonical-array-style] vulnerabilities[CVE-2021-44228].releases: Line 142: canonical style for this list is a flow array, e.g. key: [value].

For the canonical style, see File format.

Variants

If you use the Gradle plugin

Add your files to the vulnlog extension and run the tasks:

vulnlog {
    files.from("acme-shop.vl.yaml")
    validate {
        strict = true
    }
}
$ ./gradlew vulnlogValidate
$ ./gradlew vulnlogFormat
$ ./gradlew vulnlogFormat --check

For all task settings, see Gradle plugin.

If the file comes from another command

Pass - to read the file from standard input. fmt then writes the formatted file to standard output:

$ vulnlog validate - < acme-shop.vl.yaml
info: <stdin>: releases[4.4.0]: Unreferenced release ID '4.4.0'.
1 info
Validated: <stdin>

Check the result

Both commands end with exit code 0 when the files are fine. validate ends with 2 when a file has errors, or warnings with --strict. fmt --check ends with 3 when a file isn’t canonical. For all exit codes, see Exit codes and messages.

To run both checks on every pull request, see Run in CI pipelines.