Validate and format files
Check that your Vulnlog files are valid and in the canonical style before you commit them.
Validate
-
Run
vulnlog validatewith 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 -
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.
-
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.
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.