File format
A Vulnlog file is a YAML document with five top-level keys. The CLI reads it only under certain file names, and an optional first-line comment links it to the JSON schema.
Synopsis
# $schema: https://vulnlog.dev/schema/vulnlog-v1.json
---
schemaVersion: "1"
project:
organization: Acme Corp
name: Acme Shop
author: Acme Product Security Team
tags:
- id: backend
description: Java server application
releases:
- id: 4.2.0
vulnerabilities:
- id: CVE-2022-42889
releases: [4.2.0]
packages: ["pkg:maven/org.apache.commons/commons-text@1.9"]
reports:
- reporter: dependency-check
tags: [backend]
File names
The CLI reads a file only when its name matches one of these patterns:
| Pattern | Example |
|---|---|
|
|
|
|
|
|
|
|
Any other name fails with File name must be [vulnlog|*.vl].[yaml|yml].
You can put the file anywhere in your repository.
You pass its path to every command, because the CLI doesn’t search for it.
- in place of the path reads the file from standard input.
See Standard input and output.
Schema header
The first line of the file can be a comment that names the JSON schema:
# $schema: https://vulnlog.dev/schema/vulnlog-v1.json
The header is optional.
Editors with YAML schema support use it for validation and completion, and the CLI ignores it.
vulnlog init writes the header into every new file.
Commands that write a file keep the header if the file has one, and always write it with the URL shown above.
See Set up your editor.
Document start
The document can start with ---, after the schema header if there is one.
The marker is optional, and vulnlog fmt adds it when it’s missing.
A file holds one YAML document.
Top-level keys
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
|
String, |
Yes |
None |
Version of the Vulnlog format.
The CLI also accepts |
|
Object |
Yes |
None |
The organisation, project, and author. See Project and releases. |
|
List of tag objects |
No |
No tags |
Labels you attach to entries and to release package URLs (PURLs). See Tags. |
|
List of release objects |
Yes |
None |
The releases this file tracks.
|
|
List of entries |
Yes |
None |
One entry per vulnerability. The list can be empty. See Vulnerabilities. |
Rules
-
Keys that the format doesn’t define fail with
Unknown property '<key>'. Try updating vulnlog.This applies at every level of the file. -
An empty file fails with
Empty YAML document. -
The CLI accepts empty lists, such as the
releases: []thatvulnlog initwrites. The JSON schema requires at least one item in every list, so an editor that checks the file against the schema marks an empty list. -
The order of
releasesmatters. See Project and releases. -
By convention,
vulnerabilitiesis listed newest first. The CLI doesn’t check or change this order. -
YAML comments other than the schema header aren’t part of the format. Commands that write the file remove them and print a warning. The fields for notes are
analysisandcommenton an entry,descriptionon a tag, andnoteon a resolution. -
Commands that write the file use one canonical style: field order, list style, quoting, and blank lines.
vulnlog fmt --checkreports where a file differs. See vulnlog fmt.
Examples
vulnlog init writes the smallest file that the CLI accepts:
# $schema: https://vulnlog.dev/schema/vulnlog-v1.json
---
schemaVersion: "1"
project:
organization: Acme Corp
name: Acme Shop
author: Acme Product Security Team
releases: []
vulnerabilities: []
The Acme Shop file uses every top-level key:
acme-shop.vl.yaml
# $schema: https://vulnlog.dev/schema/vulnlog-v1.json
---
schemaVersion: "1"
project:
organization: Acme Corp
name: Acme Shop
author: Acme Product Security Team
contact: security@acme.example
tags:
- id: backend
description: Java server application
- id: frontend
description: Web user interface
- id: worker
description: Python report worker
- id: container
description: Container image that bundles all components
releases:
- id: 4.2.0
published_at: 2026-03-02
purls:
- purl: "pkg:maven/com.acme/acme-shop-server@4.2.0"
tags: [backend]
- purl: "pkg:oci/acme-shop@sha256:cf9066b0fcef66d545007bd33b5d8d59e7434e37c2a23d19a3075fdb6f0b48b9"
tags: [container]
- id: 4.3.0
published_at: 2026-06-15
purls:
- purl: "pkg:maven/com.acme/acme-shop-server@4.3.0"
tags: [backend]
- purl: "pkg:oci/acme-shop@sha256:23a5bff22a95119dc4bcef9422a20038eb3c2fd355f03928b02791273ff1cc27"
tags: [container]
- id: 4.4.0
purls:
- purl: "pkg:maven/com.acme/acme-shop-server@4.4.0"
tags: [backend]
- purl: "pkg:oci/acme-shop@sha256:350f97615163b67cbff8b015e60c77c2cbb954b4d9ffa9d48254e216e54899c8"
tags: [container]
vulnerabilities:
- id: CVE-2023-32681
description: Proxy-Authorization header leak in requests
releases: [4.3.0]
packages: ["pkg:pypi/requests@2.28.2"]
reports:
- reporter: github-dependabot
at: 2026-07-14
tags:
- worker
- container
- id: CVE-2024-3094
name: XZ Utils backdoor
description: Backdoor in the liblzma library of XZ Utils
releases: [4.3.0]
packages: ["pkg:deb/debian/xz-utils@5.4.1"]
reports:
- reporter: other
at: 2026-07-02
source: Customer inquiry
tags: [container]
analysis: >-
The container image is based on Debian 12, which ships xz-utils 5.4.1. The backdoor is only in the upstream releases 5.6.0
and 5.6.1.
analyzed_at: 2026-07-02
verdict: not affected
justification: vulnerable code not present
- id: CVE-2022-42889
name: Text4Shell
description: Remote code execution through string interpolation in Apache Commons Text
releases:
- 4.2.0
- 4.3.0
packages: ["pkg:maven/org.apache.commons/commons-text@1.9"]
reports:
- reporter: dependency-check
at: 2026-05-20
tags:
- backend
- container
analysis: >-
Acme Shop only uses StringEscapeUtils from Commons Text. The server never calls StringSubstitutor, which performs the vulnerable
interpolation.
analyzed_at: 2026-05-21
verdict: not affected
justification: vulnerable code not in execute path
- id: CVE-2022-22965
name: Spring4Shell
description: Remote code execution through data binding in Spring Framework
releases:
- 4.2.0
- 4.3.0
packages: ["pkg:maven/org.springframework/spring-beans@5.3.15"]
reports:
- reporter: trivy
at: 2026-04-07
suppress:
expires_at: 2027-03-31
tags:
- backend
- container
analysis: >-
Acme Shop runs as a Spring Boot executable JAR on JDK 17. The published exploit needs a WAR deployment on Apache Tomcat,
but Spring advises all users to upgrade.
analyzed_at: 2026-04-08
verdict: affected
severity: medium
disposition: will fix
comment: Planned for 4.4.0 together with the Spring Boot update.
- id: CVE-2021-23337
description: Command injection through the template function in lodash
releases:
- 4.2.0
- 4.3.0
packages: ["pkg:npm/lodash@4.17.20"]
reports:
- reporter: npm-audit
at: 2026-03-10
suppress: {}
tags: [frontend]
analysis: >-
The template function is only used in the admin interface, with templates that administrators write. Administrators can
already change the shop configuration, so the injection gives them no additional access. The admin interface is removed
in Acme Shop 5.0.
analyzed_at: 2026-03-12
verdict: affected
severity: low
disposition: wont fix
- id: CVE-2021-44228
name: Log4Shell
description: Remote code execution through JNDI lookups in Apache Log4j
aliases: [GHSA-jfh8-c2jp-5v3q]
releases: [4.2.0]
packages: ["pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1"]
reports:
- reporter: grype
at: 2026-03-10
- reporter: other
at: 2026-03-11
source: Customer support request
tags:
- backend
- container
analysis: >-
The server logs the User-Agent header with log4j-core 2.14.1. A crafted header triggers a JNDI lookup and runs attacker-controlled
code.
analyzed_at: 2026-03-11
verdict: affected
severity: critical
disposition: will fix
resolution:
in: 4.3.0
at: 2026-06-15
note: Updated log4j-core from 2.14.1 to 2.17.1