Support several release lines

When you support several release lines of a product at once, keep one Vulnlog file per line. Each line then has its own releases, verdicts, and suppression files, and you can still report on all lines together.

If each release replaces the one before and you only support the latest, you don’t need this guide. Keep one Vulnlog file, for example vulnlog.yaml, and add each release to it.

Before you start

  • A Vulnlog file for your current release line. In this guide, that’s acme-shop.vl.yaml with the 4.x releases of Acme Shop.

  • A second release line you still support. Acme Shop still ships security updates for 3.x.

Add a file for the second release line

  1. Create a file for the older line next to the existing one, on your main branch. Name it <project>-<line>.vl.yaml, so Vulnlog recognises it and the name shows the line:

    acme-shop.vl.yaml      4.x
    acme-shop-3.vl.yaml    3.x

    For the file names Vulnlog accepts, see File format.

  2. Copy project and the tags the line uses from the existing file, and list the releases of this line, oldest first. Use the same project values in every file, otherwise you can’t combine the files in one report. See Input files.

    # $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: container
        description: Container image that bundles all components
    
    releases:
      - id: 3.9.0
        published_at: 2025-11-04
        purls:
          - purl: "pkg:maven/com.acme/acme-shop-server@3.9.0"
            tags: [backend]
          - purl: "pkg:oci/acme-shop@sha256:a648cf45d8082c7e71693eaf8eeefa09b69ede432d33e14eb5bc468010bc82d0"
            tags: [container]
      - id: 3.9.1
        published_at: 2026-03-20
        purls:
          - purl: "pkg:maven/com.acme/acme-shop-server@3.9.1"
            tags: [backend]
          - purl: "pkg:oci/acme-shop@sha256:b3d57ecd7f8cce0a830f86394d16a4361c849d1401e68a3bd3e74cdd1c53058c"
            tags: [container]
  3. Record the vulnerabilities that affect this line. Acme Shop 3.9.0 shipped the vulnerable log4j-core, and 3.9.1 fixed it:

    vulnerabilities:
    
      - id: CVE-2021-44228
        name: Log4Shell
        description: Remote code execution through JNDI lookups in Apache Log4j
        aliases: [GHSA-jfh8-c2jp-5v3q]
        releases: [3.9.0]
        packages: ["pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1"]
        reports:
          - reporter: grype
            at: 2026-03-10
        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: 3.9.1
          at: 2026-03-20
          note: Updated log4j-core from 2.14.1 to 2.17.1
  4. Validate both files:

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

    The info line only tells you that no entry refers to 4.4.0 yet.

Copy an entry to another release line

When a vulnerability in one line also affects another, copy the entry instead of writing it again. Spring4Shell is recorded for 4.x and also affects 3.x:

$ vulnlog modify copy acme-shop.vl.yaml acme-shop-3.vl.yaml --vuln-id CVE-2022-22965
Copied: 1 entry to acme-shop-3.vl.yaml

The copy keeps the analysis, verdict, reports, and suppression. Its releases is set to the last release of the target file:

  - id: CVE-2022-22965
    name: Spring4Shell
    description: Remote code execution through data binding in Spring Framework
    releases: [3.9.1]
    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.

Review the copy before you commit it. Add earlier releases of the line to releases if they’re affected too, and update text that only fits the other line, such as this comment. Name several targets to copy to more than one file, and repeat --vuln-id to copy several entries. For how modify copy merges an entry that already exists in the target, see vulnlog modify copy.

Variants

If each release line has its own branch

You can keep a vulnlog.yaml on each release branch instead, next to the code it describes. Each branch then records only its own releases.

To copy an entry between branches, check out the other branch in a second directory with git worktree, and copy between the two files:

$ git worktree add ../acme-shop-3 release/3.x
$ vulnlog modify copy vulnlog.yaml ../acme-shop-3/vulnlog.yaml --vuln-id CVE-2022-22965
Copied: 1 entry to ../acme-shop-3/vulnlog.yaml

Commit the change on each branch.

If you use the Gradle plugin

Add both files to the vulnlog block. Validation, formatting, and the reports then cover both lines. vulnlogSuppress reads one file only, so limit it to the main file and register a second task for the 3.x line:

import dev.vulnlog.gradle.VulnlogSuppressTask

vulnlog {
    files.from("acme-shop.vl.yaml", "acme-shop-3.vl.yaml")
}

tasks.named<VulnlogSuppressTask>("vulnlogSuppress") {
    files.setFrom("acme-shop.vl.yaml")
}

tasks.register<VulnlogSuppressTask>("vulnlogSuppress3") {
    group = "vulnlog"
    files.from("acme-shop-3.vl.yaml")
    outputDir = layout.buildDirectory.dir("vulnlog/suppressions-3")
}

vulnlogSuppress writes to build/vulnlog/suppressions, and vulnlogSuppress3 to build/vulnlog/suppressions-3. For the properties of a task you register yourself, see Tasks you register yourself.

If you maintain several products

Give each product its own Vulnlog file with its own project. Generate the reports of each product from its own file. The report commands only combine files that share the same project values, and stop with an error for files of different products.

Check the result

  • vulnlog validate passes for every file.

  • Generate the suppression files of each line from its own file into its own directory, for example vulnlog suppress acme-shop-3.vl.yaml --output-dir suppressions/3.x. The directory must exist. In the same directory, the files of one line overwrite those of the other. See Generate suppression files.

  • To see all lines in one report, pass all files to vulnlog report impact or vulnlog report changelog. See Generate reports. If the project values differ, the command stops with all input files must share the same project metadata.