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

vulnlog.yaml

vulnlog.yaml

vulnlog.yml

vulnlog.yml

*.vl.yaml

acme-shop.vl.yaml

*.vl.yml

acme-shop.vl.yml

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

schemaVersion

String, "1"

Yes

None

Version of the Vulnlog format. The CLI also accepts "1.0" and the number 1. A newer version fails with Unsupported schema version '2'. Try updating vulnlog. A value that isn’t a version fails with Invalid schema version 'abc'. Without schemaVersion, the file fails with Missing schemaVersion.

project

Object

Yes

None

The organisation, project, and author. See Project and releases.

tags

List of tag objects

No

No tags

Labels you attach to entries and to release package URLs (PURLs). See Tags.

releases

List of release objects

Yes

None

The releases this file tracks. vulnlog init starts with an empty list. Each entry refers to releases from this list. See Project and releases.

vulnerabilities

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: [] that vulnlog init writes. 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 releases matters. See Project and releases.

  • By convention, vulnerabilities is 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 analysis and comment on an entry, description on a tag, and note on a resolution.

  • Commands that write the file use one canonical style: field order, list style, quoting, and blank lines. vulnlog fmt --check reports 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